Provide Purchase Context

Give the agent the buyer’s identity, shipping, and intent so it can check out without stopping to ask.

By default, an Agent Checkout stops and asks about every decision the merchant’s checkout involves — the buyer’s name and shipping address, any merchant-specific prompt (buying flowers? it will ask what note to put on the card), and payment. Each one comes back to you as a user action to answer mid-run.

You can pre-answer most of them by writing the context up front — a reusable buyer profile and a per-checkout buyer request — and the agent uses what you provide instead of asking. The one thing you can’t pre-supply is card details: the agent always collects those through a user action, though you can still choose the payment method in the request (see Choose a Payment Method).

Buyer profiles

A buyer profile is a reusable, saved set of the buyer’s name, contact, and shipping address. It holds no payment data — payment is always handled per checkout (see Choose a Payment Method).

Save a profile once, then attach it to any checkout with buyerProfileId. The agent prefills identity and shipping fields from it instead of asking every time — ideal when the same user checks out repeatedly.

// Create once
const { id: buyerProfileId } = await (
    await fetch(`${BASE_URL}/buyer-profiles`, {
        method: "POST",
        headers,
        body: JSON.stringify({
            label: "Home",
            name: { first: "Ada", last: "Lovelace" },
            contact: { email: "[e-mail]" },
            shipping: {
                addressLines: ["1 Market St"],
                locality: "San Francisco",
                administrativeAreaCode: "US-CA", // ISO 3166-2, country-prefixed
                postalCode: "94105",
                countryCode: "US", // ISO 3166-1 alpha-2
            },
        }),
    })
).json();

// Reuse on every checkout
await fetch(BASE_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({ target: { kind: "direct_url", url }, buyerProfileId, constraints }),
});

Profiles are managed through the buyer-profile endpoints (create, list, get, update, delete) and need the agent-checkouts.buyer-profiles.* scopes on your key. See the API Reference for the full schema.

The buyer request

The buyer request (target.request) is a per-checkout, natural-language instruction describing what to buy and how. It’s where you steer this specific purchase: variant, size, quantity, delivery option, billing preference, and which payment method to use.

The more you specify, the fewer pending actions the agent raises. Say nothing and it will stop to ask about each decision; a fully specified request can run start to finish:

target: {
    kind: "direct_url",
    url: "https://merchant.example/products/classic-tee",
    request: "buy size M in black, cheapest delivery, billing same as shipping",
}

You can name the payment method here, but not the card details. Say which method to use (e.g. “pay by card”) in the request; the agent still collects the actual card details through a payment user action during the run. Read Choose a Payment Method for how that works.

Profile vs. request. The buyer profile is reusable identity and shipping that rarely changes. The request is the per-purchase intent and preferences. Use a profile so you don’t re-enter the buyer’s details, and the request to describe each order.

Next

Choose a Payment Method

How the agent pays — supported methods, and how to pass a card safely.