---
updatedAt: 2026-11-17T18:17:47.000Z
agentTools:
  projectIndex: https://docs.cartai.ai/llms.txt
---

# Checkout Task Webhooks

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}`.<br />

> This page covers the events and payloads specific to checkout tasks. For endpoint setup, authentication, and expected responses, see [Webhooks](https://docs.cartai.ai/reference/webhooks) (general).

<br />

***

## 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 the `requiredInputs` array of the webhook payload. See [Interactive Checkouts](#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](#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[]`](#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`](#deriveddetails). |
| `customer`       | object            | The customer object from the original `POST /checkout` request, returned unchanged. See [`customer`](#customer).                                                                  |
| `requiredInputs` | array             | Only in interactive checkouts (`allowInteraction: true`). Input the agent needs from the customer before it can continue. See [Interactive Checkouts](#interactive-checkouts).    |

***

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

Filled 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"`). |

> `derivedDetails` matters most in confirmation flows. When you receive `PENDING_CONFIRMATION`, call `GET /checkout/{taskId}` for the full pricing breakdown and show it to the customer before they confirm.

***

### `customer`

The 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:

```json
{
  "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": "carol.sturka@gmail.com",
      "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[]`

```json
"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](https://json-schema.org/) 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.

```html
<iframe src="https://credshield.cartai.ai?isMfaFlow=true&taskId=...&token=..." width="400" height="500"></iframe>
```

#### Option 2: Build your own UI from `inputSchema`

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

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

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

```javascript
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](#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 +&#x20;**`GET /checkout/{taskId}`**:** webhooks tell you *when* something changed. When you need the latest `derivedDetails` that may not be in the webhook payload yet, call `GET /checkout/{taskId}`.

***