> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Checkout

> Set the purchase task, buyer details, browser country, and merchant guidance

Configure a run before it starts so the agent knows what to buy and can reuse information you already have. Missing details can become [buyer input requests](/agents/checkouts/buyer-inputs) during checkout.

## Prerequisites

* A [working checkout integration](/agents/agent-checkouts-quickstart)
* A production API key with `agent-checkouts.create`; add `agent-checkouts.buyer-profiles.create` when creating a buyer profile
* A stable buyer identity shared by the run and any profiles or payment authorization

The examples use a server-side key. For client-side authentication, see [Follow a Run](/agents/checkouts/follow-run#authenticate-each-request).

## Configure the Run

<Steps>
  <Step title="Define the purchase and spending cap">
    A run needs `request.startUrl` and `constraints.maxCost`. Add `request.task` when the URL does not fully describe the purchase.

    ```typescript theme={null}
    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 [authorize payment](/agents/checkouts/payments) when requested. Keep raw card details and protected values out of the task.
  </Step>

  <Step title="Supply reusable buyer details">
    A buyer profile stores name, contact, and shipping details. Create it once and attach its ID to later runs for the same buyer. It does not contain payment credentials.

    ```typescript theme={null}
    // 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](/api-reference/agent-checkouts/create-buyer-profile) for the complete schema.
  </Step>

  <Step title="Choose the browser country">
    Add `browser.location` to request where the managed browser's network traffic appears to originate:

    ```json theme={null}
    {
        "browser": {
            "location": { "type": "country", "countryCode": "CA" }
        }
    }
    ```

    This is an optional fragment of the create body. `countryCode` uses ISO 3166-1 alpha-2 codes, such as `US`, `GB`, and `CA`; Crossmint trims and uppercases it. Managed browsers use US egress when you omit the location.

    Location affects network egress. It does not set or verify residence, shipping address, language, or purchase eligibility.

    Routing is best effort, and there is no fixed public list of supported countries. If the requested location is unavailable, the run ends as `failed` with `reason: "browser_location_unsupported"` instead of knowingly using another country. Retry later, choose another country, or start a new run without `browser.location` to use the US default.
  </Step>

  <Step title="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 run 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.
  </Step>

  <Step title="Create the configured run">
    Combine the options you need in one create request:

    ```typescript theme={null}
    // 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 location; see [Reuse Merchant Sessions](/agents/checkouts/merchant-sessions).

    Compare the run's result and browser behavior with earlier attempts when evaluating guidance. Update or remove notes when the merchant changes its layout.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Follow a Run" icon="arrows-rotate" href="/agents/checkouts/follow-run">
    Observe progress and handle requests after starting the checkout
  </Card>

  <Card title="Create a Checkout" icon="brackets-curly" href="/api-reference/agent-checkouts/create-agent-checkout">
    Review the complete create request schema
  </Card>
</CardGroup>