GraphQL API

The BuyWhere GraphQL API provides a flexible query interface for AI agents to fetch exactly the product fields they need, reducing over-fetching and saving bandwidth and tokens.

Endpoint

• Playground: GET /graphql — Interactive GraphQL IDE (GraphiQL)
• API: POST /graphql — GraphQL endpoint

Authentication

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

Queries

products

Search and filter products with full control over returned fields.

Arguments:

Example:

query {
  products(query: "iphone 15", category: "Smartphones", limit: 5) {
    total
    limit
    offset
    hasMore
    items {
      id
      name
      price
      currency
      source
      brand
      category
      imageUrl
      affiliateUrl
      isAvailable
    }
  }
}

Response:

{
  "data": {
    "products": {
      "total": 42,
      "limit": 5,
      "offset": 0,
      "hasMore": true,
      "items": [
        {
          "id": 12345,
          "name": "iPhone 15 Pro Max 256GB",
          "price": "1499.00",
          "currency": "SGD",
          "source": "lazada_sg",
          "brand": "Apple",
          "category": "Smartphones",
          "imageUrl": "https://...",
          "affiliateUrl": "https://...",
          "isAvailable": true
        }
      ]
    }
  }
}

---

product

Get a single product by ID.

Arguments:

Example:

query {
  product(id: 12345) {
    id
    name
    sku
    source
    merchantId
    price
    currency
    buyUrl
    affiliateUrl
    imageUrl
    brand
    category
    categoryPath
    rating
    isAvailable
    lastChecked
    metadata
    updatedAt
    priceTrend
  }
}

---

categories

List all available product categories with product counts.

Example:

query {
  categories {
    name
    count
    children {
      name
      count
    }
  }
}

---

taxonomy

Get the full unified category taxonomy with hierarchical structure.

Example:

query {
  taxonomy {
    total
    version
    categories {
      id
      name
      productCount
      subcategories {
        id
        name
        productCount
      }
    }
  }
}

---

deals

Find products currently priced below their original/historical price.

Arguments:

Example:

query {
  deals(category: "Electronics", minDiscountPct: 20, limit: 10) {
    total
    limit
    offset
    items {
      id
      name
      price
      originalPrice
      discountPct
      dealScore
      currency
      source
      category
      buyUrl
      affiliateUrl
      imageUrl
      clickCount
    }
  }
}

---

priceDrops

Find products with recent price decreases using price history data.

Arguments:

Example:

query {
  priceDrops(category: "Laptops", days: 14, minDropPct: 10) {
    total
    limit
    offset
    items {
      id
      name
      price
      previousPrice
      priceDrop
      priceDropPct
      dealScore
      currency
      source
      category
      buyUrl
      priceDropDays
    }
  }
}

---

Why GraphQL?

Compared to the REST API, GraphQL offers:

1. No over-fetching: Agents only get the fields they request
2. Single request: Fetch products, categories, and deals in one query
3. Predictable responses: No need to parse different REST endpoint shapes
4. IDE support: Built-in GraphiQL playground for exploration

Rate Limits

Same rate limits apply as the REST API. Use the Authorization header with your API key.