Create Search Checkout Task

Creates an asynchronous AI-powered checkout task from product names instead of product URLs. Provide the merchant and a list of item names — the agent searches the merchant's catalog, resolves each item (and any selected variant), assembles the cart, and completes shipping, payment and order confirmation in a single call.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

How it Works

This is an asynchronous API. When you call POST /search-checkout, it does not wait for the checkout to complete. Instead, it:

  1. Validates your request and queues the task.
  2. Returns a taskId immediately (HTTP 201).
  3. Runs the checkout in the background using CartAI's AI agents — searching the merchant's site for each item in itemList, adding the matched products to the cart, and checking out.
  4. Sends real-time status updates to your configured webhook endpoint as the task progresses.

You use the returned taskId to either poll the task status via GET /checkout/{taskId}, or listen passively via webhooks.

⚠️

Do not re-submit the same payload on success. A 201 response means the task was accepted. Resubmitting creates a duplicate checkout.

When to use this API instead of Create Checkout

Use POST /search-checkout when…Use POST /checkout when…
You know the product names but not their product page URLsYou already have the exact product page URLs
All items are from a single merchantItems may span one or many merchants

Authentication

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

x-api-key: YOUR_API_KEY_HERE

Security rules you must follow:

  • Never expose your API key in client-side code, mobile apps, or public repositories.
  • Store it using environment variables or a secrets manager on your backend.

To get your API key, generate it from the CartAI Admin Portal after your account is provisioned. Contact the CartAI Account Management Team to request access.


Request Body

The request body is a JSON object with five top-level keys:

KeyTypeRequiredDescription
customerobject✅ YesCustomer identity, addresses, payment, and shipping preference
merchantstring (URI)✅ YesWebsite URL of the merchant to search and check out from
itemListarray of objects✅ YesOne or more products to find and purchase, identified by name
optionsobject❌ NoExecution control flags
addonsobject❌ NoOptional enhancements such as coupon codes

customer (object, required)

Contains all information CartAI needs to identify the buyer, ship the order, and process payment.

customer.contact

Personal contact details of the buyer.

FieldTypeDescription
firstNamestringBuyer's given name, as it will appear on shipping labels.
lastNamestringBuyer's surname.
emailstring (email format)Valid email address. Used by the merchant for order confirmation.
phonestringContact phone number. Supports international formats (e.g. +12144444444). Pattern: ^[+0-9\- ]{7,20}$

customer.shippingAddress

Where the order should be physically delivered.

FieldTypeDescription
addressLine1stringPrimary street address (house number + street name).
addressLine2stringOptional — apartment, suite, floor, unit, etc.
citystringCity name.
provincestringState, province, or region. Can be abbreviated (NY) or full (New York).
postalCodestringZIP or postal code. Pattern: ^[A-Za-z0-9\- ]{3,10}$
countrystringCountry name or ISO code (e.g. US or United States).

customer.billingAddress

Billing address for the payment method. Uses the exact same schema as shippingAddress.

💡

If billing and shipping addresses are the same, send identical objects for both. The API does not auto-copy them.

customer.shippingMethod

Controls how the AI agent selects a shipping option at the merchant's checkout.

FieldTypeDescription
strategystringCurrently supported: "cheapest" and "fastest" — the default agent behavior is to select the lowest-cost ie cheapest shipping option available.

customer.payment

Configures how the checkout task pays for the order. CartAI delegates payment to an external provider rather than handling raw card data directly. For that see Payment Integration section from the Guide.

But to test the execution you can use Test Cards.

FieldTypeDescription
providerstringName of the payment provider. Example: "test". Must match a provider configured in your CartAI account.
datastringThe buyer's identifier within the payment provider's system. CartAI uses this to look up their stored payment credentials.

merchant (string, required)

The website URL of the merchant to shop from (e.g. "https://kyliecosmetics.com/"). CartAI's agent searches this merchant's catalog for every item in itemList, so all items in a single request must be sold by this merchant.

⚠️

Use the merchant's main storefront URL. To buy from more than one merchant, send a separate request per merchant.


itemList (array of objects, required)

Each item in the array represents one product to find and purchase on the merchant site.

Item object fields

FieldTypeRequiredDescription
namestring✅ YesProduct name to search for on the merchant's site (e.g. "Plumping Matte Lip Kit"). Use the product's full name as the merchant lists it for the most reliable match.
quantityinteger❌ NoNumber of units to purchase. Minimum: 1. Defaults to 1 if omitted.
selectedVariantobject❌ NoSpecifies which product variant to select. If omitted, the agent may pick the default or fail if variant selection is mandatory.

selectedVariant fields

selectedVariant is a set of key/value pairs. Each key is the name of a variant option as the merchant's site shows it (e.g. Shade, Color, Size), and each value is the option to select.

ExampleMeaning
{ "Shade": "candy k" }Select the shade candy k
{ "Color": "Ivory", "Size": "S" }Select color Ivory in size S
⚠️

Variant labels must match exactly what the merchant's site displays. A mismatch can cause the agent to select the wrong variant or fail the task.

Tips for item names

  • Use the product's full name from the merchant's site rather than a generic description — "Blush Wood Eau De Parfum" resolves more reliably than "perfume".
  • If a merchant sells several products with similar names, include enough detail (format, size, collection) to tell them apart, and use selectedVariant for options such as shade or size rather than putting them in name.

options (object, optional)

Execution control flags that modify the checkout agent's behaviour.

FieldTypeDefaultDescription
verifyBeforePlacementbooleanfalseWhen true, the agent asks for confirmation just before placing the order. The task pauses in PENDING_CONFIRMATION until the order is confirmed.
useSavedCredentialToLoginbooleanfalseWhen true, the agent signs in to the merchant's site using the credentials stored for the customer's email and that merchant with the Create Credential Vault Session API. Credentials must be saved first.
useGuestCheckoutIfLoginFailsbooleanfalseWhen true, if the stored credentials do not work, the agent falls back to guest checkout when the merchant offers it. Only relevant when useSavedCredentialToLogin is true.
allowInteractionbooleanfalseWhen true, the task runs as an interactive flow instead of fire-and-forget: if the agent comes across a question it cannot answer (e.g. an OTP), it pauses and requests the input. See Send Interactive Inputs.
allowPartialCheckoutbooleanfalseWhen true, if some items in itemList fail (e.g. not found or out of stock), CartAI will still complete the checkout for the remaining successful items. When false, any single item failure aborts the entire checkout.

addons (object, optional)

Optional enhancements to apply during checkout, such as discount codes.

FieldTypeDescription
couponCodearray of stringsOne or more coupon or promo codes to apply at checkout (e.g. ["SUMMER15"]). CartAI's agent will attempt to apply each code in order. Invalid codes are skipped.

Example Request

{
  "customer": {
    "contact": {
      "firstName": "Carol",
      "lastName": "Sturka",
      "phone": "+12144444444",
      "email": "[email protected]"
    },
    "shippingAddress": {
      "addressLine1": "609 Royal Crest Dr",
      "addressLine2": "",
      "city": "Richardson",
      "province": "TX",
      "postalCode": "75081",
      "country": "US"
    },
    "billingAddress": {
      "addressLine1": "609 Royal Crest Dr",
      "addressLine2": "",
      "city": "Richardson",
      "province": "TX",
      "postalCode": "75081",
      "country": "US"
    },
    "shippingMethod": {
      "strategy": "cheapest"
    },
    "payment": {
      "provider": "test",
      "data": {
        "cvv": "444",
        "name": "Carol Sturka",
        "cardNumber": "4242424242424242",
        "expiryYear": "2034",
        "expiryMonth": "12"
      }
    }
  },
  "merchant": "https://kyliecosmetics.com/",
  "itemList": [
    {
      "name": "Velvet Brew Eau De Parfum Pen Spray",
      "quantity": 1
    },
    {
      "name": "Face Brush Trio"
    },
    {
      "name": "Blush Wood Eau De Parfum",
      "quantity": 2
    },
    {
      "name": "Plumping Matte Lip Kit",
      "quantity": 1,
      "selectedVariant": {
        "Shade": "candy k"
      }
    }
  ],
  "options": {
    "verifyBeforePlacement": false,
    "useSavedCredentialToLogin": false,
    "useGuestCheckoutIfLoginFails": false,
    "allowInteraction": false,
    "allowPartialCheckout": true
  },
  "addons": {
    "couponCode": ["SUMMER15"]
  }
}

Response

On success the API returns HTTP 201 with the queued task(s).

{
  "status": "success",
  "message": "Checkout tasks submitted",
  "groupId": "01a1f857-0a5b-7371-a70e-0513656b448e",
  "tasks": [
    {
      "taskId": "01a1f857-0a68-7233-abf2-faec6856e343",
      "executionId": "01a1f857-0a68-7233-abf2-fad75e4b2d81",
      "status": "queued",
      "merchant": "aloyoga.com",
      "liveUrl": "https://web.cartai.ai/v2/live-preview?id=eyJ0aWQiOiAiMDFhMWY4NTctMGE2OC03MjMzLWFiZjItZmFlYzY4NTZlMzQzIiwgImV4ZWN1dGlvbl9pZCI6ICIwMWExZjg1Ny0wYTY4LTcyMzMtYWJmMi1mYWQ3NWU0YjJkODEifQ=="
    }
  ]
}
Body Params
customer
object
required
uri
required

Merchant website URL to search and check out from

itemList
array of objects
required
itemList*
options
object
addons
object
Headers
string
required
Responses

400

Bad Request

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json