Skip to main content

Product Search

Search and discover products across multiple merchants with a single API call. One endpoint returns standardized product data from many stores, giving you variant IDs to use directly with carts or checkouts.

See API Reference for complete endpoint documentation.

Quick Start​

# 1. Search for products
curl -X POST https://api.simplecheckout.ai/v0/catalog/search \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes", "per_page": 5}'

# 2. Apply filters based on returned facets
curl -X POST https://api.simplecheckout.ai/v0/catalog/search \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes",
    "filters": {
      "brand": ["Nike"],
      "size": ["10"]
    }
  }'

# 3. Extract variant id from results
# Use this ID to add items to carts or reference in checkouts

The search returns products with variants. Each variant has an id that contains all routing information needed to purchase that specific item.

Key Concepts​

Products and Variants​

  • Product: A high-level item (e.g., "Nike Air Max 90")
  • Variant: A specific, purchasable configuration (e.g., "Nike Air Max 90, Size 10, White/Red")

Each variant has a unique id that you can use to add items to carts. This ID contains all the routing information needed to interact with the specific merchant.

Facets​

Facets are filterable attributes that help users navigate search results. When you search, the API returns both products AND the distribution of facets across all results:

{
  "facets": {
    "brand": {
      "Nike": 245,
      "Adidas": 189,
      "New Balance": 102
    },
    "merchant": {
      "store-one.com": 88,
      "store-two.com": 156,
      "store-three.com": 92
    }
  }
}

This enables dynamic filtering UIs where users can progressively refine their search based on available options.

How It Works​

Search across multiple merchants with one endpoint that returns standardized product data. Apply filters using facets to refine results, and use the variant IDs directly with carts or checkouts. Include your API key in the api-key header for authentication.

Using Variant IDs​

The variant id from search results can be used directly with the Carts API to add items to a shopping cart:

requests.post(
    f"https://api.simplecheckout.ai/v0/carts/{cart_id}/lines",
    headers={"api-key": "YOUR_API_KEY"},
    json={"product_variant_id": variant_id, "quantity": 1}
)

Next Steps​