CartAI FAQ: Checkout

Checkout tasks, options, statuses, tracking, failures, and cancellation.

What is programmatic non-human-in-the-loop checkout?

It is a checkout that starts with one API call and finishes without a person stepping through the merchant’s site. CartAI handles cart, address, payment, and confirmation on the merchant’s own site. Your customer stays in your app, and the merchant stays the merchant of record. One request can include multiple products from more than one merchant.

How does CartAI place an order from a product URL?

Send POST /checkout with the product URL, customer details, and payment. CartAI completes the purchase on the merchant’s own site. The call is asynchronous. It returns 201 with a groupId and a list of tasks, one per merchant. Each task has a taskId, executionId, status, merchant, and liveUrl.

Can I start a checkout from product names instead of URLs?

Yes. POST /search-checkout takes a merchant and a list of item names. CartAI finds each item at that merchant and runs the checkout. If you already have a product URL, use POST /checkout.

What options can I set on a checkout?

All options are off by default.

Option

What it does

verifyBeforePlacement

Pauses the task at PENDING_CONFIRMATION until you confirm the order.

useSavedCredentialToLogin

Signs in to the merchant with credentials saved for that customer and merchant.

useGuestCheckoutIfLoginFails

Falls back to guest checkout if the saved credentials do not work.

allowPartialCheckout

Completes the remaining items if one item fails. When it is off, one failure stops the whole group.

A fifth option, allowInteraction, lets the checkout pause for customer input such as a one-time passcode. You can also pass promo codes in addons.couponCode. CartAI tries each code in order and skips any that are invalid.

How do I track an order?

Use webhooks. CartAI sends every status change to the endpoint you configure in the portal. You can also call GET /checkout/{taskId}. If you poll, poll every 5 to 10 seconds. The final order total is in derivedDetails.pricing. For a step by step record, call GET /checkout/{taskId}/status-history.

What statuses can a checkout have?

A successful checkout moves through QUEUED, STARTED, IN_PROGRESS, PLACED, and COMPLETED. With verifyBeforePlacement on, it also passes through PENDING_CONFIRMATION and CONFIRMED. A task can move to FAILED or CANCELLED from any stage. COMPLETED, FAILED, and CANCELLED are final.

What happens if an item is out of stock or a checkout fails?

Check stock first with Product Details and only offer variants that are available. If an item fails during checkout, allowPartialCheckout decides the outcome. When it is on, CartAI completes the remaining items. When it is off, the whole group stops. A failed task cannot be resumed. Call GET /checkout/{taskId}/status-history to see where it failed, then create a new checkout for the items you still want.

How do I cancel a checkout?

Send DELETE /checkout/{taskId}. A 200 means the cancellation was accepted. The CANCELLED webhook confirms the task has stopped. Cancellation cannot be undone, and a task that is already COMPLETED, FAILED, or CANCELLED cannot be cancelled. If the order was already placed, cancel it or return it with the merchant under the merchant’s policy. Orders that span several merchants have one task per merchant, so cancel each task separately.

Can CartAI check out on merchants that require a login?

Yes. Your customer saves their merchant login once, on a secure page hosted by CartAI. Set useSavedCredentialToLogin to true and the agent signs in with that login at checkout. Logins are saved per customer and per merchant, and they never pass through your backend. Set useGuestCheckoutIfLoginFails to true if you want the agent to fall back to guest checkout when a login does not work.

How do I save a customer’s merchant login?

Call POST /credentials/session from your backend with the merchant domain and the customer’s email. The response returns a secure link. Embed it in an iframe or send it to the customer, and they enter their login there. The link is short lived, so create it right before you show it. At checkout, use the same email and a product URL on the same merchant domain. For a shared business account, an admin can enter the login instead of the customer.

What happens when a merchant asks for a verification code?

Set allowInteraction to true along with useSavedCredentialToLogin. When the merchant asks for a one-time passcode, the checkout pauses and CartAI sends a webhook that lists the input it needs. Your customer enters the code on a screen hosted by CartAI, or in your own UI, which then sends it to the Send Interactive Inputs endpoint. The checkout resumes once the code is in. Codes expire quickly, so send the code as soon as the customer enters it.

Can a checkout pause for customer input?

Yes. Set allowInteraction to true and the checkout pauses whenever the agent needs input from your customer. That covers one-time passcodes, multi-factor prompts, and any choice the agent meets during checkout. Send the answer through the Send Interactive Inputs endpoint and the checkout resumes. With allowInteraction off, the checkout runs start to finish with no input.

© 2026 CartAI · All rights reserved.