Product Detail by SKU API — Developer Documentation

BUY-3254 | GET /v1/products/{sku} — product detail endpoint with price variants and merchant links

---

Overview

GET /v1/products/{sku} retrieves a single product by its SKU, returning full product details including price variants (color, size, storage options) and merchant links (affiliate URLs across all platforms selling the same product).

Key characteristics:

• SKU lookup — exact match on product SKU from source platform
• Price variants — all available options (color, size, storage) with their respective prices
• Merchant links — tracked affiliate URLs for every platform offering this product
• Cross-platform aggregation — same SKU across Shopee, Lazada, Amazon, and more in one response
• p99 < 50ms — optimized for real-time agentic shopping flows

---

Endpoint

GET /v1/products/{sku}

Path Parameters

Query Parameters

---

Authentication

All requests require a Bearer token:

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

See Authentication Guide for API key generation.

---

Response Envelope

{
  "product": {
    "id": 18472931,
    "sku": "IPHONE15PRO256BLK",
    "source": "shopee_sg",
    "merchant_id": "SHOPEE_SG_001",
    "name": "iPhone 15 Pro 256GB Black Titanium",
    "description": "Titanium design. A17 Pro chip. Customizable Action button.",
    "price": "1349.00",
    "currency": "SGD",
    "price_sgd": "1349.00",
    "buy_url": "https://shopee.sg/product/iphone-15-pro-256gb",
    "image_url": "https://cf.shopee.sg/file/...",
    "brand": "Apple",
    "category": "Mobile Phones",
    "category_path": ["Electronics", "Phones", "Mobile Phones"],
    "rating": "4.8",
    "review_count": 2341,
    "is_available": true,
    "in_stock": true,
    "stock_level": "high",
    "last_checked": "2026-04-18T10:00:00Z",
    "data_updated_at": "2026-04-18T08:30:00Z",
    "updated_at": "2026-04-18T14:30:00Z",
    "has_variants": true,
    "specs": {
      "color": "Black Titanium",
      "storage": "256GB",
      "display": "6.1-inch Super Retina XDR"
    }
  },
  "price_variants": [
    {
      "variant_id": "IPHONE15PRO256BLK",
      "variant_name": "256GB Black Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "stock_status": "in_stock",
      "specs": {
        "color": "Black Titanium",
        "storage": "256GB"
      }
    },
    {
      "variant_id": "IPHONE15PRO256WHT",
      "variant_name": "256GB White Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "stock_status": "in_stock",
      "specs": {
        "color": "White Titanium",
        "storage": "256GB"
      }
    },
    {
      "variant_id": "IPHONE15PRO512BLK",
      "variant_name": "512GB Black Titanium",
      "price": "1549.00",
      "currency": "SGD",
      "stock_status": "low_stock",
      "specs": {
        "color": "Black Titanium",
        "storage": "512GB"
      }
    }
  ],
  "merchant_links": [
    {
      "source": "shopee_sg",
      "merchant_id": "SHOPEE_SG_001",
      "merchant_name": "Shopee Singapore",
      "price": "1349.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/iphone-15-pro-256gb",
      "affiliate_url": "https://buywhere.ai/track/shopee_sg/18472931",
      "is_available": true,
      "rating": "4.8",
      "review_count": 2341,
      "last_checked": "2026-04-18T10:00:00Z"
    },
    {
      "source": "lazada_sg",
      "merchant_id": "LAZADA_SG_001",
      "merchant_name": "Lazada Singapore",
      "price": "1369.00",
      "currency": "SGD",
      "buy_url": "https://www.lazada.sg/products/iphone-15-pro",
      "affiliate_url": "https://buywhere.ai/track/lazada_sg/18472932",
      "is_available": true,
      "rating": "4.7",
      "review_count": 891,
      "last_checked": "2026-04-18T09:45:00Z"
    },
    {
      "source": "amazon_sg",
      "merchant_id": "AMAZON_SG_001",
      "merchant_name": "Amazon Singapore",
      "price": "1399.00",
      "currency": "SGD",
      "buy_url": "https://www.amazon.sg/dp/B0CIDRXQ5G",
      "affiliate_url": "https://buywhere.ai/track/amazon_sg/18472933",
      "is_available": true,
      "rating": "4.6",
      "review_count": 203,
      "last_checked": "2026-04-18T10:15:00Z"
    }
  ],
  "meta": {
    "total_merchants": 3,
    "total_variants": 6,
    "cheapest_price": "1349.00",
    "cheapest_source": "shopee_sg",
    "lowest_rating": "4.6",
    "data_freshness": "recent"
  }
}

---

Field Definitions

Product Object

Price Variant Object

Merchant Link Object

Meta Object

---

Examples

Basic SKU Lookup

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

With Currency Conversion (to MYR)

curl "https://api.buywhere.ai/v1/products/IPHONE15PRO256BLK?currency=MYR" \
  -H "Authorization: Bearer bw_live_xxxxx"

Variants Only (no merchant links)

curl "https://api.buywhere.ai/v1/products/IPHONE15PRO256BLK?include_merchant_links=false" \
  -H "Authorization: Bearer bw_live_xxxxx"

Merchant Links Only (no variants)

curl "https://api.buywhere.ai/v1/products/IPHONE15PRO256BLK?include_variants=false" \
  -H "Authorization: Bearer bw_live_xxxxx"

---

SDK Usage

Python SDK

from buywhere import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

# Basic lookup
response = client.products.get_by_sku("IPHONE15PRO256BLK")

# Access product details
print(response.product.name)
print(response.product.price)

# Iterate over price variants
for variant in response.price_variants:
    print(f"{variant.variant_name}: {variant.price}")

# Iterate over merchant links
for merchant in response.merchant_links:
    print(f"{merchant.source}: {merchant.price} -> {merchant.affiliate_url}")

# Find cheapest option
cheapest = min(response.merchant_links, key=lambda m: float(m.price))
print(f"Cheapest: {cheapest.source} at {cheapest.price}")

JavaScript/TypeScript SDK

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

const client = new BuyWhere({ apiKey: "bw_live_xxxxx" });

// Basic lookup
const response = await client.products.getBySku("IPHONE15PRO256BLK");

// Access product details
console.log(response.product.name);
console.log(response.product.price);

// Iterate over price variants
for (const variant of response.priceVariants) {
  console.log(`${variant.variantName}: ${variant.price}`);
}

// Iterate over merchant links
for (const merchant of response.merchantLinks) {
  console.log(`${merchant.source}: ${merchant.price} -> ${merchant.affiliateUrl}`);
}

// Find cheapest option
const cheapest = response.merchantLinks.reduce((min, m) => 
  parseFloat(m.price) < parseFloat(min.price) ? m : min
);
console.log(`Cheapest: ${cheapest.source} at ${cheapest.price}`);

---

Agentic Commerce Use Cases

Shopping Agent: "Find me the cheapest iPhone 15 Pro"

# Agent workflow for product comparison
async def find_cheapest_product(sku: str):
    response = client.products.get_by_sku(sku)
    
    # Sort by price
    by_price = sorted(response.merchant_links, key=lambda m: float(m.price))
    
    # Present to user
    return {
        "product_name": response.product.name,
        "options": [
            {
                "merchant": m.merchant_name,
                "price": m.price,
                "affiliate_url": m.affiliate_url,
                "rating": m.rating,
                "in_stock": m.is_available
            }
            for m in by_price[:5]
        ]
    }

Shopping Agent: "Check if my size is in stock"

# Agent workflow for variant checking
async def check_variant_availability(sku: str, target_specs: dict):
    response = client.products.get_by_sku(sku)
    
    for variant in response.price_variants:
        if all(variant.specs.get(k) == v for k, v in target_specs.items()):
            return {
                "variant_name": variant.variant_name,
                "price": variant.price,
                "stock_status": variant.stock_status,
                "merchants": [
                    m for m in response.merchant_links 
                    if m.is_available
                ]
            }
    
    return {"error": "Variant not found"}

---

Error Responses

404 Not Found Response

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "No product found with SKU: NONEXISTENT_SKU",
    "details": {
      "sku": "NONEXISTENT_SKU",
      "suggestion": "Verify the SKU or search for the product first"
    }
  }
}

---

Performance Characteristics

Performance varies based on load conditions. Targets below represent single-request baseline latency:

Cache TTL: 5 minutes (300 seconds)

Note: Actual latency depends on query complexity, network conditions, and server load. Complex SKU lookups with multiple merchant links may see higher latency.

---

Caching

Responses are cached server-side for 5 minutes to improve performance for repeated queries.

Client-side caching: Use Cache-Control headers to cache responses locally:

Cache-Control: private, max-age=300

Cache invalidation: Send unique query parameters (e.g., &t=timestamp) to bypass cache when fresh data is required.

---

Rate Limits

Applies per API key. See Rate Limits for details.

---

Implementation Notes

• SKU vs ID — Use GET /v1/products/{sku} for human-readable lookups (agent workflows). Use GET /v1/products/{id} for internal/database IDs.
• Same SKU, multiple merchants — The merchant_links array shows every platform offering this exact SKU, enabling cross-platform price comparison.
• Variant structure — Price variants reflect option-level pricing (color, storage, size). For full cross-platform comparison, see merchant_links.
• Affiliate links — Always use affiliate_url for BuyWhere tracked links that support our commerce infrastructure.

---

Related Endpoints

• GET /v1/products — Paginated product listing
• GET /v1/products/{id} — Product by internal ID
• GET /v1/products/bulk-lookup — Batch SKU lookup
• GET /v1/search — Full-text product search
• GET /v1/products/{id}/similar — Similar products