Configure a Checkout

Configure a checkout before it starts. Tell it what to buy, and give it the details that you already have, so that it asks your user less. The checkout asks for missing details during the purchase. See Answer Questions.

Prerequisites

Checkout integration — complete the quickstart.
Server key — a production key with agent-checkouts.create. Add agent-checkouts.buyer-profiles.create to create a buyer profile.
One user ID — use the same x-crossmint-user-id for the checkout, its profiles, and the user’s order intents.

The examples use a server key. To call the API from the browser, see Stream Updates.

Configure the Checkout

Define the purchase and spending cap

A checkout needs request.startUrl and constraints.maxCost. Add request.task when the URL does not fully describe the purchase.

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

const checkout = {
    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" },
    },
};

Use a product URL when it identifies the item. A merchant home page, category, search, or cart URL also works when the task describes what to find. Include quantity, variants, delivery preferences, and billing preferences in the task.maxCost limits what the agent may spend. A checkout that would exceed it ends as blocked with result.code: "policy.max_cost_exceeded".Name the payment method in the task, then pay when the checkout asks. Keep card details and passwords out of the task.

Supply reusable buyer details

A buyer profile stores name, contact, and shipping details. Create it once and attach its ID to later checkouts for the same buyer. It does not contain payment credentials.

// Uses BASE_URL and headers from the previous step.
const profileResponse = await fetch(`${BASE_URL}/buyer-profiles`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        label: "Home",
        name: { first: "Ada", last: "Lovelace" },
        contact: { email: "ada@example.com" },
        shipping: {
            addressLines: ["1 Market St"],
            locality: "San Francisco",
            administrativeAreaCode: "US-CA",
            postalCode: "94105",
            countryCode: "US",
        },
    }),
});
if (!profileResponse.ok) {
    throw new Error(`Could not create buyer profile: ${profileResponse.status}`);
}
const { id: buyerProfileId } = await profileResponse.json();

Use the profile for reusable identity and address data, and the task for this purchase’s preferences. The agent can still request details the profile does not supply, such as a gift message or a merchant-specific question.Buyer-profile create, list, read, update, and delete operations have separate agent-checkouts.buyer-profiles.* scopes. See Create Buyer Profile for the complete schema.

Choose the browser country

Merchants see the country that a visitor connects from. Some merchants show different products, prices, or currencies in each country. Some merchants block visitors from other countries.By default, the checkout browser connects from the United States. To connect from a different country, add browser.location with a two-letter country code (ISO 3166-1 alpha-2), such as CA for Canada. Crossmint then connects the browser through a proxy in that country:

{
    "browser": {
        "location": { "type": "country", "countryCode": "CA" }
    }
}

With browser.location set to CA, the checkout browser connects from Canada, and the merchant shows prices in CAD and products for Canada. The shipping address and the language do not change.

This setting changes only the country that the merchant sees. It does not change the shipping address, the language, or who can buy.Crossmint cannot connect from every country, and there is no fixed list. If the country is not available, the checkout ends as failed with the reason browser_location_unsupported. Crossmint does not use a different country instead. Try again later, choose a different country, or start the checkout without browser.location.

Add merchant guidance when needed

merchantGuidance supplies short operational notes about a merchant’s checkout. Use it for repeatable problems you have observed, rather than ordinary checkout instructions.

Observed problem	Useful guidance
A fit-finder modal derails size selection	Close the fit finder and use the product page’s size dropdown.
The agent misses the guest path	Guest checkout is the Continue without an account link below the sign-in form.
The checkout button stays disabled briefly	Wait for the cart drawer to finish loading before pressing Checkout.

Guidance applies to the merchant of startUrl, for this checkout only. It cannot expand the task, authorize consent, or raise the spending cap. The agent uses the actual page when it contradicts the guidance.Supplying guidance replaces any guidance Crossmint maintains for that merchant. Omit it for standard checkouts; an empty string is rejected. The limit is 20,000 characters, but keep notes short and concrete.

Create the configured checkout

Combine the options you need in one create request:

// Uses checkout, buyerProfileId, BASE_URL, and headers from the earlier steps.
const response = await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
        ...checkout,
        buyerProfileId,
        browser: { location: { type: "country", countryCode: "CA" } },
        merchantGuidance: "Close the fit finder and use the product page's size dropdown.",
    }),
});
if (!response.ok) {
    throw new Error(`Could not start checkout: ${response.status}`);
}
const { runId } = await response.json();

To reuse a merchant session, also set browser.profileId. It is independent of the location. See Sign In to Stores.Compare the checkout’s result and browser behavior with earlier attempts when evaluating guidance. Update or remove notes when the merchant changes its layout.

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Prerequisites

Configure the Checkout

Next Steps

Answer Questions

Create a Checkout

​Prerequisites

​Configure the Checkout

​Next Steps

Answer Questions

Create a Checkout

Prerequisites

Configure the Checkout

Next Steps