---
updatedAt: 2026-11-20T11:45:35.000Z
agentTools:
  projectIndex: https://docs.cartai.ai/llms.txt
---

# Create Checkout Task

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.

## How it Works

This is an **asynchronous API**. When you call `POST /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.
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.

<Callout icon="⚠️" theme="warn">
  ### **Do not re-submit the same payload on success.** A `201` response means the task was accepted. Resubmitting creates a duplicate checkout.
</Callout>

***

## Authentication

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

```http
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 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)

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

#### `customer.contact`

Personal 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. `+12144444444`). **Pattern:** `^[+0-9\- ]{7,20}$` |

#### `customer.shippingAddress`

Where 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`

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

<Callout icon="💡" theme="default">
  ### If billing and shipping addresses are the same, send identical objects for both. The API does not auto-copy them.
</Callout>

#### `customer.shippingMethod`

Controls 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`

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.

| 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)

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.

<br />

#### 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

| 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.                                   |

<Callout icon="⚠️" theme="warn">
  ### 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.
</Callout>

<br />

***

### `options` (object, optional)

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

| Field                          | Type    | Default | Description                                                                                                                                                                                                                                                                                                        |
| ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `verifyBeforePlacement`        | boolean | `false` | When `true`, the agent asks for confirmation just before placing the order. The task pauses in `PENDING_CONFIRMATION` until the order is confirmed.                                                                                                                                                                |
| `useSavedCredentialToLogin`    | boolean | `false` | When `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](https://docs.cartai.ai/reference/create_credential_session) API. Credentials must be saved first.                                                              |
| `useGuestCheckoutIfLoginFails` | boolean | `false` | When `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`.                                                                                                                                  |
| `allowInteraction`             | boolean | `false` | When `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](https://docs.cartai.ai/reference/send_interactive_inputs).                                                            |
| `allowPartialCheckout`         | 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. |

<br />

### `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. |

***

## Response

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

```json
{
  "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=="
    }
  ]
}
```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Cart AI",
    "version": "1.0.0",
    "description": ""
  },
  "servers": [
    {
      "url": "https://api.cartai.ai"
    }
  ],
  "paths": {
    "/checkout": {
      "post": {
        "summary": "Create Checkout Task",
        "tags": [],
        "description": "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.",
        "parameters": [
          {
            "in": "header",
            "name": "X-Api-Key",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Checkout tasks submitted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "Checkout tasks submitted"
                    },
                    "groupId": {
                      "type": "string",
                      "description": "Identifier grouping all tasks submitted in this request"
                    },
                    "tasks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "taskId": {
                            "type": "string"
                          },
                          "executionId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "example": "queued"
                          },
                          "merchant": {
                            "type": "string"
                          },
                          "liveUrl": {
                            "type": "string",
                            "format": "uri",
                            "description": "Live preview URL for watching the checkout run"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "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=="
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "customer",
                  "tasks"
                ],
                "properties": {
                  "customer": {
                    "type": "object",
                    "properties": {
                      "contact": {
                        "type": "object",
                        "properties": {
                          "lastName": {
                            "type": "string"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "phone": {
                            "type": "string",
                            "pattern": "^[+0-9\\- ]{7,20}$"
                          },
                          "email": {
                            "type": "string",
                            "format": "email"
                          }
                        }
                      },
                      "shippingAddress": {
                        "type": "object",
                        "properties": {
                          "addressLine1": {
                            "type": "string"
                          },
                          "addressLine2": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "province": {
                            "type": "string"
                          },
                          "postalCode": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9\\- ]{3,10}$"
                          },
                          "country": {
                            "type": "string"
                          }
                        }
                      },
                      "billingAddress": {
                        "type": "object",
                        "properties": {
                          "addressLine1": {
                            "type": "string"
                          },
                          "addressLine2": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "province": {
                            "type": "string"
                          },
                          "postalCode": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9\\- ]{3,10}$"
                          },
                          "country": {
                            "type": "string"
                          }
                        }
                      },
                      "shippingMethod": {
                        "type": "object",
                        "properties": {
                          "strategy": {
                            "type": "string"
                          }
                        }
                      },
                      "payment": {
                        "type": "object",
                        "properties": {
                          "provider": {
                            "type": "string"
                          },
                          "data": {
                            "type": "object",
                            "properties": {
                              "cvv": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "cardNumber": {
                                "type": "string"
                              },
                              "expiryYear": {
                                "type": "string"
                              },
                              "expiryMonth": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "tasks": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "url",
                        "quantity"
                      ],
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "selectedVariant": {
                          "type": "object",
                          "properties": {
                            "color": {
                              "type": "string"
                            },
                            "size": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "verifyBeforePlacement": {
                        "type": "boolean",
                        "default": false,
                        "description": "Agent asks for confirmation just before placing the order"
                      },
                      "useSavedCredentialToLogin": {
                        "type": "boolean",
                        "default": false,
                        "description": "Agent signs in using the stored credentials created with the Create Credential Vault Session API"
                      },
                      "useGuestCheckoutIfLoginFails": {
                        "type": "boolean",
                        "default": false,
                        "description": "If the stored credentials do not work, the agent falls back to guest checkout when the merchant offers it"
                      },
                      "allowInteraction": {
                        "type": "boolean",
                        "default": false,
                        "description": "Enables the interactive flow instead of fire-and-forget; the agent can request additional input if it needs it"
                      },
                      "allowPartialCheckout": {
                        "type": "boolean",
                        "default": false,
                        "description": "If some items fail (e.g. out of stock), the agent still completes checkout for the remaining items"
                      }
                    }
                  },
                  "addons": {
                    "type": "object",
                    "properties": {
                      "couponCode": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "New Example": {
                  "summary": "New Example",
                  "value": {
                    "customer": {
                      "contact": {
                        "lastName": "Sturka",
                        "firstName": "Carol",
                        "phone": "+12144444444",
                        "email": "john.doe@example.com"
                      },
                      "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": {
                        "data": {
                          "cvv": "444",
                          "name": "Carol Sturka",
                          "cardNumber": "4242424242424242",
                          "expiryYear": "2034",
                          "expiryMonth": "12"
                        },
                        "provider": "test"
                      }
                    },
                    "tasks": [
                      {
                        "url": "https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory",
                        "quantity": 1,
                        "selectedVariant": {
                          "color": "Ivory",
                          "size": "S"
                        }
                      }
                    ],
                    "options": {
                      "verifyBeforePlacement": false,
                      "useSavedCredentialToLogin": false,
                      "useGuestCheckoutIfLoginFails": false,
                      "allowInteraction": false,
                      "allowPartialCheckout": true
                    },
                    "addons": {
                      "couponCode": [
                        "SUMMER15"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {}
}
```