Buy Several Items in One Order

One checkout can buy several products from one merchant. List every item in the task. The checkout builds one cart, and your user approves one payment for the total.

Prerequisites

Agent Checkouts integration — complete the quickstart.
Server key — a production key with agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel.

Buy the Items

List every item in the task

Give the quantity and the options of each item. When an item is not available, the checkout asks the user whether to replace it, skip it, or cancel. To decide in advance, say it in the task. Set maxCost for the total of the order, with shipping and tax.

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",
            "task": "Buy these items in one order: 2 black Classic Tees in size M, 1 grey hoodie in size L, and 1 canvas tote bag. If an item is sold out, skip it and buy the rest. Use standard shipping and pay by card."
        },
        "constraints": { "maxCost": { "amount": "150.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",
            task: "Buy these items in one order: 2 black Classic Tees in size M, 1 grey hoodie in size L, and 1 canvas tote bag. If an item is sold out, skip it and buy the rest. Use standard shipping and pay by card.",
        },
        constraints: { maxCost: { amount: "150.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",
            "task": (
                "Buy these items in one order: 2 black Classic Tees in size M, "
                "1 grey hoodie in size L, and 1 canvas tote bag. "
                "If an item is sold out, skip it and buy the rest. "
                "Use standard shipping and pay by card."
            ),
        },
        "constraints": {"maxCost": {"amount": "150.00", "currency": "USD"}},
    },
)
response.raise_for_status()
run_id = response.json()["runId"]

Start at the merchant’s home page when the items are on different product pages. Start at the cart page to buy what is already in the user’s cart. See Manage a Store Cart.

Answer the questions

The checkout can ask about each item, for example a size that the task did not give. See Answer Questions.

Approve one payment

The payment request gives the total of the order. Create one order intent for that total, and send its ID. See Pay for a Checkout.

Common Gotchas

The items come from different merchants

One checkout buys from one merchant. Start one checkout for each merchant.

The total is more than the spending cap

The checkout ends as blocked with policy.max_cost_exceeded. result.summary gives the total. Ask the user for a higher limit, then start a new checkout.

Next Steps

Manage a Store Cart

Build the cart first, and buy later

Pay for a Checkout

Answer the payment request with an order intent

Create a Checkout

Review the complete create request schema

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Buy Several Items in One Order

Prerequisites

Buy the Items

Common Gotchas

Next Steps

Manage a Store Cart

Pay for a Checkout

Create a Checkout

​Prerequisites

​Buy the Items

​Common Gotchas

​Next Steps

Manage a Store Cart

Pay for a Checkout

Create a Checkout

Prerequisites

Buy the Items

Common Gotchas

Next Steps