Manage a Store Cart

An agent checkout can change a user’s cart at a merchant without buying. Your agent can add items over several days, tell the user what is in the cart, and check out when the user is ready.

The API has no cart endpoint. You write the cart change in the task, and a browser profile keeps the cart at the merchant for the next checkout.

Prerequisites

Agent Checkouts integration — complete the quickstart.
Browser profile — create one for the user. See Sign In to Stores. Many merchants keep the cart only for a signed-in user.
Server key — a production key with agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel.

Change the Cart

Start a checkout that only changes the cart

Write the change in the task, and tell the checkout not to pay. Start at the product page to add an item. Start at the merchant’s cart page to remove items, to empty the cart, or to list it.

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/wool-socks",
            "task": "Add one pair of wool socks in grey, size L, to the cart. Only change the cart. Do not check out and do not pay. When you are done, list what is in the cart, with the prices and the cart total."
        },
        "browser": { "profileId": "YOUR_BROWSER_PROFILE_ID" },
        "constraints": { "maxCost": { "amount": "100.00", "currency": "USD" } }
    }'

const response = await fetch("https://www.crossmint.com/api/unstable/agent-checkouts", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": process.env.CROSSMINT_SERVER_API_KEY!,
        "x-crossmint-user-id": "YOUR_USER_ID",
    },
    body: JSON.stringify({
        request: {
            startUrl: "https://shop.example.com/products/wool-socks",
            task: "Add one pair of wool socks in grey, size L, to the cart. Only change the cart. Do not check out and do not pay. When you are done, list what is in the cart, with the prices and the cart total.",
        },
        browser: { profileId: "YOUR_BROWSER_PROFILE_ID" },
        constraints: { maxCost: { amount: "100.00", currency: "USD" } },
    }),
});
if (!response.ok) {
    throw new Error(`Could not start checkout: ${response.status}`);
}
const { runId } = await response.json();

import os

import requests

response = requests.post(
    "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",
    },
    json={
        "request": {
            "startUrl": "https://shop.example.com/products/wool-socks",
            "task": (
                "Add one pair of wool socks in grey, size L, to the cart. "
                "Only change the cart. Do not check out and do not pay. "
                "When you are done, list what is in the cart, "
                "with the prices and the cart total."
            ),
        },
        "browser": {"profileId": "YOUR_BROWSER_PROFILE_ID"},
        "constraints": {"maxCost": {"amount": "100.00", "currency": "USD"}},
    },
)
response.raise_for_status()
run_id = response.json()["runId"]

constraints.maxCost is required. Set it to a value that is higher than the cart total.

Answer questions and stop any payment request

Follow the checkout and answer its questions, such as a size or a sign-in. See Answer Questions.If a payment request arrives, do not answer it. Cancel the checkout with POST /api/unstable/agent-checkouts/{runId}/cancel.

Show the cart to the user

When the checkout ends, read result.summary. It lists the items in the cart, with the prices and the total. Show it to your user.

Check Out Later

When the user is ready to buy, start a normal checkout with the same browser.profileId. Start at the merchant’s cart page, with a task such as “Check out the items in the cart. Use standard shipping.” Then answer the payment request with an order intent. See Pay for a Checkout.

Common Gotchas

The cart is empty on the next checkout

The checkout ran without a browser profile, or the merchant keeps the cart only for a signed-in user. Attach the same browser.profileId to each checkout, and sign in once. Some merchants also clear a cart after some time.

Each cart change is a checkout

Crossmint bills each checkout that starts. Group several changes in one task when you can, for example “Add the socks and remove the hat”.

Next Steps

Buy Several Items in One Order

Buy a full cart with one payment

Buy When the Price Drops

Check out later, when the price is right

Create a Checkout

Review the complete create request schema

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Prerequisites

Change the Cart

Check Out Later

Common Gotchas

Next Steps

Buy Several Items in One Order

Buy When the Price Drops

Create a Checkout

​Prerequisites

​Change the Cart

​Check Out Later

​Common Gotchas

​Next Steps

Buy Several Items in One Order

Buy When the Price Drops

Create a Checkout

Prerequisites

Change the Cart

Check Out Later

Common Gotchas

Next Steps