Search Products

post

https://api.cartai.ai/product/search

Searches for products by name across one or more merchants. Optionally prioritize results to a specific merchant. Returns a ranked list of matching products with pricing, imagery, and direct purchase links.

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

Search for products by name across CartAI's merchant network — including Shopify stores and major retailers. Optionally prioritize a specific merchant — other retailers are still included.

When to Use This Endpoint

Use /product/search to let users discover products before initiating a checkout. It is a lightweight lookup — no cart is created, no session is started.

Use case	Recommended approach
Search bar / product discovery UI	Call `/product/search` on user input, display returned products
Narrowing results to a specific retailer	Pass `merchant` to prioritize a specific merchant — `targetMatchCount` tells you how many matched
Pre-filling a checkout with a found item	Use `directUrl` from a search result as the `url` in `POST /checkout`
Cross-merchant price comparison	Omit `merchant` to get results from multiple retailers in one response

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

Never embed your API key in client-side code. Always call this endpoint from your backend.

Request Body

Field	Type	Required	Description
`name`	string	✅ Yes	The product name or search query (e.g. `"jeans"`, `"blue denim jacket"`).
`merchant`	string	❌ No	Prioritize results to a specific merchant name (e.g. `"Macy's"`). Case-insensitive.

Example Request

curl --location 'https://api.cartai.ai/product/search' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data '{
  "name": "jeans",
  "merchant": "Macy'\''s"
}'

Response Schema

A successful 200 response returns a JSON object with the following structure.

Top-level fields

Field	Type	Description
`status`	string	`"success"` on a successful search.
`message`	string	Human-readable result summary (e.g. `"Search complete"`).
`data`	object	Contains the search results. See `data` below.

`data`

Field	Type	Description
`products`	array of objects	Ranked list of matching products. See `products[]` below.
`targetMerchant`	string	The `merchant` value from your request, echoed back. Empty string if no merchant filter was applied.
`targetMatchCount`	integer	Number of products in `products[]` that belong to the target merchant. `0` if no merchant was specified.

`products[]`

Each item in the products array represents a single matching product.

Field	Type	Description
`name`	string	Product name as listed by the merchant.
`brand`	string	Brand name. May be omitted if the merchant does not provide it.
`merchant`	string	Name of the retailer selling this product.
`image`	string (URI)	URL of the primary product image.
`priceFrom`	number	Lowest available price for this product, in the specified `currency`.
`currency`	string	ISO 4217 currency code (e.g. `"USD"`).
`directUrl`	string (URI)	Direct link to the product page on the merchant's site. Use this as the `url` in `POST /checkout`.

Example Response

{
  "status": "success",
  "message": "Search complete",
  "data": {
    "products": [
      {
        "name": "Dkny Jeans Women's High-Rise Jeans - Clifton",
        "brand": "Dkny Jeans",
        "merchant": "Macy's",
        "image": "https://slimages.macysassets.com/is/image/MCY/products/0/optimized/35661058_fpx.tif?wid=1200&fmt=jpeg&qlt=100",
        "priceFrom": 26.63,
        "currency": "USD",
        "directUrl": "https://www.macys.com/shop/product/dkny-jeans-womens-high-rise-jeans?ID=24996759"
      },
      {
        "name": "Nautica Jeans Women's Demi Bootcut Jeans - Sailor",
        "brand": "Nautica Jeans",
        "merchant": "Macy's",
        "image": "https://slimages.macysassets.com/is/image/MCY/products/6/optimized/33148130_fpx.tif?wid=1200&fmt=jpeg&qlt=100",
        "priceFrom": 44.52,
        "currency": "USD",
        "directUrl": "https://www.macys.com/shop/product/nautica-jeans-womens-demi-bootcut-jeans?ID=22497871"
      }
    ],
    "targetMerchant": "Macy's",
    "targetMatchCount": 2
  }
}

Notes

priceFrom reflects the lowest-priced variant. The actual checkout price may vary depending on the variant selected.
The directUrl from a search result can be passed directly as the url field in POST /checkout to initiate a purchase if the product does not have any variants.

Responses

400

Bad Request

Language

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json