Checkouts

CartAI's Checkout APIs power the full lifecycle of an AI-driven purchase — from placing an order across any supported merchant to monitoring its progress in real time and cancelling it if needed. The AI agent handles the entire checkout flow autonomously: adding items to cart, selecting shipping, filling addresses, and processing payment.

The Four Checkout Endpoints

How They Work Together

Checkout is asynchronous. You create a task, get a taskId back immediately, and then track the task as the AI agent executes in the background. The other three endpoints give you visibility and control over that running task.

POST /checkout
    │  returns taskId (201)
    │
    ├──▶ Webhooks (recommended)
    │        push status events as the agent progresses
    │
    ├──▶ GET /checkout/{taskId}
    │        poll for current state, derivedDetails, and pricing
    │
    ├──▶ POST /checkout/cancel
    │        abort the task if the customer changes their mind
    │
    └──▶ GET /status-history/{taskId}
             full step-by-step audit trail after execution

Step 1 — Create: POST /checkout

The entry point. Pass in the customer details, product URLs, and payment information — CartAI queues the task and returns a taskId within milliseconds. The actual checkout runs in the background.

Key inputs:

• customer — contact info, shipping address, billing address, shipping strategy ("cheapest" or "fastest"), and payment provider
• tasks[] — one or more product URLs with quantities and variant selections; CartAI automatically groups them by merchant
• options — set allowPartialCheckoutForMultiSku: true to allow partial fulfillment when some items in a multi-SKU order fail

Key output to carry forward:

• taskId — the UUID you will use in every subsequent call; store it immediately

{
  "customer": {
    "contact": { "firstName": "Carol", "lastName": "Sturka", "email": "[email protected]", "phone": "5555555555" },
    "shippingAddress": { "addressLine1": "123 Main St", "city": "New York", "province": "NY", "postalCode": "10001", "country": "US" },
    "shippingMethod": { "strategy": "cheapest" },
    "payment": { "provider": "test", "data": { "cardNumber": "4242424242424242", "expiryMonth": "12", "expiryYear": "2034", "cvv": "444" } }
  },
  "tasks": [
    { "url": "https://www.natori.com/products/feathers-plunge-t-shirt-bra-black", "quantity": 1, "selectedVariant": { "color": "Black", "size": "32C" } }
  ]
}

A 201 response confirms the task was accepted — not that checkout succeeded. Never resubmit the same payload on a 201; it creates a duplicate order.

Step 2 — Track: GET /checkout/{taskId}

Use this to check what the task is doing right now. It returns the current status, the customer data echoed back, and derivedDetails — the live pricing and shipping data the AI agent discovers as it moves through checkout.

Key outputs:

• status — current lifecycle state (e.g. IN_PROGRESS, COMPLETED, FAILED)
• derivedDetails.pricing — actual subtotal, shipping, and tax as seen by the agent at the merchant's checkout — the source of truth for what the customer will be charged
• derivedDetails.selectedShippingOption — the exact shipping option the agent picked
• iterations[] — all execution attempts if the task was retried; use executionId from the latest iteration when calling cancel

derivedDetails is the most valuable part of this response for customer-facing UIs. It contains the real total the customer will be charged — which may differ from the listed price due to merchant-applied tax and shipping.

Step 3 — Cancel: POST /checkout/cancel

Sends a cancellation signal to the AI agent. This is asynchronous — a 200 OK means the request was accepted, not that the task has already stopped. The agent winds down in the background; confirmation arrives via the CANCELLED webhook event.

Required inputs:

• taskId — from Step 1
• executionId — from the latest GET /checkout/{taskId} response or from the most recent webhook payload; identifies the specific execution attempt to stop

{
  "taskId": "019bd5c5-2824-76d1-aa7a-01db5c4d7065",
  "executionId": "019bd5d7-aba0-7080-95e0-8b183f4eca0b"
}

Key behaviours:

• Cancellation is irreversible — a cancelled task cannot be resumed. To retry the same order, create a new task via POST /checkout.
• You cannot cancel a task already in a terminal state (COMPLETED, FAILED, or CANCELLED) — those will return a 400.
• For multi-merchant orders, each merchant task has its own taskId and executionId. Cancel each one individually — there is no group-level cancel.
• If the agent had already reached the payment step before cancellation was processed, any charge must be refunded through your payment provider.

Step 4 — Audit: GET /status-history/{taskId}

Returns a flat, reverse-chronological list of every step the AI agent recorded — including granular step labels, timestamps, credit consumption per step, and failure flags. This is your primary debugging and reconciliation tool.

Key output fields per step:

• status — fine-grained agent action (e.g. ADD_TO_CART, SHIPPING_SELECTED, CREDIT_CARD_INPUT, ORDER_CONFIRMED)
• systemStatus — coarse lifecycle phase matching what webhooks emit (e.g. IN_PROGRESS, COMPLETED, FAILED)
• creditsConsumed — credits used at this step; sum across all steps to calculate total task cost
• isFailed — whether this specific step was a failure point, even if the overall task eventually recovered
• note — optional system note when isFailed: true, giving context on what went wrong

End-to-End Example

A user purchases a bra from Natori. Here is how the four endpoints serve that journey:

Checkout Task Lifecycle

The AI agent progresses through these system-level states from creation to completion:

QUEUED → STARTED → IN_PROGRESS → COMPLETED
                              ↘ FAILED
                              ↘ CANCELLED