Set the Browser Location

Agent Checkouts manages the browser and its network configuration for you. When a merchant changes prices, inventory, payment methods, or access based on location, you can request the country where the checkout browser should appear to be located.

Request a Country

Set browser.location when you create the checkout:

const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};

const response = await fetch("https://www.crossmint.com/api/unstable/agent-checkouts", {
    method: "POST",
    headers,
    body: JSON.stringify({
        request: {
            startUrl: "https://merchant.example/products/classic-tee",
            task: "Buy one in black, size medium",
        },
        browser: {
            location: {
                type: "country",
                countryCode: "CA",
            },
        },
        constraints: {
            maxCost: { amount: "100.00", currency: "USD" },
        },
    }),
});

const { runId } = await response.json();

countryCode uses the same ISO 3166-1 alpha-2 format as buyer profiles, such as US, GB, or CA. Crossmint trims the value and converts it to uppercase. When the checkout uses a managed browser, omitting browser.location uses US browser egress by default.

The browser location controls network egress only. It does not set or verify the buyer’s residence, shipping address, language, or eligibility to purchase an item.

Combine Location with a Browser Profile

browser.location and browser.profileId are independent options. Include both when a checkout should use a saved merchant session from a particular country:

browser: {
    profileId: "7c3b1f2a-9d54-4e80-b1a6-2f0c8e5d4a31",
    location: {
        type: "country",
        countryCode: "GB",
    },
}

The location applies to this checkout run. The profile continues to hold the user’s saved merchant sessions for reuse on later runs.

Handle Availability

Country routing is best effort because it depends on third-party network availability and IP geolocation. Crossmint chooses the underlying network configuration; your integration does not select or manage proxy providers or proxy types. There is no fixed public list of supported countries. Availability can change over time. Crossmint does not knowingly route the checkout through a different country when the requested country is unavailable. Instead, the run ends with:

{
    "status": "failed",
    "reason": "browser_location_unsupported"
}

When this happens, tell the user that checkout is not currently available from the requested country. You can retry later, choose another country, or start a new run without browser.location to use the US default. If the run already used the default, retry later.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Request a Country

Combine Location with a Browser Profile

Handle Availability

Next Steps

Provide Purchase Context

Buy from Authenticated Stores

​Request a Country

​Combine Location with a Browser Profile

​Handle Availability

​Next Steps

Provide Purchase Context

Buy from Authenticated Stores

Request a Country

Combine Location with a Browser Profile

Handle Availability

Next Steps