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

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 the requiredInputs array of the webhook payload. See Interactive Checkouts.

Terminal failure paths:

any stage → FAILED
any stage → CANCELLED
EventDescriptionderivedDetails populated?
QUEUEDCartAI has accepted the checkout task, and it is waiting in the execution queue. No agent has started yet.No
STARTEDAn AI agent has claimed the task and begun execution.No
IN_PROGRESSThe 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_CONFIRMATIONThe 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
CONFIRMEDThe customer confirmed the order, and the agent will now place it. Only occurs in confirmation-required flows.Yes
PLACEDThe order has been submitted to the merchant and is awaiting final confirmation.Yes
COMPLETEDThe checkout is complete and the order is confirmed. Terminal success state.Yes, all fields
CANCELLEDThe task was cancelled, either by the customer during PENDING_CONFIRMATION or by your application via DELETE /checkout/{taskId}. Terminal state.Partial or none
FAILEDThe 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

FieldTypeDescription
tidstring (UUID)The task ID. Matches the taskId returned by POST /checkout. Use this to look up the task in your system.
statusstringThe status change that triggered this webhook. See Event Lifecycle for all values.
createdAtstring (ISO 8601)When this event was generated.
groupIdstring (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.
merchantstringThe merchant domain the agent is working on (e.g. saltiebeauty.com).
tasksarrayThe products in this checkout task. See tasks[].
derivedDetailsobjectPricing, shipping, and other data the agent finds on the merchant site. Filled in as the checkout progresses and null in early stages. See derivedDetails.
customerobjectThe customer object from the original POST /checkout request, returned unchanged. See customer.
requiredInputsarrayOnly in interactive checkouts (allowInteraction: true). Input the agent needs from the customer before it can continue. See Interactive Checkouts.

tasks[]

FieldTypeDescription
urlstringThe product page URL the agent is buying from.
quantityintegerNumber of units being bought.
selectedVariant.colorstringSelected color variant (empty string if not specified).
selectedVariant.sizestringSelected size variant (empty string if not specified).
selectedVariant.fitstringSelected fit variant (empty string if not specified).
optionsobject | nullTask-level execution options. null if not set.
metadataobjectYour 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.

FieldTypeAvailable fromDescription
pricingobject | nullPENDING_CONFIRMATION or laterThe actual pricing shown on the merchant's checkout page: subtotal, shipping cost, tax, and grand total.
shippingMethodobject | nullPENDING_CONFIRMATION or laterThe shipping strategy applied (e.g. { "strategy": "cheapest" }).
selectedShippingOptionstring | nullPENDING_CONFIRMATION or laterThe 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 pathTypeDescription
contact.firstNamestringBuyer's first name.
contact.lastNamestringBuyer's last name.
contact.emailstringBuyer's email.
contact.phonestringBuyer's phone number.
shippingAddressobjectFull shipping address (addressLine1, addressLine2, city, province, postalCode, country).
billingAddressobject | nullBilling address, same fields as shippingAddress. null if not provided separately.
shippingMethod.strategystringShipping strategy used (e.g. "cheapest").
payment.providerstringPayment provider name (e.g. "test").
payment.dataobjectPayment 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": [
  {
    "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"]
    }
  }
]
FieldTypeDescription
typestringHow the input can be collected. hosted-screen means CartAI provides a ready-made screen at the URL in value.
intentstringWhy the agent needs the input (e.g. mfa-request when the merchant asks for an OTP).
requiredbooleanWhether the agent needs this input to continue the checkout.
valuestringFor 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.
inputSchemaobjectA 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

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

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

EventRecommended action
QUEUED, STARTED, IN_PROGRESSInformational. Optionally update a progress indicator.
Any event with requiredInputsAction required. Show the customer the hosted screen from value, or a form built from inputSchema. See Interactive Checkouts.
PENDING_CONFIRMATIONAction required. Fetch GET /checkout/{tid}, show pricing to the customer, and collect a Confirm or Cancel decision.
CONFIRMED, PLACEDUpdate the order status in your records.
COMPLETEDFinalise the order and notify the customer.
CANCELLEDMark the order as cancelled. This event is the reliable signal that a DELETE /checkout/{taskId} request has taken effect.
FAILEDNotify 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 latest derivedDetails that may not be in the webhook payload yet, call GET /checkout/{taskId}.