Provide Purchase Context

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 an input request 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 task — and the agent uses what you provide instead of asking. The one thing you cannot pre-supply is card details: the agent always collects those through an input request, though you can still choose the payment method in the task (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: "ada@example.com" },
            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({ request: { startUrl: 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 task

The task (request.task) is a per-checkout, natural-language instruction describing what to buy and how. It is 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 input requests the agent raises. Say nothing and it will stop to ask about each decision; a fully specified task can run start to finish:

request: {
    startUrl: "https://merchant.example/products/classic-tee",
    task: "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 task; the agent still collects the actual card details through a payment input request during the run. Read Choose a Payment Method for how that works.

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

Choose a Payment Method

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

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Buyer profiles

The task

Next

Choose a Payment Method

​Buyer profiles

​The task

​Next

Choose a Payment Method

Buyer profiles

The task

Next