When you create a checkout task via POST /checkout, CartAI's AI agent runs the purchase in the background. Every time the task changes status, CartAI sends a webhook event to your configured endpoint with the full task state at that moment. This lets you track each task from start to finish without polling GET /checkout/{taskId}.
This page covers the events and payloads specific to checkout tasks. For endpoint setup, authentication, and expected responses, see Webhooks (general).
Event Lifecycle
CartAI sends one webhook event per status transition. Every event carries the same tid (task ID) that POST /checkout returned as taskId, so you can match events to your own records.
POST /checkout ──► CartAI queues task
│
▼
CartAI POST /your-webhook-url
{ "tid": "...", "status": "QUEUED", ... }
│
Agent claims task
│
▼
CartAI POST /your-webhook-url
{ "tid": "...", "status": "STARTED", ... }
│
Agent navigates merchant site
│
▼
CartAI POST /your-webhook-url
{ "tid": "...", "status": "IN_PROGRESS", ... }
│
...
│
▼
CartAI POST /your-webhook-url
{ "tid": "...", "status": "COMPLETED", ... }
The full sequence for a successful checkout:
QUEUED → STARTED → IN_PROGRESS → [PENDING_CONFIRMATION] → [CONFIRMED] → PLACED → COMPLETED
Statuses in brackets only occur in confirmation-required flows.
Interactive checkouts: if you created the task with
allowInteraction: true, the agent may pause during checkout to ask the customer for input, such as an OTP for multi-factor authentication. These requests arrive in therequiredInputsarray of the webhook payload. See Interactive Checkouts.
Terminal failure paths:
any stage → FAILED
any stage → CANCELLED
| Event | Description | derivedDetails populated? |
|---|---|---|
QUEUED | CartAI has accepted the checkout task, and it is waiting in the execution queue. No agent has started yet. | No |
STARTED | An AI agent has claimed the task and begun execution. | No |
IN_PROGRESS | The agent is working on the merchant site: adding items to the cart, selecting a shipping option, and entering checkout details. | Partially. Fields may still be null. |
PENDING_CONFIRMATION | The agent has reached the final checkout step and is waiting for the customer to confirm the order. Action required. Only occurs in confirmation-required flows. | Yes |
CONFIRMED | The customer confirmed the order, and the agent will now place it. Only occurs in confirmation-required flows. | Yes |
PLACED | The order has been submitted to the merchant and is awaiting final confirmation. | Yes |
COMPLETED | The checkout is complete and the order is confirmed. Terminal success state. | Yes, all fields |
CANCELLED | The task was cancelled, either by the customer during PENDING_CONFIRMATION or by your application via DELETE /checkout/{taskId}. Terminal state. | Partial or none |
FAILED | The checkout could not be completed. Can happen at any stage after STARTED. Terminal failure state. | Partial or none |
Multi-merchant checkouts: each merchant gets its own task and its own stream of webhook events. All tasks from the same order share a
groupId, so you can combine them into a single order status in your UI.
Payload Schema
Every checkout task webhook has the same JSON structure, whatever the status. Fields that aren't known yet (for example, pricing before the agent reaches checkout) are null.
Top-level fields
| Field | Type | Description |
|---|---|---|
tid | string (UUID) | The task ID. Matches the taskId returned by POST /checkout. Use this to look up the task in your system. |
status | string | The status change that triggered this webhook. See Event Lifecycle for all values. |
createdAt | string (ISO 8601) | When this event was generated. |
groupId | string (UUID) | Shared by all tasks in the same order. In a multi-merchant checkout, each merchant has its own task and webhook events, but they all share one groupId. |
merchant | string | The merchant domain the agent is working on (e.g. saltiebeauty.com). |
tasks | array | The products in this checkout task. See tasks[]. |
derivedDetails | object | Pricing, shipping, and other data the agent finds on the merchant site. Filled in as the checkout progresses and null in early stages. See derivedDetails. |
customer | object | The customer object from the original POST /checkout request, returned unchanged. See customer. |
requiredInputs | array | Only in interactive checkouts (allowInteraction: true). Input the agent needs from the customer before it can continue. See Interactive Checkouts. |
tasks[]
tasks[]| Field | Type | Description |
|---|---|---|
url | string | The product page URL the agent is buying from. |
quantity | integer | Number of units being bought. |
selectedVariant.color | string | Selected color variant (empty string if not specified). |
selectedVariant.size | string | Selected size variant (empty string if not specified). |
selectedVariant.fit | string | Selected fit variant (empty string if not specified). |
options | object | null | Task-level execution options. null if not set. |
metadata | object | Your pass-through data (title, description, primaryImage, price), returned exactly as you sent it. |
derivedDetails
derivedDetailsFilled in as the agent moves through the checkout. Each field stays null until the agent reaches the matching step.
| Field | Type | Available from | Description |
|---|---|---|---|
pricing | object | null | PENDING_CONFIRMATION or later | The actual pricing shown on the merchant's checkout page: subtotal, shipping cost, tax, and grand total. |
shippingMethod | object | null | PENDING_CONFIRMATION or later | The shipping strategy applied (e.g. { "strategy": "cheapest" }). |
selectedShippingOption | string | null | PENDING_CONFIRMATION or later | The exact shipping option the agent selected (e.g. "Standard Shipping (Free)" or "UPS Ground - $5.99"). |
derivedDetailsmatters most in confirmation flows. When you receivePENDING_CONFIRMATION, callGET /checkout/{taskId}for the full pricing breakdown and show it to the customer before they confirm.
customer
customerThe customer object from your original request. All values are returned exactly as you sent them to POST /checkout.
| Field path | Type | Description |
|---|---|---|
contact.firstName | string | Buyer's first name. |
contact.lastName | string | Buyer's last name. |
contact.email | string | Buyer's email. |
contact.phone | string | Buyer's phone number. |
shippingAddress | object | Full shipping address (addressLine1, addressLine2, city, province, postalCode, country). |
billingAddress | object | null | Billing address, same fields as shippingAddress. null if not provided separately. |
shippingMethod.strategy | string | Shipping strategy used (e.g. "cheapest"). |
payment.provider | string | Payment provider name (e.g. "test"). |
payment.data | object | Payment tokens for real flows, or redacted card details for the test gateway. |
Full Payload Example
Below is a real IN_PROGRESS event. derivedDetails is still empty because the agent hasn't reached the checkout page yet:
{
"tid": "019af513-ea98-7d21-8f36-3dbe36dd4e05",
"status": "IN_PROGRESS",
"createdAt": "2025-12-06T19:11:54.519Z",
"groupId": "019af513-ea97-7552-91e9-e1f113ea0361",
"merchant": "saltiebeauty.com",
"tasks": [
{
"url": "https://saltiebeauty.com/products/sea-salt-texturizing-spray-enriched-with-sea-salt-marine-botanicals-8-fl-oz-250-ml",
"quantity": 1,
"selectedVariant": {
"color": "",
"size": "",
"fit": ""
},
"options": null,
"metadata": {
"title": "",
"description": "",
"primaryImage": "",
"price": ""
}
}
],
"derivedDetails": {
"pricing": null,
"shippingMethod": null,
"selectedShippingOption": null
},
"customer": {
"contact": {
"firstName": "Carol",
"lastName": "Sturka",
"email": "[email protected]",
"phone": "+16507083507"
},
"shippingAddress": {
"addressLine1": "6104 Plano Parkway",
"addressLine2": "",
"city": "Plano",
"province": "Texas",
"postalCode": "75093",
"country": "United States"
},
"billingAddress": null,
"shippingMethod": {
"strategy": "cheapest"
},
"payment": {
"data": {
"cvv": "***",
"name": "Carol Sturka",
"cardNumber": "************4242",
"expiryYear": "2034",
"expiryMonth": "12"
},
"provider": "test"
}
}
}Interactive Checkouts
Some merchants ask the shopper for extra input during checkout, such as a one-time password (OTP) sent by SMS or email. If you pass allowInteraction: true when creating the checkout task with POST /checkout, the agent pauses at that step. CartAI then sends a webhook event that includes a requiredInputs array describing what the agent needs.
Check every webhook event for a non-empty requiredInputs array, whatever its status.
requiredInputs[]
requiredInputs[]"requiredInputs": [
{
"type": "hosted-screen",
"intent": "mfa-request",
"required": true,
"value": "https://credshield.cartai.ai?isMfaFlow=true&taskId=01a1e420-877c-7ae0-b8ab-61d16a8c6df4&token=<jwt_token>",
"inputSchema": {
"type": "object",
"properties": {
"otp": {
"type": "string",
"title": "OTP",
"maxLength": 8,
"minLength": 4
}
},
"required": ["otp"]
}
}
]| Field | Type | Description |
|---|---|---|
type | string | How the input can be collected. hosted-screen means CartAI provides a ready-made screen at the URL in value. |
intent | string | Why the agent needs the input (e.g. mfa-request when the merchant asks for an OTP). |
required | boolean | Whether the agent needs this input to continue the checkout. |
value | string | For hosted-screen, the URL of the CartAI-hosted screen that collects the input. The URL carries a short-lived token tied to this task, so show it to the customer promptly. |
inputSchema | object | A JSON Schema describing the data the agent needs: field names, types, titles, and validation rules such as minLength and maxLength. |
Collecting the input
You can collect the input in either of two ways.
Option 1: Render the hosted screen (recommended)
Show the URL from value to the customer, either embedded in an iframe or opened in a browser window. The hosted screen collects the input and submits it to the CartAI agent for you, so you don't need any further API calls.
<iframe src="https://credshield.cartai.ai?isMfaFlow=true&taskId=...&token=..." width="400" height="500"></iframe>Option 2: Build your own UI from inputSchema
inputSchemaUse inputSchema to build a form that matches your app's design. Each key in properties is a field to collect. title gives the label, type the data type, and minLength / maxLength the validation rules. Every field listed in the schema's required array must be filled in.
For the example above, you would show a single text field labelled OTP that accepts 4 to 8 characters.
Example
function handleRequiredInputs(tid, requiredInputs = []) {
for (const input of requiredInputs) {
if (input.type === "hosted-screen") {
// Option 1: send the customer to the CartAI-hosted screen
showHostedScreen(tid, input.value);
} else {
// Option 2: build a form from the JSON Schema
renderFormFromSchema(tid, input.intent, input.inputSchema);
}
}
}Handling Each Checkout Task Event
Below is suggested handler logic for each checkout task event.
Deduplicating events
CartAI may deliver the same event more than once. Use tid + status + createdAt as a combined key to spot and skip duplicates. Including createdAt matters for interactive checkouts: a request for input can arrive in a new event that has the same status as an earlier one, and a key without createdAt would wrongly skip it.
async function isDuplicate(payload) {
const key = `${payload.tid}:${payload.status}:${payload.createdAt}`;
if (await cache.get(key)) return true;
await cache.set(key, true, { ex: 86400 }); // 24h TTL
return false;
}Example handler
app.post("/webhook", async (req, res) => {
res.status(200).json({ received: true }); // Always acknowledge first
const payload = req.body;
if (await isDuplicate(payload)) return;
const { tid, status, groupId, merchant, derivedDetails, requiredInputs } = payload;
// Interactive checkouts: the agent needs input from the customer
if (requiredInputs?.length) {
handleRequiredInputs(tid, requiredInputs);
}
switch (status) {
case "QUEUED":
// Optional: mark the task as "pending" in your UI
break;
case "STARTED":
case "IN_PROGRESS":
// Optional: show a "checkout in progress" indicator to the user
break;
case "PENDING_CONFIRMATION":
// Action required: show the customer their order summary
// Call GET /checkout/{tid} for full pricing
// Show Confirm / Cancel options to the customer
notifyCustomerToConfirm(tid, derivedDetails);
break;
case "CONFIRMED":
// Customer confirmed; the agent is placing the order
updateOrderStatus(tid, "confirmed");
break;
case "PLACED":
// Order submitted to the merchant; update your records
updateOrderStatus(tid, "placed");
break;
case "COMPLETED":
// ✅ Success: order confirmed and complete
finaliseOrder(tid);
sendOrderConfirmationEmail(payload.customer.contact.email);
break;
case "CANCELLED":
// Task was cancelled; clean up
markOrderCancelled(tid);
break;
case "FAILED":
// ❌ Checkout failed: notify the customer, consider retrying
handleFailure(tid, merchant);
alertOpsTeam(tid);
break;
}
});Event handling summary
| Event | Recommended action |
|---|---|
QUEUED, STARTED, IN_PROGRESS | Informational. Optionally update a progress indicator. |
Any event with requiredInputs | Action required. Show the customer the hosted screen from value, or a form built from inputSchema. See Interactive Checkouts. |
PENDING_CONFIRMATION | Action required. Fetch GET /checkout/{tid}, show pricing to the customer, and collect a Confirm or Cancel decision. |
CONFIRMED, PLACED | Update the order status in your records. |
COMPLETED | Finalise the order and notify the customer. |
CANCELLED | Mark the order as cancelled. This event is the reliable signal that a DELETE /checkout/{taskId} request has taken effect. |
FAILED | Notify the customer and your ops team. To retry, create a new checkout task. Use GET /checkout/{taskId}/status-history to debug where it failed. |
Webhooks +
GET /checkout/{taskId}: webhooks tell you when something changed. When you need the latestderivedDetailsthat may not be in the webhook payload yet, callGET /checkout/{taskId}.