V2 Batch Product Details

Batch lookup up to 100 products by their BuyWhere IDs in a single request. Optimized for AI agent workflows.

Base URL: https://api.buywhere.ai/v2/products/batch-details

Overview

The Batch Details endpoint allows AI agents to fetch multiple products simultaneously, reducing API calls and improving performance for workflows that need to display or process multiple products at once.

HTTP Method

POST /v2/products/batch-details

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Request Body

{
  "product_ids": [18472931, 18472932, 18472933, 18472934],
  "include_metadata": true,
  "target_currency": "SGD"
}

Request Example

cURL

curl -X POST "https://api.buywhere.ai/v2/products/batch-details" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [18472931, 18472932, 18472933],
    "include_metadata": true
  }'

Python

import httpx

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

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = httpx.post(
    f"{BASE_URL}/v2/products/batch-details",
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "include_metadata": True
    },
    headers=headers
)
data = response.json()
print(f"Retrieved {len(data['results'])} products")
for product in data['results']:
    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/batch-details`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      product_ids: [18472931, 18472932, 18472933],
      include_metadata: true
    })
  }
);

const data = await response.json();
console.log(`Retrieved ${data.results.length} products`);
data.results.forEach(product => {
  console.log(`  ${product.title}: ${product.currency} ${product.price}`);
});

Go

package main

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

func batchLookup(apiKey string, productIDs []int64) error {
    url := "https://api.buywhere.ai/v2/products/batch-details"
    
    body := map[string]interface{}{
        "product_ids":      productIDs,
        "include_metadata": true,
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    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)

    results := result["results"].([]interface{})
    fmt.Printf("Retrieved %d products\n", len(results))
    for _, r := range results {
        m := r.(map[string]interface{})
        fmt.Printf("  %s: %s %s\n", m["title"], m["currency"], m["price"])
    }
    return nil
}

Response

Success Response (200 OK)

{
  "results": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "price_sgd": "1349.00",
      "url": "https://shopee.sg/product/18472931",
      "brand": "Apple",
      "category": "Mobile Phones",
      "image_url": "https://cf.shopee.sg/file/xxxxx.jpg",
      "rating": 4.8,
      "review_count": 2341,
      "is_available": true,
      "in_stock": true,
      "confidence_score": 0.95,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "1349.00",
      "affiliate_url": "https://buywhere.ai/track/abc123",
      "data_updated_at": "2026-04-15T12:00:00Z",
      "specs": {
        "storage": "256GB",
        "color": "Natural Titanium"
      },
      "metadata_": {
        "original_price": 1499.00
      }
    },
    {
      "id": 18472932,
      "sku": "IPHONE15PRO512",
      "source": "lazada_sg",
      "title": "iPhone 15 Pro 512GB Black Titanium",
      "price": "1549.00",
      "currency": "SGD",
      "price_sgd": "1549.00",
      "url": "https://www.lazada.sg/product/18472932",
      "brand": "Apple",
      "category": "Mobile Phones",
      "image_url": "https://static-sg.lazada.com/xxxxx.jpg",
      "rating": 4.7,
      "review_count": 1245,
      "is_available": true,
      "in_stock": true,
      "confidence_score": 0.93,
      "availability_prediction": "in_stock",
      "competitor_count": 6,
      "buybox_price": "1349.00",
      "affiliate_url": "https://buywhere.ai/track/def456"
    }
  ],
  "errors": []
}

Response Fields

Product Fields (Batch Response)

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": "product_ids",
          "message": "Array must not exceed 100 items",
          "type": "max_length"
        }
      ]
    }
  }
}

Batch with Currency Conversion

Request prices in USD:

curl -X POST "https://api.buywhere.ai/v2/products/batch-details" \
  -H "Authorization: Bearer bw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [18472931, 18472932],
    "target_currency": "USD"
  }'

Response prices will be converted to USD.

Performance Notes

• Maximum 100 products per request
• Responses are cached for 60 seconds
• Use include_metadata=false for faster responses when specs aren't needed

---

Related Endpoints

• V2 Product Detail - Get single product
• V2 Search - Search products
• Agent Native Batch Lookup - AI-optimized batch lookup