This API creates an asynchronous AI-powered checkout task that manages the entire purchase lifecycle — from cart assembly and shipping selection to payment processing and order confirmation — across one or many merchants in a single call.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
How it Works
This is an asynchronous API. When you call POST /checkout, it does not wait for the checkout to complete. Instead, it:
- Validates your request and queues the task.
- Returns a
taskIdimmediately (HTTP201). - Runs the checkout in the background using CartAI's AI agents.
- 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. A201response means the task was accepted. Resubmitting creates a duplicate checkout.
Authentication
Every request must include your API key in the request header.
x-api-key: YOUR_API_KEY_HERESecurity 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 four top-level keys:
| Key | Type | Required | Description |
|---|---|---|---|
customer | object | ✅ Yes | Customer identity, addresses, payment, and shipping preference |
tasks | array of objects | ✅ Yes | One or more products to purchase |
options | object | ❌ No | Execution control flags |
addons | object | ❌ No | Optional enhancements such as coupon codes |
customer (object, required)
customer (object, required)Contains all information CartAI needs to identify the buyer, ship the order, and process payment.
customer.contact
customer.contactPersonal contact details of the buyer.
| Field | Type | Description |
|---|---|---|
firstName | string | Buyer's given name, as it will appear on shipping labels. |
lastName | string | Buyer's surname. |
email | string (email format) | Valid email address. Used by the merchant for order confirmation. |
phone | string | Contact phone number. Supports international formats (e.g. +15555555555). Pattern: ^[+0-9\- ]{7,20}$ |
customer.shippingAddress
customer.shippingAddressWhere the order should be physically delivered.
| Field | Type | Description |
|---|---|---|
addressLine1 | string | Primary street address (house number + street name). |
addressLine2 | string | Optional — apartment, suite, floor, unit, etc. |
city | string | City name. |
province | string | State, province, or region. Can be abbreviated (NY) or full (New York). |
postalCode | string | ZIP or postal code. Pattern: ^[A-Za-z0-9\- ]{3,10}$ |
country | string | Country name or ISO code (e.g. US or United States). |
customer.billingAddress
customer.billingAddressBilling 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
customer.shippingMethodControls how the AI agent selects a shipping option at the merchant's checkout.
| Field | Type | Description |
|---|---|---|
strategy | string | Currently supported: "cheapest" and "fastest" — the default agent behavior is to select the lowest-cost ie cheapest shipping option available. |
customer.payment
customer.paymentConfigures 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.
| Field | Type | Description |
|---|---|---|
provider | string | Name of the payment provider. Example: "test". Must match a provider configured in your CartAI account. |
data | string | The buyer's identifier within the payment provider's system. CartAI uses this to look up their stored payment credentials. |
tasks (array of objects, required)
tasks (array of objects, required)Each item in the array represents one product to purchase. A single API call can include products from one or many merchants — CartAI groups them automatically by merchant based on the product URL.
Task object fields
| Field | Type | Required | Description |
|---|---|---|---|
url | string (URI) | ✅ Yes | Full product page URL on the merchant's website. CartAI's agent uses this to identify the merchant, navigate the product page, select variants, and proceed through checkout. Must be a canonical, publicly accessible URL. Avoid shortened URLs or redirect chains — use the final destination URL. |
quantity | integer | ✅ Yes | Number of units to purchase. Minimum: 1. |
selectedVariant | object | ❌ No | Specifies which product variant to select during checkout. If omitted, the agent may pick the default or fail if variant selection is mandatory. |
selectedVariant fields
selectedVariant fields| Field | Type | Description |
|---|---|---|
color | string | Color variant label as shown on the merchant's product page (e.g. "wild poppy atlas 5530"). Match the label exactly. |
size | string | Size label (e.g. "S", "M", "32x30"). Match the merchant's exact display value. |
Variant labels are case-sensitive and must match exactly what the merchant's site displays. A mismatch can cause the agent to select the wrong variant or fail the task.
options (object, optional)
options (object, optional)Execution control flags that modify the checkout agent's behaviour.
| Field | Type | Default | Description |
|---|---|---|---|
allowPartialCheckoutForMultiSku | boolean | false | When true, if some products in the tasks array fail (e.g. out of stock), CartAI will still complete the checkout for the remaining successful items. Recommended for multi-SKU or multi-merchant carts where partial fulfillment is acceptable. When false, any single task failure aborts the entire group. |
addons (object, optional)
addons (object, optional)Optional enhancements to apply during checkout, such as discount codes.
| Field | Type | Description |
|---|---|---|
couponCode | array of strings | One 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. |
Bad Request