developer-guide-shopping-agents

BuyWhere API Developer Guide

A comprehensive technical guide to building AI-powered shopping agents and integrations with the BuyWhere product catalog API. This guide covers authentication, all core endpoints, SDK usage, MCP integration, rate limits, and production best practices.

Overview
Getting Started
- Authentication
- Your First API Call
Core Endpoints
Advanced Features
SDK Reference
- JavaScript/TypeScript
- Python
MCP Integration
- Claude Desktop
- Other MCP Clients
Rate Limits & Best Practices
Affiliate Integration
Use Case Walkthroughs
Error Handling
Data Model

Overview

The BuyWhere Catalog API is an agent-native product data infrastructure serving AI shopping agents across Southeast Asia. The API aggregates product data from Lazada, Shopee, Amazon SG, Carousell, Qoo10, Zalora, and 20+ other platforms into a unified, queryable interface.

Key capabilities:

80,000+ products indexed across Singapore and Southeast Asia
Full-text search with semantic matching and filtering
Cross-platform price comparison with confidence scores
Real-time deal discovery with discount tracking
Price history analytics with prediction models
Multi-currency support (SGD, USD, EUR, MYR, IDR, THB, PHP, VND)

Base URL:

https://api.buywhere.ai

Getting Started

Authentication

The BuyWhere API uses Bearer token authentication. All requests require an Authorization header with your API key.

Getting Your API Key

Option 1: Developer Signup (Recommended)

curl -X POST https://api.buywhere.ai/v1/developers/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "your-password-here",
    "name": "Your Name"
  }'

Response:

{
  "api_key": "bw_live_abc123xyz789...",
  "developer_id": "dev_abc123",
  "email": "developer@example.com",
  "created_at": "2026-04-16T10:00:00Z"
}

Option 2: Bootstrap First Key (First-Time Setup Only)

If no API keys exist in the system, you can bootstrap the first key:

curl -X POST https://api.buywhere.ai/v1/keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Key",
    "permissions": ["read", "search"]
  }'

Using Your API Key

Include the API key in every request:

curl https://api.buywhere.ai/v1/products/stats \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Key Management

List your API keys:

curl https://api.buywhere.ai/v1/keys \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Rotate a key:

curl -X POST https://api.buywhere.ai/v1/keys/{key_id}/rotate \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Revoke a key:

curl -X DELETE https://api.buywhere.ai/v1/keys/{key_id} \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Your First API Call

Verify your API key and get catalog statistics:

curl https://api.buywhere.ai/v1/products/stats \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "total_products": 80564,
  "sources": {
    "lazada_sg": 34911,
    "carousell_sg": 27371,
    "zalora_sg": 10679,
    "mustafa_sg": 4184,
    "shopee_sg": 1234,
    "qoo10_sg": 50
  },
  "categories": {
    "Electronics": 38295,
    "Fashion": 16813,
    "Health & Beauty": 5739,
    "Mobiles & Tablets": 4422,
    "Home & Living": 4013
  }
}

Core Endpoints

Search Products

The search endpoint provides full-text search with filtering, sorting, and faceting.

Endpoint: GET /v1/search

# Basic search
curl "https://api.buywhere.ai/v1/search?q=iphone+15" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Search with filters
curl "https://api.buywhere.ai/v1/search?q=iphone+15&category=Electronics&max_price=1500&platform=shopee_sg&in_stock=true" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Search with pagination
curl "https://api.buywhere.ai/v1/search?q=laptop&limit=20&offset=40" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Search with currency conversion
curl "https://api.buywhere.ai/v1/search?q=macbook&currency=USD" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Multi-country search
curl "https://api.buywhere.ai/v1/search?q=playstation+5&country=SG,MY" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Include faceting for filter counts
curl "https://api.buywhere.ai/v1/search?q=headphones&include_facets=true" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Query Parameters:

Parameter	Type	Description
`q`	string	Full-text search query (max 500 chars)
`category`	string	Filter by category
`brand`	string	Filter by brand
`min_price`	number	Minimum price filter
`max_price`	number	Maximum price filter
`platform`	string	Filter by platform (e.g., `shopee_sg`, `lazada_sg`)
`country`	string	Filter by country code(s), comma-separated (e.g., `SG,MY`)
`in_stock`	boolean	Filter by availability
`currency`	string	Target currency for price conversion
`lang`	string	Query language for translation (`ms`, `th`, `vi`, `id`)
`limit`	integer	Results per page (1-100, default 20)
`offset`	integer	Pagination offset (0-10000)
`sort_by`	string	Sort order: `relevance`, `price_asc`, `price_desc`, `newest`
`include_facets`	boolean	Include facet counts in response

Response:

{
  "total": 847,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "items": [
    {
      "id": 12345,
      "name": "Apple iPhone 15 Pro Max 256GB Natural Titanium",
      "price": 1649.00,
      "currency": "SGD",
      "source": "shopee_sg",
      "buy_url": "https://buywhere.ai/redirect/12345",
      "affiliate_url": "https://buywhere.ai/affiliate/12345?api_key=bw_live_xxx",
      "image_url": "https://cdn.buywhere.ai/img/12345.jpg",
      "category": "Mobiles & Tablets > Smartphones",
      "category_path": ["Mobiles & Tablets", "Smartphones"],
      "is_available": true,
      "rating": 4.8,
      "review_count": 2341,
      "brand": "Apple",
      "metadata": {
        "sku": "iphone-15-pro-max-256",
        "storage": "256GB",
        "color": "Natural Titanium"
      }
    }
  ],
  "facets": {
    "brand": {"Apple": 45, "Samsung": 32, "Google": 12},
    "price_range": {"$500-$1000": 120, "$1000-$1500": 280, "$1500+": 447}
  }
}

Semantic Search

For natural language queries that benefit from understanding intent:

Endpoint: GET /v1/search/semantic

curl "https://api.buywhere.ai/v1/search/semantic?q=phone+for+gaming+and+photography&max_price=1000" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Search Suggestions (Autocomplete)

Get autocomplete suggestions for search queries:

Endpoint: GET /v1/search/suggest

curl "https://api.buywhere.ai/v1/search/suggest?q=sony+wh" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "suggestions": [
    "sony wh-1000xm5",
    "sony wh-ch520",
    "sony wh-xb910n"
  ]
}

Search Filters

Get available filter options with counts for building dynamic filter UIs:

Endpoint: GET /v1/search/filters

curl "https://api.buywhere.ai/v1/search/filters?q=headphones" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Search History

Get search history for the authenticated API key:

Endpoint: GET /v1/search/history

curl "https://api.buywhere.ai/v1/search/history?limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Product Details

Get Product by ID

Endpoint: GET /v1/products/{product_id}

# Get product details
curl "https://api.buywhere.ai/v1/products/12345" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Get product with currency conversion
curl "https://api.buywhere.ai/v1/products/12345?currency=USD" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "id": 12345,
  "sku": "iphone-15-pro-max-256-nat",
  "source": "shopee_sg",
  "source_url": "https://shopee.sg/iphone-15-pro-max-256gb",
  "name": "Apple iPhone 15 Pro Max 256GB Natural Titanium",
  "description": "The most powerful iPhone ever with A17 Pro chip...",
  "price": 1649.00,
  "original_price": 1899.00,
  "currency": "SGD",
  "buy_url": "https://buywhere.ai/redirect/12345",
  "affiliate_url": "https://buywhere.ai/affiliate/12345?api_key=bw_live_xxx",
  "image_url": "https://cdn.buywhere.ai/img/12345.jpg",
  "images": [
    "https://cdn.buywhere.ai/img/12345_1.jpg",
    "https://cdn.buywhere.ai/img/12345_2.jpg"
  ],
  "category": "Mobiles & Tablets > Smartphones",
  "category_path": ["Mobiles & Tablets", "Smartphones", "iPhone"],
  "brand": "Apple",
  "is_available": true,
  "stock_level": "high",
  "rating": 4.8,
  "review_count": 2341,
  "seller": {
    "name": "Apple Authorized Store SG",
    "rating": 4.9
  },
  "shipping": {
    "estimated_days": "1-3",
    "cost": 0
  },
  "metadata": {
    "sku": "iphone-15-pro-max-256-nat",
    "storage": "256GB",
    "color": "Natural Titanium",
    "model": "iPhone 15 Pro Max"
  },
  "updated_at": "2026-04-16T08:30:00Z"
}

List Products

List all products with pagination and filtering:

Endpoint: GET /v1/products/

# List products with cursor pagination (recommended for large catalogs)
curl "https://api.buywhere.ai/v1/products/?limit=20&after=0&sort_by=relevance" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# List with offset pagination (deprecated)
curl "https://api.buywhere.ai/v1/products/?limit=20&offset=0" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Filter by category
curl "https://api.buywhere.ai/v1/products/?category=Electronics&limit=50" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Filter with currency
curl "https://api.buywhere.ai/v1/products/?category=Fashion&currency=USD" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (1-100, default 20)
`offset`	integer	Pagination offset (0-10000, deprecated)
`after`	integer	Cursor for pagination - return products with id > after
`sort_by`	string	Sort: `relevance`, `price_asc`, `price_desc`, `newest`
`category`	string	Filter by category
`currency`	string	Target currency

Get Random Products

Get N random products for agent exploration and testing:

Endpoint: GET /v1/products/random

curl "https://api.buywhere.ai/v1/products/random?limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Price Comparison

Compare Product Across Platforms

Endpoint: GET /v1/products/compare

# Find and compare same product across sources
curl "https://api.buywhere.ai/v1/products/compare?q=iphone+15+pro+256gb&limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "query": "iphone 15 pro 256gb",
  "seed_products": [
    {
      "id": 12345,
      "name": "iPhone 15 Pro Max 256GB",
      "price": 1649.00,
      "source": "shopee_sg"
    }
  ],
  "comparisons": [
    {
      "seed_id": 12345,
      "matches": [
        {
          "product_id": 12345,
          "source": "shopee_sg",
          "price": 1649.00,
          "confidence": 0.96,
          "shipping_cost": 0,
          "total_cost": 1649.00,
          "delivery_days": "1-3",
          "seller_rating": 4.9
        },
        {
          "product_id": 67890,
          "source": "lazada_sg",
          "price": 1699.00,
          "confidence": 0.94,
          "shipping_cost": 0,
          "total_cost": 1699.00,
          "delivery_days": "1-2",
          "seller_rating": 4.8
        }
      ],
      "savings_pct": 2.94,
      "cheapest": {
        "product_id": 12345,
        "source": "shopee_sg",
        "price": 1649.00
      }
    }
  ]
}

Batch Compare Multiple Products

Endpoint: POST /v1/products/compare

curl -X POST "https://api.buywhere.ai/v1/products/compare" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"q": "iphone 15 pro 256gb", "limit": 5},
      {"q": "samsung s24 ultra", "limit": 5}
    ],
    "min_price": 0,
    "max_price": 2000
  }'

Compare Two Products Directly

Endpoint: POST /v1/products/compare/diff

curl -X POST "https://api.buywhere.ai/v1/products/compare/diff" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [12345, 67890]
  }'

Get Product Matches Across Platforms

Endpoint: GET /v1/products/{product_id}/matches

curl "https://api.buywhere.ai/v1/products/12345/matches?min_confidence=0.5&limit=20" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Price Comparison for Product

Endpoint: GET /v1/products/{product_id}/price-comparison

curl "https://api.buywhere.ai/v1/products/12345/price-comparison" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Find Best Price Across All Platforms

Endpoint: GET /v1/products/best-price

curl "https://api.buywhere.ai/v1/products/best-price?q=sony+wh-1000xm5" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Advanced Features

Deals & Price Drops

Get Deals (Discounted Products)

Endpoint: GET /v1/deals

# Find products with discounts
curl "https://api.buywhere.ai/v1/deals?min_discount_pct=20&category=Electronics" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Filter by platform
curl "https://api.buywhere.ai/v1/deals?platform=shopee_sg&min_discount_pct=30" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "deals": [
    {
      "id": 12345,
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "price": 349.00,
      "original_price": 449.00,
      "discount_pct": 22,
      "source": "lazada_sg",
      "buy_url": "https://buywhere.ai/redirect/12345",
      "image_url": "https://cdn.buywhere.ai/img/12345.jpg",
      "category": "Electronics > Audio > Headphones",
      "is_available": true,
      "rating": 4.7,
      "review_count": 892
    }
  ],
  "total": 156,
  "limit": 20,
  "offset": 0
}

Get Price Drops (Recent Decreases)

Endpoint: GET /v1/deals/price-drops

# Find products with recent price drops
curl "https://api.buywhere.ai/v1/deals/price-drops?days=7&min_drop_pct=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Best Deals Across Sources

Endpoint: GET /v1/deals/best

curl "https://api.buywhere.ai/v1/deals/best?min_savings_pct=20&category=Electronics" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Bulk Operations

Batch Product Lookup by IDs

Endpoint: POST /v1/products/batch

curl -X POST "https://api.buywhere.ai/v1/products/batch" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [12345, 67890, 11111, 22222, 33333]
  }'

Bulk Lookup by SKU, UPC, or URL

Endpoint: POST /v1/products/bulk-lookup

curl -X POST "https://api.buywhere.ai/v1/products/bulk-lookup" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "lookups": [
      {"type": "sku", "value": "iphone-15-pro-max-256"},
      {"type": "upc", "value": "194253397731"},
      {"type": "url", "value": "https://shopee.sg/iphone-15-pro-max"}
    ]
  }'

Bulk Import Products (Merchant Self-Serve)

Endpoint: POST /v1/products/bulk

curl -X POST "https://api.buywhere.ai/v1/products/bulk" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "name": "Product Name",
        "price": 99.99,
        "sku": "SKU-001",
        "category": "Electronics",
        "buy_url": "https://merchant.example.com/product"
      }
    ]
  }'

Bulk Check Availability

Endpoint: POST /v1/products/availability

curl -X POST "https://api.buywhere.ai/v1/products/availability" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [12345, 67890, 11111]
  }'

Export Products

Endpoint: GET /v1/products/export

# Export as JSON
curl "https://api.buywhere.ai/v1/products/export?format=json&category=Electronics&limit=100" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Export as CSV
curl "https://api.buywhere.ai/v1/products/export?format=csv&source=lazada_sg&limit=500" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Stream Products Feed (NDJSON)

Endpoint: GET /v1/products/feed

# Stream all products updated since timestamp
curl "https://api.buywhere.ai/v1/products/feed?updatedSince=2026-04-01T00:00:00Z&limit=1000" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Price History & Analytics

Get Price History

Endpoint: GET /v1/products/{product_id}/price-history

# Get 30-day price history (default)
curl "https://api.buywhere.ai/v1/products/12345/price-history" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Get 90-day history for specific platform
curl "https://api.buywhere.ai/v1/products/12345/price-history?days=90&platform=shopee_sg" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "product_id": 12345,
  "platform": "shopee_sg",
  "history": [
    {"date": "2026-04-16", "price": 1649.00},
    {"date": "2026-04-15", "price": 1649.00},
    {"date": "2026-04-14", "price": 1699.00},
    {"date": "2026-04-10", "price": 1749.00}
  ],
  "current_price": 1649.00,
  "lowest_price": 1599.00,
  "highest_price": 1899.00,
  "average_price": 1699.00
}

Get Price Statistics

Endpoint: GET /v1/products/{product_id}/price-stats

curl "https://api.buywhere.ai/v1/products/12345/price-stats" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "product_id": 12345,
  "current_price": 1649.00,
  "lowest_30d": 1599.00,
  "highest_30d": 1899.00,
  "average_30d": 1699.00,
  "price_change_30d": -8.5,
  "volatility": "medium",
  "trend": "decreasing"
}

Get Price Prediction

Endpoint: GET /v1/products/{product_id}/price-prediction

curl "https://api.buywhere.ai/v1/products/12345/price-prediction" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "product_id": 12345,
  "current_price": 1649.00,
  "predicted_price_7d": 1629.00,
  "predicted_price_30d": 1579.00,
  "confidence": 0.78,
  "trend": "slightly_decreasing",
  "recommendation": "wait"
}

Product Recommendations & Discovery

Find Similar Products

Endpoint: GET /v1/products/{product_id}/similar

curl "https://api.buywhere.ai/v1/products/12345/similar?limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Alternatives (Cheaper in Same Category)

Endpoint: GET /v1/products/{product_id}/alternatives

curl "https://api.buywhere.ai/v1/products/12345/alternatives?limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Bundle Suggestions

Endpoint: GET /v1/products/{product_id}/bundles

curl "https://api.buywhere.ai/v1/products/12345/bundles?limit=5" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get "Also Searched" Products

Endpoint: GET /v1/products/{product_id}/also-searched

curl "https://api.buywhere.ai/v1/products/12345/also-searched?limit=10" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Trending Products

Endpoint: GET /v1/products/trending

# Get trending products (default: 7 days, 50 items)
curl "https://api.buywhere.ai/v1/products/trending" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

# Custom period and category
curl "https://api.buywhere.ai/v1/products/trending?period=24h&category=Electronics&limit=25" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Product Availability & Stock

Get Product Availability Across Platforms

Endpoint: GET /v1/products/{product_id}/availability

curl "https://api.buywhere.ai/v1/products/12345/availability?force_refresh=false" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Check URL Availability (Lightweight)

Endpoint: GET /v1/products/{product_id}/url-availability

curl "https://api.buywhere.ai/v1/products/12345/url-availability?force_refresh=true" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Get Product Stock Level

Endpoint: GET /v1/products/{product_id}/stock

curl "https://api.buywhere.ai/v1/products/12345/stock" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Product Reviews

Get Product Reviews Aggregation

Endpoint: GET /v1/products/{product_id}/reviews

curl "https://api.buywhere.ai/v1/products/12345/reviews" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Response:

{
  "product_id": 12345,
  "total_reviews": 2341,
  "average_rating": 4.8,
  "rating_distribution": {
    "5": 1873,
    "4": 351,
    "3": 82,
    "2": 23,
    "1": 12
  },
  "reviews_by_platform": [
    {"platform": "shopee_sg", "count": 1200, "avg_rating": 4.9},
    {"platform": "lazada_sg", "count": 800, "avg_rating": 4.7}
  ],
  "top_keywords": ["fast delivery", "genuine product", "good quality"]
}

Product Questions & Answers

Submit a Question

Endpoint: POST /v1/products/{product_id}/questions

curl -X POST "https://api.buywhere.ai/v1/products/12345/questions" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Does this product support 5G connectivity?"
  }'

List Questions for a Product

Endpoint: GET /v1/products/{product_id}/questions

curl "https://api.buywhere.ai/v1/products/12345/questions?page=1&page_size=20" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Submit an Answer

Endpoint: POST /v1/products/{product_id}/questions/{question_id}/answers

curl -X POST "https://api.buywhere.ai/v1/products/12345/questions/789/answers" \
  -H "Authorization: Bearer bw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "Yes, this model supports 5G connectivity on all major Singapore carriers."
  }'

Track Product Clicks

Endpoint: POST /v1/products/{product_id}/click

curl -X POST "https://api.buywhere.ai/v1/products/12345/click" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Returns the affiliate redirect URL for tracking.

SDK Reference

JavaScript/TypeScript

Install the SDK:

npm install @buywhere/sdk

Initialize and use:

import { BuyWhereClient } from "@buywhere/sdk";

const client = new BuyWhereClient("bw_live_your_api_key");

// Search products
const searchResult = await client.search({
  q: "iphone 15 pro",
  category: "Electronics",
  limit: 10
});

console.log(`Found ${searchResult.total} products`);
searchResult.items.forEach(product => {
  console.log(`${product.name} - ${product.currency} ${product.price}`);
});

// Get product details
const product = await client.getProduct(12345);
console.log(`Product: ${product.name}, Price: ${product.price}`);

// Compare prices
const comparison = await client.compare(12345);
console.log(`Found ${comparison.matches.length} listings`);

// Get deals
const deals = await client.getDeals({
  category: "Electronics",
  minDiscount: 20
});

deals.deals.forEach(deal => {
  console.log(`${deal.name}: ${deal.discount_pct}% off`);
});

// Batch lookup
const products = await client.batchLookup([12345, 67890, 11111]);

// Price history
const history = await client.getPriceHistory(12345, { days: 30 });
console.log(`30-day range: ${history.lowest_price} - ${history.highest_price}`);

Python

Install the SDK:

pip install buywhere-sdk

Initialize and use:

from buywhere import BuyWhereClient

client = BuyWhereClient("bw_live_your_api_key")

# Search products
result = client.search(
    q="iphone 15 pro",
    category="Electronics",
    limit=10
)

print(f"Found {result['total']} products")
for product in result['items']:
    print(f"{product['name']} - {product['currency']} {product['price']}")

# Get product details
product = client.get_product(12345)
print(f"Product: {product['name']}, Price: {product['price']}")

# Compare prices
comparison = client.compare(12345)
print(f"Found {len(comparison['matches'])} listings")

# Get deals
deals = client.get_deals(
    category="Electronics",
    min_discount_pct=20
)

for deal in deals['deals']:
    print(f"{deal['name']}: {deal['discount_pct']}% off")

# Batch lookup
products = client.batch_lookup([12345, 67890, 11111])

# Price history
history = client.get_price_history(12345, days=30)
print(f"30-day range: {history['lowest_price']} - {history['highest_price']}")

MCP Integration

The BuyWhere MCP server allows AI assistants like Claude Desktop, GPT-4, and other MCP-compatible clients to access BuyWhere functionality through the Model Context Protocol.

Claude Desktop

Installation

Install the BuyWhere MCP server:

# Clone the repository
git clone https://github.com/buywhere/buywhere-mcp.git
cd buywhere-mcp

# Install dependencies
npm install

# Build the server
npm run build

Configure Claude Desktop:

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the BuyWhere MCP server:

{
  "mcpServers": {
    "buywhere": {
      "command": "node",
      "args": ["/path/to/buywhere-mcp/dist/index.js"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_your_api_key_here"
      }
    }
  }
}

MCP Tools Available

Once configured, Claude can use these tools:

search_products - Search by keyword, category, price range
get_product - Get full product details by ID
compare_prices - Compare product across platforms
get_deals - Find discounted products
get_categories - Browse product categories
get_affiliate_link - Generate tracked purchase links
track_click - Track product click for analytics

Usage Examples

Example 1: Find Best Price

"Find me the best price for AirPods Pro 2 across Singapore platforms"

Claude will use search_products and compare_prices to find the best deal.

Example 2: Compare Products

"Compare iPhone 15 prices on Shopee vs Lazada"

Claude will use compare_prices filtered to specific platforms.

Example 3: Find Deals Under Budget

"Show me electronics under SGD 100 with high availability"

Claude will use search_products with max_price and in_stock filters.

Other MCP Clients

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "buywhere": {
      "command": "node",
      "args": ["/path/to/buywhere-mcp/dist/index.js"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_your_api_key_here"
      }
    }
  }
}

VS Code Copilot

MCP integration for VS Code is available through the MCP extension marketplace.

Rate Limits & Best Practices

Expected Latency by Endpoint

Understanding latency helps you design responsive agent workflows:

Endpoint	Baseline p95	Heavy Load p95	Notes
`GET /v1/products/{id}`	< 10ms	< 200ms	Fastest endpoint
`GET /v1/products/{sku}`	< 50ms	< 600ms	SKU lookup with variants
`GET /v1/products`	< 100ms	< 1000ms	Listing with pagination
`GET /v1/search`	< 150ms	< 1200ms	Full-text search
`GET /v2/agents/search`	< 300ms	< 800ms	AI-enhanced search
`GET /v1/deals`	< 100ms	< 700ms	Deal aggregation

Baseline: Single request, warm cache, low traffic Heavy Load: 1000+ concurrent requests

Rate Limits by Plan

Plan	Requests/minute	Requests/day	Concurrent
Free	60	1,000	5
Pro	300	10,000	20
Enterprise	1,000+	100,000+	100+

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1713264000

Handling 429 Errors

When rate limited, the API returns:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 32
}

Retry with exponential backoff:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const backoff = retryAfter * 1000 * Math.pow(2, i);
      const jitter = Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, backoff + jitter));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Performance Best Practices

DO:

Use cursor pagination (after parameter) for large catalogs — O(1) vs offset's O(n) degradation
Cache responses client-side — product data updates every 5-10 minutes, not every second
Batch requests when looking up multiple products — use POST /v1/products/batch
Use webhooks for real-time updates instead of polling
Monitor rate limit headers to stay within quotas
Use specific queries — narrower searches return faster than broad ones
Enable only needed options — each AI feature (confidence scores, predictions) adds 50-200ms

DON'T:

Deep offset pagination (> 100 pages) — use cursor-based navigation instead
High-frequency polling (> 1 req/sec sustained) — implement exponential backoff
Large result sets without pagination — request 20-50 items per page
Parallel requests burst — space out requests to avoid rate limiting

Caching Strategies

Data Type	Recommended TTL	Rationale
Product details	5-10 minutes	Updates infrequently
Search results	60 seconds	More dynamic, depends on query
Deals	5 minutes	Price changes but not every second
Categories	1 hour	Category structure rarely changes
Price history	1 hour	Historical data doesn't change

Pagination Performance

Method	Best For	Performance at Scale
Cursor (`after`)	Large catalogs, infinite scroll	O(1) — constant time
Offset (`offset`)	Known page numbers	O(n) — slows with deep offsets
Page number (`page`)	Fixed navigation UI	Same as offset

Example: Converting to cursor pagination

// Old (offset-based) — SLOW for deep pages
const products = await client.products.list({ limit: 20, offset: 1000 });

// New (cursor-based) — FAST at any depth
let cursor = null;
for (let i = 0; i < 50; i++) {
  const page = await client.products.list({ limit: 20, after: cursor });
  cursor = page.meta.next_cursor;
  if (!cursor) break;
}

Affiliate Integration

BuyWhere supports affiliate link generation for all purchase URLs. When users click through your affiliate links and make purchases, you earn a commission.

Generating Affiliate Links

Option 1: Using the API

The affiliate_url field is automatically included in all product responses:

{
  "id": 12345,
  "buy_url": "https://buywhere.ai/redirect/12345",
  "affiliate_url": "https://buywhere.ai/affiliate/12345?api_key=bw_live_xxx"
}

Option 2: Construct Manually

Append your API key to generate affiliate links:

https://buywhere.ai/affiliate/{product_id}?api_key=bw_live_your_key

Option 3: Track Clicks First

curl -X POST "https://api.buywhere.ai/v1/products/12345/click" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Returns the redirect URL with tracking.

Affiliate Dashboard

View your affiliate performance:

curl "https://api.buywhere.ai/v1/developers/me/usage" \
  -H "Authorization: Bearer bw_live_your_api_key_here"

Use Case Walkthroughs

Walkthrough 1: Find Cheapest iPhone in Singapore

Goal: Find the cheapest iPhone 15 Pro Max across all Singapore platforms.

import { BuyWhereClient } from "@buywhere/sdk";

const client = new BuyWhereClient("bw_live_your_api_key");

async function findCheapestIphone() {
  // Step 1: Search for iPhone 15 Pro Max
  const search = await client.search({
    q: "iphone 15 pro max 256gb",
    category: "Mobiles & Tablets",
    limit: 5
  });

  if (!search.items.length) {
    console.log("No products found");
    return;
  }

  // Step 2: Get the top result and find all matches
  const topResult = search.items[0];
  console.log(`\nComparing: ${topResult.name}\n`);

  // Step 3: Compare across all platforms
  const comparison = await client.compare(topResult.id);

  // Step 4: Sort by price and display
  const sortedMatches = comparison.matches.sort((a, b) => a.price - b.price);

  console.log("Price Comparison:");
  console.log("─".repeat(60));

  sortedMatches.forEach((match, i) => {
    console.log(
      `${i + 1}. ${match.source.padEnd(15)} ${match.currency} ${match.price.toFixed(2)} ` +
      `(${match.delivery_days} delivery)`
    );
  });

  // Step 5: Highlight best deal
  const cheapest = sortedMatches[0];
  const mostExpensive = sortedMatches[sortedMatches.length - 1];
  const savings = ((mostExpensive.price - cheapest.price) / mostExpensive.price * 100).toFixed(1);

  console.log("\n" + "=".repeat(60));
  console.log(`BEST DEAL: ${cheapest.source}`);
  console.log(`PRICE: ${cheapest.currency} ${cheapest.price.toFixed(2)}`);
  console.log(`SAVINGS: ${savings}% vs most expensive`);
  console.log(`BUY LINK: ${cheapest.buy_url}`);
  console.log("=".repeat(60));
}

findCheapestIphone();

Output:

Comparing: Apple iPhone 15 Pro Max 256GB Natural Titanium

Price Comparison:
────────────────────────────────────────────────────────────
1. shopee_sg       SGD 1649.00 (1-3 delivery)
2. lazada_sg       SGD 1699.00 (1-2 delivery)
3. amazon_sg       SGD 1749.00 (2-5 delivery)
4. qoo10_sg        SGD 1799.00 (3-5 delivery)

============================================================
BEST DEAL: shopee_sg
PRICE: SGD 1649.00
SAVINGS: 8.3% vs most expensive
BUY LINK: https://buywhere.ai/redirect/12345
============================================================

Walkthrough 2: Build a Deal Alert Bot

import { BuyWhereClient } from "@buywhere/sdk";

const client = new BuyWhereClient("bw_live_your_api_key");

interface DealAlert {
  category: string;
  minDiscount: number;
  onDeal: (deal: any) => void;
}

async function watchForDeals({ category, minDiscount, onDeal }: DealAlert) {
  console.log(`Watching ${category} for ${minDiscount}+% discounts...`);

  while (true) {
    try {
      const deals = await client.getDeals({
        category,
        minDiscount,
        limit: 10
      });

      for (const deal of deals.deals) {
        // Check if this is a significant deal (price drop or high discount)
        if (deal.discount_pct >= minDiscount) {
          await onDeal(deal);
        }
      }

      // Wait 5 minutes before next check
      await new Promise(resolve => setTimeout(resolve, 5 * 60 * 1000));

    } catch (error) {
      console.error("Error fetching deals:", error);
      await new Promise(resolve => setTimeout(resolve, 60 * 1000));
    }
  }
}

// Example usage
watchForDeals({
  category: "Electronics",
  minDiscount: 30,
  onDeal: async (deal) => {
    const message = `
🔥 HOT DEAL ALERT!

${deal.name}
💰 Price: ${deal.currency} ${deal.price}
📉 Was: ${deal.original_price} (${deal.discount_pct}% off)
🏪 Source: ${deal.source}
⭐ Rating: ${deal.rating}/5 (${deal.review_count} reviews)
🔗 ${deal.buy_url}
    `;

    // Send to Slack, Telegram, Discord, etc.
    console.log(message);
  }
});

Walkthrough 3: Price Tracking for Wishlist

import { BuyWhereClient } from "@buywhere/sdk";

const client = new BuyWhereClient("bw_live_your_api_key");

interface WishlistItem {
  query: string;
  targetPrice?: number;
}

const wishlist: WishlistItem[] = [
  { query: "Sony WH-1000XM5", targetPrice: 300 },
  { query: "iPad Air 256GB", targetPrice: 700 },
  { query: "Nintendo Switch OLED" }
];

async function trackWishlist() {
  const results = [];

  for (const item of wishlist) {
    // Search for the product
    const search = await client.search({ q: item.query, limit: 1 });

    if (!search.items.length) {
      results.push({ item: item.query, status: "not_found" });
      continue;
    }

    const product = search.items[0];

    // Get price history to check trend
    const stats = await client.getPriceStats(product.id);

    // Compare with target price if specified
    const meetsTarget = item.targetPrice ? product.price <= item.targetPrice : false;

    // Get prediction
    const prediction = await client.getPricePrediction(product.id);

    results.push({
      item: item.query,
      currentPrice: product.price,
      targetPrice: item.targetPrice,
      meetsTarget,
      priceStats: stats,
      prediction,
      buyUrl: product.buy_url
    });
  }

  // Print report
  console.log("\n📊 WISHLIST PRICE REPORT\n");
  console.log("─".repeat(80));

  for (const r of results) {
    console.log(`\n${r.item}`);
    console.log(`Current: ${r.currentPrice} | Target: ${r.targetPrice || "None"}`);

    if (r.meetsTarget) {
      console.log(`✅ TARGET MET! Buy now: ${r.buyUrl}`);
    } else if (r.prediction) {
      const days = 30;
      console.log(`📈 Price trend: ${r.prediction.trend}`);
      console.log(`🔮 Predicted in ${days}d: ${r.prediction[`predicted_price_${days}d`]}`);
    }
  }
}

trackWishlist();

Error Handling

Error Response Format

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {}
}

Common Error Codes

HTTP Status	Error Code	Description
400	`invalid_request`	Malformed request body or parameters
401	`authentication_failed`	Invalid or missing API key
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource not found
422	`validation_error`	Request validation failed
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Error Handling Example

import { BuyWhereClient, BuyWhereError, RateLimitError, NotFoundError } from "@buywhere/sdk";

const client = new BuyWhereClient("bw_live_your_api_key");

async function safeSearch(query: string) {
  try {
    return await client.search({ q: query });
  } catch (error) {
    if (error instanceof RateLimitError) {
      console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
      // Implement backoff and retry
    } else if (error instanceof NotFoundError) {
      console.log("Product not found");
    } else if (error instanceof BuyWhereError) {
      console.log(`API error: ${error.message}`);
      console.log(`Error code: ${error.code}`);
    } else {
      console.log("Unexpected error:", error);
    }
    return null;
  }
}

Data Model

Product

Field	Type	Description
`id`	integer	Unique product identifier
`sku`	string	Stock keeping unit
`source`	string	E-commerce platform (e.g., `shopee_sg`, `lazada_sg`)
`name`	string	Product title
`description`	string	Full product description
`price`	number	Current price
`original_price`	number	Original/list price before discount
`currency`	string	Currency code (SGD, USD, etc.)
`buy_url`	string	Direct purchase link
`affiliate_url`	string	Affiliate-tracked purchase link
`image_url`	string	Primary product image
`images`	string[]	All product images
`category`	string	Primary category
`category_path`	string[]	Hierarchical category path
`brand`	string	Brand name
`is_available`	boolean	Stock availability
`stock_level`	string	Stock level: `high`, `medium`, `low`, `out_of_stock`
`rating`	number	Average rating (0-5)
`review_count`	integer	Number of reviews
`seller`	object	Seller information
`shipping`	object	Shipping information
`metadata`	object	Source-specific data
`updated_at`	string	ISO 8601 timestamp

CompareMatch

Field	Type	Description
`product_id`	integer	Product ID on BuyWhere
`source`	string	Platform source
`price`	number	Listing price
`confidence`	number	Match confidence (0-1)
`shipping_cost`	number	Shipping cost
`total_cost`	number	Total cost (price + shipping)
`delivery_days`	string	Estimated delivery time
`seller_rating`	number	Seller rating (0-5)

Deal

Field	Type	Description
`id`	integer	Product ID
`name`	string	Product name
`price`	number	Current discounted price
`original_price`	number	Original price
`discount_pct`	number	Discount percentage
`source`	string	Platform source
`rating`	number	Product rating
`review_count`	integer	Number of reviews
`is_available`	boolean	Availability status

Support

Documentation: https://docs.buywhere.ai
Knowledge Base: https://docs.buywhere.ai/knowledge-base/ (troubleshooting guides, integration examples, best practices)
API Status: https://status.buywhere.ai
Support Email: support@buywhere.ai
API Reference: /docs/api-reference/openapi.md
SDK Source: https://github.com/buywhere/buywhere-sdk

Changelog

See CHANGELOG.md for version history and breaking changes.

developer-guide-shopping-agents

BuyWhere API Developer Guide

Table of Contents

Overview

Getting Started

Authentication

Getting Your API Key

Using Your API Key

Key Management

Your First API Call

Core Endpoints

Search Products

Semantic Search

Search Suggestions (Autocomplete)

Search Filters

Search History

Product Details

Get Product by ID

List Products

Get Random Products

Price Comparison

Compare Product Across Platforms

Batch Compare Multiple Products

Compare Two Products Directly

Get Product Matches Across Platforms

Get Price Comparison for Product

Find Best Price Across All Platforms

Categories

List Categories (Flat)

Get Category Tree (Hierarchical)

Get Full Taxonomy

Browse Products by Category

Advanced Features

Deals & Price Drops

Get Deals (Discounted Products)

Get Price Drops (Recent Decreases)

Get Best Deals Across Sources

Bulk Operations

Batch Product Lookup by IDs

Bulk Lookup by SKU, UPC, or URL

Bulk Import Products (Merchant Self-Serve)

Bulk Check Availability

Export Products

Stream Products Feed (NDJSON)

Price History & Analytics

Get Price History

Get Price Statistics

Get Price Prediction

Product Recommendations & Discovery

Find Similar Products

Get Alternatives (Cheaper in Same Category)

Get Bundle Suggestions

Get "Also Searched" Products

Get Trending Products

Product Availability & Stock

Get Product Availability Across Platforms

Check URL Availability (Lightweight)

Get Product Stock Level

Product Reviews

Get Product Reviews Aggregation

Product Questions & Answers

Submit a Question

List Questions for a Product

Submit an Answer

Track Product Clicks

SDK Reference

JavaScript/TypeScript

Python

MCP Integration

Claude Desktop

Installation

MCP Tools Available

Usage Examples

Other MCP Clients

Cursor

VS Code Copilot

Rate Limits & Best Practices

Expected Latency by Endpoint

Rate Limits by Plan

Rate Limit Headers