Retrieves the full state of an existing checkout task — including its current status, execution history, derived pricing and shipping details, and the original customer and product data. Use this endpoint to track the progress of an asynchronous checkout task created via POST /checkout.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
When to Use This Endpoint
POST /checkout is asynchronous — it returns a taskId immediately but the actual checkout runs in the background. You need a way to know what happened.
The recommended approach is webhooks. CartAI will push status events to your server as each transition occurs. Use this GET endpoint as a complement to webhooks, or as a fallback when webhooks are not available in your environment.
| Use case | Recommended approach |
|---|---|
| Production app, real-time updates | Webhooks (push) — lower latency, no polling overhead |
| After receiving a webhook event | Call GET /checkout/{taskId} to fetch full derivedDetails |
| Webhook delivery not possible | Poll GET /checkout/{taskId} every few seconds |
| Debugging / inspection | Call GET /checkout/{taskId} on demand |
| Showing order summary to user | Call after any status |
Do not poll at very high frequency. If webhooks are unavailable, a 5–10 second polling interval is appropriate. Polling every second will generate unnecessary load and may trigger rate limits.
Authentication
Every request must include your API key in the request header.
X-Api-Key: YOUR_API_KEY_HERE- Use
X-Api-Key(capital X and A) — this header name is case-insensitive in HTTP/1.1, but match the casing your client library normalises to. - Never embed your API key in client-side code. Always call this endpoint from your backend.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string (UUID) | ✅ Yes | The taskId returned by POST /checkout when the task was created. Example: 019af513-ea98-7d21-8f36-3dbe36dd4e05 |
Response Schema
A successful 200 response returns a single JSON object. Here is every field explained.
Top-level fields
| Field | Type | Description |
|---|---|---|
tid | string (UUID) | The task identifier. Same as the taskId you passed in the path. |
executionId | string (UUID) | Unique ID for the current execution attempt. Changes on each retry/re-execution. See Understanding Iterations. |
executionNumber | integer | Which execution attempt this is. Starts at 1. Increments if CartAI retries the checkout. |
isLatest | boolean | true if this response reflects the most recent execution attempt. Always true when querying the task directly. |
status | string | Current lifecycle status of the task. See Checkout Task Lifecycle for all possible values. |
createdAt | string (datetime) | When this execution attempt was created. Format: YYYY-MM-DD HH:MM:SS.ffffff |
groupId | string (UUID) | Groups all sub-tasks belonging to the same logical order. In multi-merchant checkouts, each merchant gets its own task but they share a groupId. |
merchant | string | The merchant domain the agent is operating on (e.g. saltiebeauty.com). |
tasks | array of objects | The products included in this checkout task. See tasks[] below. |
derivedDetails | object | Data discovered by the AI agent during execution — actual pricing, shipping option selected, etc. Populated progressively. See derivedDetails below. |
customer | object | The full customer object as originally submitted. Echoed back for reference. See customer below. |
addons | object | The addons object as originally submitted. Echoed back for reference. See addons below. |
tasks[]
tasks[]The list of products this task is purchasing. Each item is an object with the following fields:
| Field | Type | Description |
|---|---|---|
url | string (URI) | The product page URL on the merchant's website. This is what the AI agent navigated to. |
quantity | integer | Number of units to purchase. |
selectedVariant | object | The variant selected for this product. Contains color, size, and fit string fields. Empty strings indicate the field was not specified or not applicable. |
options | object | null | Task-level execution options. null if not set. |
metadata | object | Your custom pass-through data. Contains title, description, primaryImage, and price. These are for your records — CartAI does not use them for execution. |
derivedDetails
derivedDetailsThis object is populated progressively by the AI agent as it moves through the checkout. Fields will be null in early stages and fill in as the agent discovers them.
| Field | Type | Populated when | Description |
|---|---|---|---|
pricing | object | null | After the agent reaches the checkout summary step | Actual pricing discovered at checkout — subtotal, shipping cost, tax, and total as shown by the merchant. |
shippingMethod | object | null | After the agent evaluates shipping options | The shipping strategy that was applied (e.g. { strategy: "cheapest" }). |
selectedShippingOption | string | null | After the agent selects a shipping method | The exact shipping option the agent picked (e.g. "Standard Shipping (Free)" or "UPS Ground - $5.99"). |
derivedDetailsis the most useful part of this response for displaying order summaries to your customers. It contains the actual total they will be charged, which may differ from the product's listed price due to shipping, tax, or merchant-applied discounts.
customer
customerAn echo of the customer object sent in the original POST /checkout request. All fields are returned as-is. This is useful for verifying what data was used without needing to look up your original request.
| Field path | Type | Description |
|---|---|---|
contact.firstName | string | Buyer's first name. |
contact.lastName | string | Buyer's last name. |
contact.email | string | Buyer's email address. |
contact.phone | string | Buyer's phone number. |
shippingAddress.addressLine1 | string | Primary street address. |
shippingAddress.addressLine2 | string | Suite, apartment, or unit (may be empty). |
shippingAddress.city | string | City. |
shippingAddress.province | string | State or province. |
shippingAddress.postalCode | string | ZIP or postal code. |
shippingAddress.country | string | Country. |
billingAddress | object | null | Billing address, same schema as shippingAddress. null if billing was not separately specified. |
shippingMethod.strategy | string | The shipping selection strategy used (e.g. "cheapest"). |
payment.provider | string | Payment provider name (e.g. "test"). |
payment.data | string | Test Card Information for the Checkout. |
addons
addonsAn echo of the addons object sent in the original POST /checkout request. Returned as-is for reference.
| Field | Type | Description |
|---|---|---|
couponCode | array of strings | The coupon or promo codes that were submitted for this checkout (e.g. ["SUMMER15"]). |
Bad Request