Agent Checkouts Quickstart

Agent Checkouts buys on any website for your user. Choose how to start:

Try it out

See how Agent Checkouts handles a merchant. Purchases are real

Call the API

Start a checkout from your server with an API key, in about 5 minutes

Add it to your app

Paste one prompt into Claude Code, Cursor, or Codex

Call the API

Start a checkout from your server, follow it, answer its questions, and read the exact total at the payment step. Then cancel it, so that nothing is bought.

Prerequisites

Production server key — a key with the agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel scopes. Create it in the Crossmint Console, or ask your coding agent to create it with the Crossmint MCP server.
A user ID — any stable ID of your user, for example user-123. Send it in x-crossmint-user-id: each checkout belongs to that user.

Agent Checkouts uses production API keys. A staging key gets 403 with the message "Agent Checkouts is only available in production". See Test Agent Checkouts.

Start a checkout

Send a link to a product, the task, and the maximum amount to spend. Replace the link and the task with a real product. Set maxCost a little above the price, so that the checkout can reach the payment step.

curl --fail-with-body --request POST "https://www.crossmint.com/api/unstable/agent-checkouts" \
    --header "X-API-KEY: YOUR_SERVER_API_KEY" \
    --header "x-crossmint-user-id: YOUR_USER_ID" \
    --header "Content-Type: application/json" \
    --data '{
        "request": {
            "startUrl": "https://shop.example.com/products/sticker-pack",
            "task": "Go to the checkout for one sticker pack, with standard delivery."
        },
        "constraints": { "maxCost": { "amount": "20.00", "currency": "USD" } }
    }'

const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";
const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_SERVER_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};

const response = await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
        request: {
            startUrl: "https://shop.example.com/products/sticker-pack",
            task: "Go to the checkout for one sticker pack, with standard delivery.",
        },
        constraints: { maxCost: { amount: "20.00", currency: "USD" } },
    }),
});
if (!response.ok) {
    throw new Error(`Could not start checkout: ${response.status}`);
}
const { runId } = await response.json();

import os

import requests

BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts"
HEADERS = {
    "X-API-KEY": os.environ["CROSSMINT_SERVER_API_KEY"],
    "x-crossmint-user-id": "YOUR_USER_ID",
}

response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "request": {
            "startUrl": "https://shop.example.com/products/sticker-pack",
            "task": "Go to the checkout for one sticker pack, with standard delivery.",
        },
        "constraints": {"maxCost": {"amount": "20.00", "currency": "USD"}},
    },
)
response.raise_for_status()
run_id = response.json()["runId"]

The response has the checkout’s runId.

Read the checkout

Read the checkout every 2 seconds, until it waits for an answer (awaiting_input) or ends:

curl --fail-with-body "https://www.crossmint.com/api/unstable/agent-checkouts/YOUR_RUN_ID" \
    --header "X-API-KEY: YOUR_SERVER_API_KEY" \
    --header "x-crossmint-user-id: YOUR_USER_ID"

// Uses BASE_URL, headers, and runId from the previous step.
const WAIT_STATUSES = ["awaiting_input", "succeeded", "blocked", "failed", "cancelled"];

// Pass the requestId that you answered, to skip that question until the checkout moves on.
async function waitForCheckout(runId: string, answeredRequestId?: string) {
    while (true) {
        const response = await fetch(`${BASE_URL}/${runId}`, { headers });
        if (!response.ok) {
            throw new Error(`Could not read checkout: ${response.status}`);
        }
        const run = await response.json();
        const answered =
            run.status === "awaiting_input" && run.requiredAction?.requestId === answeredRequestId;
        if (WAIT_STATUSES.includes(run.status) && !answered) {
            return run;
        }
        await new Promise((resolve) => setTimeout(resolve, 2000));
    }
}

let run = await waitForCheckout(runId);

# Uses BASE_URL, HEADERS, and run_id from the previous step.
import time

WAIT_STATUSES = {"awaiting_input", "succeeded", "blocked", "failed", "cancelled"}


# Pass the requestId that you answered, to skip that question until the checkout moves on.
def wait_for_checkout(run_id, answered_request_id=None):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS)
        response.raise_for_status()
        run = response.json()
        answered = (
            run["status"] == "awaiting_input"
            and (run.get("requiredAction") or {}).get("requestId") == answered_request_id
        )
        if run["status"] in WAIT_STATUSES and not answered:
            return run
        time.sleep(2)


run = wait_for_checkout(run_id)

When status is awaiting_input, requiredAction.request.interaction holds the question. For every status, see Statuses, Results, and Errors.

Answer the questions

This step is optional: the checkout asks only for what it does not know, such as the email or the shipping address. When interaction.kind is "form", send one answer for each field in interaction.fields, by its key. Use the question’s requiredAction.requestId and a new message ID:

curl --fail-with-body --request POST "https://www.crossmint.com/api/unstable/agent-checkouts/YOUR_RUN_ID/messages" \
    --header "X-API-KEY: YOUR_SERVER_API_KEY" \
    --header "x-crossmint-user-id: YOUR_USER_ID" \
    --header "Content-Type: application/json" \
    --data '{
        "id": "msg_answer_1",
        "parts": [{
            "type": "input_response",
            "requestId": "YOUR_REQUEST_ID",
            "action": "submit",
            "response": { "kind": "form", "answers": { "email": "ada@example.com" } }
        }]
    }'

// Uses BASE_URL, headers, runId, run, and waitForCheckout from the previous steps.
const requestId = run.requiredAction.requestId;
const answerResponse = await fetch(`${BASE_URL}/${runId}/messages`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        id: crypto.randomUUID(),
        parts: [
            {
                type: "input_response",
                requestId,
                action: "submit",
                response: { kind: "form", answers: { email: "ada@example.com" } },
            },
        ],
    }),
});
if (!answerResponse.ok) {
    throw new Error(`Could not send answer: ${answerResponse.status}`);
}
run = await waitForCheckout(runId, requestId);

# Uses BASE_URL, HEADERS, run_id, run, and wait_for_checkout from the previous steps.
import uuid

request_id = run["requiredAction"]["requestId"]
response = requests.post(
    f"{BASE_URL}/{run_id}/messages",
    headers=HEADERS,
    json={
        "id": str(uuid.uuid4()),
        "parts": [
            {
                "type": "input_response",
                "requestId": request_id,
                "action": "submit",
                "response": {"kind": "form", "answers": {"email": "ada@example.com"}},
            }
        ],
    },
)
response.raise_for_status()
run = wait_for_checkout(run_id, request_id)

The checkout can still show the question that you answered for a short time after it accepts the answer, so the read skips that requestId. Repeat until the checkout reaches the payment step. To ask fewer questions, give the details up front in a buyer profile. See Configure a Checkout. For passwords and other protected fields, see Answer Questions.

Read the total and cancel

At the payment step, interaction.kind is "payment". When interaction.amount.kind is "exact", interaction.amount.value is the total, with shipping and tax:

{
    "kind": "payment",
    "method": "card",
    "amount": { "kind": "exact", "value": "12.49", "currency": "USD" },
    "merchant": { "name": "Example Shop", "url": "https://shop.example.com", "countryCode": "US" }
}

Do not answer the payment request. Cancel the checkout, so that nothing is bought:

curl --fail-with-body --request POST "https://www.crossmint.com/api/unstable/agent-checkouts/YOUR_RUN_ID/cancel" \
    --header "X-API-KEY: YOUR_SERVER_API_KEY" \
    --header "x-crossmint-user-id: YOUR_USER_ID"

// Uses BASE_URL, headers, and runId from the first step.
const cancelResponse = await fetch(`${BASE_URL}/${runId}/cancel`, { method: "POST", headers });
if (!cancelResponse.ok) {
    throw new Error(`Could not cancel checkout: ${cancelResponse.status}`);
}

# Uses BASE_URL, HEADERS, and run_id from the first step.
response = requests.post(f"{BASE_URL}/{run_id}/cancel", headers=HEADERS)
response.raise_for_status()

The cancel request returns 202 Accepted, and the status becomes cancelled.

To buy, answer the payment request instead of cancelling. To pay with your user’s own card, your app saves the card and the user approves the payment in your frontend: see Add It to Your App. For other methods, such as a card saved at the merchant or Shop Pay, see Pay for a Checkout.

Add It to Your App

Open your app’s repository in Claude Code, Cursor, or Codex, and paste this prompt. Your coding agent reads these docs and asks you how your users pay: with their own cards through Agent Cards or not, and when they save a card and approve a spending limit. Then it adds the checkout, its questions, and the payment step to your app. Connect the Crossmint MCP server to your coding agent first: then it also creates your production project, registers your auth provider, and creates your API keys.

Prompt

Add Crossmint Agent Checkouts to my app, so that my app or my agent can buy
products on any website for my users.

Read these docs first:
- https://docs.crossmint.com/agents/agent-checkouts-quickstart.md
- https://docs.crossmint.com/agents/checkouts/how-it-works.md
- https://docs.crossmint.com/agents/checkouts/configure.md
- https://docs.crossmint.com/agents/checkouts/follow-run.md
- https://docs.crossmint.com/agents/checkouts/buyer-inputs.md
- https://docs.crossmint.com/agents/checkouts/payments.md
- https://docs.crossmint.com/agents/checkouts/statuses.md
- https://docs.crossmint.com/mcp-server/connect.md
- https://docs.crossmint.com/mcp-server/tools.md
With Agent Cards, also read:
- https://docs.crossmint.com/agents/payment-methods/cards/save-card.md
- https://docs.crossmint.com/agents/payment-methods/cards/register-card.md
- https://docs.crossmint.com/agents/payment-methods/cards/create-agent-card.md
- https://docs.crossmint.com/agents/payment-methods/cards/list-order-intents.md

First, read my codebase. Tell me my framework, my auth provider, and where my
agent runs, if I have one. Then ask me:
1. Do my users pay with their own cards, saved in my app (Agent Cards)?
   Without Agent Cards, the checkout pays with other methods, such as a card
   saved at the merchant, Shop Pay, or Klarna.
2. With Agent Cards, when does the user save a card: ahead of time, for
   example on a settings page, or at the time of the first purchase?
3. With Agent Cards, when does the user approve a spending limit (an order
   intent): ahead of time, as a general limit for several purchases (an amount
   and an expiration, for example 200 USD for a month), or at the time of each
   purchase, for that purchase only?
Propose a plan from my answers and wait for my OK.

Set up Crossmint with the Crossmint MCP server (https://mcp.crossmint.com/mcp).
If it is not connected, show me how to connect it
(https://docs.crossmint.com/mcp-server/connect.md) and wait. Then:
- Switch to production with env_select, and create a project with
  projects_create.
- Register my auth provider in the project with projects_auth_provider_set:
  the provider, its ID or issuer, and the user ID claim. If this tool is not
  available, tell me how to register it in the Crossmint Console under
  3P Auth providers, and wait.
- Create a server key with the scopes agent-checkouts.create,
  agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel.
- Create a web client key for my app's origins with the scope
  protected-inputs.create. With Agent Cards, also add the scopes
  payment-methods.create, payment-methods.read, payment-methods.update,
  payment-methods.delete, order-intents.create, order-intents.read, and
  order-intents.revoke.
- Write both keys to my .env file at once: the production server key secret
  appears only in the keys_create response.

Build these parts:
1. A server function that starts a checkout with the server key and the
   x-crossmint-user-id header: the user ID claim of my user's JWT. Set the
   task, maxCost, and the buyer details that I already have, as in
   configure.md.
2. A view that follows the checkout, as in follow-run.md, and shows its
   questions. Answer each question with an input_response for its
   requestId, as in buyer-inputs.md. Collect passwords and other protected
   fields with CrossmintProtectedInput.
3. The payment step, as we agreed:
   - With Agent Cards: save the card with CrossmintPaymentMethodManagement
     from @crossmint/client-sdk-react-ui, at the time that I chose, and
     register it for order intents (register-card.md). Create
     order intents in my frontend with the client key and the user's JWT:
     ahead of time as a general limit, or for the exact amount and merchant
     of the payment request. Reuse an approved order intent when it covers
     the payment. Render OrderIntentVerification when its card rail is
     pending_verification. Send the orderIntentId as the payment answer.
   - For a payment request with method "klarna", show its authorizationUrl
     to the user and send no answer.
   - For other methods, follow payments.md.
4. A result view for succeeded, blocked, failed, and cancelled, as in
   statuses.md.

Launching in Production

You already use production keys. Before you serve users:

Stream the checkout’s messages instead of reading the checkout every 2 seconds. See Stream Updates.
Collect passwords and codes with CrossmintProtectedInput. See Answer Questions.
Handle every final status and code. See Statuses, Results, and Errors.
Save the user’s name and shipping address in a buyer profile, so that the checkout asks less. See Configure a Checkout.

If the response to a create request is lost, read List Checkouts before you create another checkout.

Learn More

How Agent Checkouts Works

The parts, the questions, and the statuses

Test Agent Checkouts

Test at low cost, and clean up after

Pay for a Checkout

Pay with an order intent, Shop Pay, or another method

Common Questions

Merchants, cost, and what happens after a purchase

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Agent Checkouts Quickstart ⚡

Try it out

Call the API

Add it to your app

Call the API

Prerequisites

Add It to Your App

Launching in Production

Learn More

How Agent Checkouts Works

Test Agent Checkouts

Pay for a Checkout

Common Questions

Try it out

Call the API

Add it to your app

​Call the API

​Prerequisites

​Add It to Your App

​Launching in Production

​Learn More

How Agent Checkouts Works

Test Agent Checkouts

Pay for a Checkout

Common Questions

Call the API

Prerequisites

Add It to Your App

Launching in Production

Learn More