Agent Checkouts Quickstart ⚡

Start a checkout, answer buyer requests, and read the result

Send the agent a product URL and a task. It navigates the merchant’s checkout, asks your application for missing inputs or payment authorization, and returns the purchase result.

Try the Live Demo

Explore the complete experience in a working app

View the Sample App

Use the full integration as a reference for your app

Prerequisites

• API key: A production server-side key with agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel scopes from the Crossmint Console
• Buyer identity: A stable identifier for your user, sent as x-crossmint-user-id on every request
• Purchase task: A product URL, the variant and quantity to buy, and a spending cap
• Card authorization: To complete a card purchase, a saved and registered card, plus a client-side key and buyer JWT as described in Authorize Payments

Use the same user ID as your JWT’s configured user ID claim (sub by default), so the checkout and its card authorization belong to the same buyer.

Agent Checkouts does not support staging. These examples run on your backend; keep the server key out of browser code. For direct browser calls, see Authenticate Each Request.

Agent Checkouts and the live demo can place real orders. Use a task and spending cap that you intend to authorize.

Run a Checkout

1. Start the checkout

   Set these variables in your terminal. Reuse them in the following steps:

   export CROSSMINT_API_KEY="YOUR_SERVER_API_KEY"
   export CROSSMINT_USER_ID="YOUR_USER_ID"
   export CHECKOUT_API="https://www.crossmint.com/api/unstable/agent-checkouts"
   

   Replace the sample URL and task with your intended purchase, then create a run:

   cURL

   curl --fail-with-body --request POST "$CHECKOUT_API" \
       --header "X-API-KEY: $CROSSMINT_API_KEY" \
       --header "x-crossmint-user-id: $CROSSMINT_USER_ID" \
       --header "Content-Type: application/json" \
       --data '{
           "request": {
               "startUrl": "https://merchant.example/products/classic-tee",
               "task": "Buy one black Classic Tee in size medium. Use standard delivery and pay by card."
           },
           "constraints": {
               "maxCost": { "amount": "100.00", "currency": "USD" }
           }
       }'
   

   The response contains a runId. Save it for subsequent calls:

   export RUN_ID="YOUR_RETURNED_RUN_ID"
   

   To prefill shipping details or set the browser country, see Configure a Checkout.

2. Read the run

   Read its current status and any request waiting for your application:

   cURL

   curl --fail-with-body "$CHECKOUT_API/$RUN_ID" \
       --header "X-API-KEY: $CROSSMINT_API_KEY" \
       --header "x-crossmint-user-id: $CROSSMINT_USER_ID"
   

   While the run is active, repeat this read every 2 seconds. When status is "awaiting_input", handle requiredAction. Your application chooses how to present the request: in a web page, a native app, or a conversation.

   requiredAction.request.interaction.kind	What your application does
   form	Collect the requested fields. Use ordinary controls for handling: "standard" and CrossmintProtectedInput for handling: "protected".
   payment	Authorize the buyer’s saved card with an order intent.

   For live updates and conversation history, see Follow a Run. You can optionally display the agent’s browser using run.browser.embedUrl once run.browser is available.

3. Answer the request

   Copy requiredAction.requestId into your response. For example, if a form requests a standard field whose key is email, send the buyer’s answer:

   cURL

   curl --fail-with-body --request POST "$CHECKOUT_API/$RUN_ID/messages" \
       --header "X-API-KEY: $CROSSMINT_API_KEY" \
       --header "x-crossmint-user-id: $CROSSMINT_USER_ID" \
       --header "Content-Type: application/json" \
       --data '{
           "id": "answer_email_001",
           "parts": [{
               "type": "input_response",
               "requestId": "YOUR_FORM_REQUEST_ID",
               "action": "submit",
               "response": { "kind": "form", "answers": { "email": "[e-mail]" } }
           }]
       }'
   

   Each submission answers the complete request: include all required fields, and omit optional fields left unanswered. Handle Buyer Inputs shows the field types, ordinary rendering, and protected collection.

   When the agent asks for payment, follow Authorize Payments to create an order intent for the request’s amount and merchant using the same buyer’s saved card. Complete any verification, then submit this body to the same messages endpoint:

   {
       "id": "answer_payment_001",
       "parts": [{
           "type": "input_response",
           "requestId": "YOUR_PAYMENT_REQUEST_ID",
           "action": "submit",
           "response": { "kind": "payment", "orderIntentId": "YOUR_ORDER_INTENT_ID" }
       }]
   }
   

   Use a unique message id for each answer. If you retry after a lost acknowledgement, resend the same ID and body. A payment answer contains the order intent ID; it never contains card details.

4. Read the result

   After each answer, resume reading the run and handle further requests until it finishes. A read can briefly show a request you already answered; handle each requestId only once, retrying its original message if needed.

   At a terminal status, read the result:

   Status	What to read
   succeeded	result.summary describes the purchase. If result.purchase.kind is "receipt_captured", read result.purchase.receipt.
   blocked	result.code and result.summary explain why the agent stopped.
   failed	reason explains the failure.
   cancelled	Cancellation has completed.

   An accepted answer resumes the agent. The final run status tells you whether the purchase succeeded.

   To stop an active run, request cancellation and keep reading until it reaches a terminal status:

   cURL

   curl --fail-with-body --request POST "$CHECKOUT_API/$RUN_ID/cancel" \
       --header "X-API-KEY: $CROSSMINT_API_KEY" \
       --header "x-crossmint-user-id: $CROSSMINT_USER_ID"
   

   See Finish or Cancel for the complete result behavior.

Launching in Production

Agent Checkouts already uses production credentials. Before serving buyers, add streaming and recovery, buyer input handling, and payment authorization for your application’s user experience. The sample app above shows how these pieces fit together.

If a create-run acknowledgement is lost, inspect List Checkouts before creating another run.

Learn More

Configure a Checkout

Prefill buyer details and set merchant guidance

Follow a Run

Stream updates, steer the agent, and recover after disconnects