Catalog

CartAI's Catalog APIs give you real-time access to product data across thousands of merchants — including Shopify stores and major retailers — without building or maintaining any scrapers. Three focused endpoints cover the full pre-checkout journey: finding a product, understanding its variants, and computing an accurate order total before a single cart is touched.

The Three Catalog Endpoints

How They Work Together

These three APIs are designed to chain. The output of each step feeds directly into the next, forming a complete product-discovery-to-pricing pipeline.

User query
    │
    ▼
POST /product/search          ← "Find me jeans at Macy's"
    │  returns directUrl
    ▼
POST /product/details         ← "What sizes and colors are available?"
    │  returns variant url + unitPrice
    ▼
POST /checkout-estimates      ← "What will this actually cost me to ship?"
    │  returns total (subtotal + shipping + tax)
    ▼
POST /checkout                ← Place the order

Step 1 — Discover: /product/search

The entry point for any product journey. Pass a search term and an optional merchant name; get back a ranked list of matching products from across the network.

Key outputs to carry forward:

• directUrl — pass this into /product/details to fetch variant data for the product the user selects
• priceFrom — use as a preview price in your UI while the user browses results
• targetMatchCount — surface how many results match the user's preferred merchant

{
  "name": "jeans",
  "merchant": "Macy's"
}

Without a merchant filter, the search returns results from multiple retailers — useful for cross-merchant price comparison before the user commits to a store.

Step 2 — Inspect: /product/details

Once a user selects a product, pass its URL here to get the full variant breakdown. This is where you build the variant picker — colours, sizes, band/cup combinations — and confirm stock before showing a "Buy" button.

Key outputs to carry forward:

• dimensions — the axis names (e.g. ["Color", "Size"]); use these to render dynamic pickers
• variants[].available — filter to true before showing options; display false variants as greyed-out
• variants[].price — the per-variant price to pass as unitPrice into /checkout-estimates
• variants[].url — the variant-specific URL to pass into POST /checkout

{
  "url": "https://www.natori.com/products/feathers-plunge-t-shirt-bra-black",
  "allVariants": true
}

Always use variants[].url (not the top-level directUrl) when the user has selected a specific variant. This ensures the checkout agent lands on the correct colour/size combination.

Step 3 — Estimate: /checkout-estimates

Before placing an order, give users a transparent cost breakdown. Pass the merchant name, the destination ZIP, and the item details (using unitPrice from Step 2). Get back a full order estimate including shipping and tax — no cart, no session, no side effects.

Key outputs to surface to the user:

• total — the all-in estimated cost: subtotal + shipping + tax
• shipping — show "Free" when 0.0 and shippingKnown: true
• tax — itemised by line in items[].tax
• shippingKnown — if false, flag the estimate as incomplete rather than showing an inaccurate total

{
  "merchant": "Natori",
  "destination": { "zip": "75001" },
  "items": [
    {
      "url": "https://www.natori.com/products/feathers-plunge-t-shirt-bra-black",
      "quantity": 1,
      "unitPrice": 72,
      "category": "clothing"
    }
  ]
}

End-to-End Example

A user types "black bra, Natori" into your app. Here is how the three APIs serve that request:

The user sees real stock, real prices, and a real total — all before a checkout session is ever opened.

Why This Approach Is Fast

• No page loads. All three endpoints return structured JSON. Your UI never waits for a merchant page to render.
• No scraping maintenance. CartAI handles the extraction layer across every supported merchant.
• Parallelisable. If you already have a product URL, you can call /product/details and skip /product/search entirely. If the user just wants a price check, call /checkout-estimates standalone.
• Feeds directly into checkout. The url and unitPrice from /product/details map directly to the fields required by POST /checkout — no data transformation needed.