V2 Product List

List products from the BuyWhere catalog with filtering, sorting, and cursor-based pagination.

Base URL: https://api.buywhere.ai/v2/products

Overview

The V2 Product List endpoint retrieves products with optional filters for category, brand, price range, platform, availability, and regional targeting. It supports cursor-based pagination for efficient traversal of large result sets.

HTTP Method

GET /v2/products

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Query Parameters

Request Example

cURL

curl -X GET "https://api.buywhere.ai/v2/products?category=electronics&min_price=100&max_price=2000&limit=20&sort_by=price_asc" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx"

Python

import httpx

API_KEY = "bw_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.buywhere.ai"

headers = {"Authorization": f"Bearer {API_KEY}"}

response = httpx.get(
    f"{BASE_URL}/v2/products",
    params={
        "category": "electronics",
        "min_price": 100,
        "max_price": 2000,
        "limit": 20,
        "sort_by": "price_asc"
    },
    headers=headers
)
data = response.json()
print(f"Total products: {data['total']}")
for product in data['items'][:5]:
    print(f"  {product['title']}: {product['currency']} {product['price']}")

JavaScript (Node.js)

const API_KEY = "bw_live_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://api.buywhere.ai";

const response = await fetch(
  `${BASE_URL}/v2/products?category=electronics&min_price=100&max_price=2000&limit=20&sort_by=price_asc`,
  {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  }
);

const data = await response.json();
console.log(`Total products: ${data.total}`);
data.items.slice(0, 5).forEach(product => {
  console.log(`  ${product.title}: ${product.currency} ${product.price}`);
});

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func listProducts(apiKey string) error {
    baseURL, _ := url.Parse("https://api.buywhere.ai/v2/products")
    params := url.Values{}
    params.Set("category", "electronics")
    params.Set("min_price", "100")
    params.Set("max_price", "2000")
    params.Set("limit", "20")
    params.Set("sort_by", "price_asc")
    baseURL.RawQuery = params.Encode()

    req, _ := http.NewRequest("GET", baseURL.String(), nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    total := int(result["total"].(float64))
    fmt.Printf("Total products: %d\n", total)

    items := result["items"].([]interface{})
    for i := 0; i < 5 && i < len(items); i++ {
        m := items[i].(map[string]interface{})
        fmt.Printf("  %s: %s %s\n", m["title"], m["currency"], m["price"])
    }
    return nil
}

Response

Success Response (200 OK)

{
  "total": 45230,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "items": [
    {
      "id": 18472931,
      "sku": "SAMSUNG-TV-55",
      "source": "shopee_sg",
      "title": "Samsung 55 inch 4K Smart TV",
      "description": "Crystal UHD, HDR, Smart Hub, WiFi Built-in",
      "price": "899.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/789012",
      "affiliate_url": "https://buywhere.ai/track/xyz789",
      "image_url": "https://cf.shopee.sg/file/abc123",
      "brand": "Samsung",
      "category": "TVs & Home Cinema",
      "rating": 4.6,
      "review_count": 1205,
      "is_available": true,
      "in_stock": true,
      "stock_level": "in_stock",
      "updated_at": "2026-04-15T08:00:00Z"
    }
  ]
}

Response Fields

Cursor-Based Pagination

For large result sets, use cursor-based pagination with the after parameter:

# First request
curl "https://api.buywhere.ai/v2/products?limit=20" \
  -H "Authorization: Bearer bw_live_xxx"

# Next page using cursor
curl "https://api.buywhere.ai/v2/products?limit=20&after=18472000" \
  -H "Authorization: Bearer bw_live_xxx"

The after parameter accepts a product ID to start after for efficient deep pagination.

Sorting Options

Regional Filtering

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

422 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "min_price",
          "message": "Value must be greater than or equal to 0",
          "type": "greater_than_equal"
        }
      ]
    }
  }
}

---

Related Endpoints

• V2 Search - Full-text search
• V2 Product Detail - Get single product by ID
• V2 Batch Details - Batch lookup multiple products
• Agent Native Search - AI-optimized search