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 during checkout.

Prerequisites

• A working checkout integration
• 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.

Configure the Run

1. 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.

   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 when requested. Keep raw card details and protected values out of the task.

2. 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.

   // 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: "[e-mail]" },
           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.

3. Choose the browser country

   Add browser.location to request where the managed browser’s network traffic appears to originate:

   {
       "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.

4. 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.

5. Create the configured run

   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 location; see Reuse 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.

Next Steps

Follow a Run

Observe progress and handle requests after starting the checkout

Create a Checkout

Review the complete create request schema