Improve Merchant Success Rate

The agent works through ordinary checkout behavior on its own: finding the cart or a pay button, choosing guest checkout, filling address and payment forms, dismissing cookie banners, and reading totals. It does not need to be told that a billing portal says “Make a payment” instead of “Add to cart”. merchantGuidance is for what the agent cannot learn from the page in front of it: things you know about this merchant from running checkouts there before. A control that is hidden until the page settles, a modal that leads nowhere, a required step that looks optional, or the one of two similar paths that actually works. It is free text that the agent reads as operational advice about the site.

Prerequisites

A working checkout integration. Follow the quickstart first. Guidance refines a merchant that mostly works; it does not replace the task or the buyer profile.
Evidence of a repeatable problem. Read the result.summary and blocked code of past runs at the merchant, or watch the live browser session, and identify the step the agent gets wrong.

What Guidance Can and Cannot Do

Guidance is scoped and subordinate by design:

It applies to the merchant of request.startUrl, for this run only. It does not follow the agent to another merchant.
It sits below the task, the buyer’s answers, and the spending cap. It cannot authorize a substitution, a higher quantity, another seller, any consent, or spending above maxCost.
It is advice, not a script. If the page contradicts it, the agent follows the page. Guidance written for an old layout degrades gracefully instead of breaking the run.
If you omit it, the checkout uses any guidance Crossmint already maintains for that merchant. Supplying it replaces that guidance in full for the run.

When to Use It

Write guidance when the agent repeatedly stumbles on the same merchant-specific detail:

Symptom you observe	Guidance that fixes it
The agent opens the cart before the checkout button is usable	”The checkout button in the cart drawer stays disabled until the drawer finishes loading. Wait for it.”
A recommendation or fit-finder modal derails size selection	”Close the fit finder modal and use the size dropdown on the product page.”
The agent signs in when a guest path exists	”Guest checkout is the ‘Continue without an account’ link below the sign-in form.”
Delivery choice is made in an unexpected place	”Delivery versus pickup is chosen on the product page, not at checkout. Select delivery before adding to cart.”
Express wallet buttons lead to third-party sign-ins	”Ignore the express checkout buttons. Use the regular ‘Continue to checkout’ button under them.”
A required field is easy to miss	”The phone number field at the bottom of the address form is required even though it is not marked.”

Each line names a concrete control, where it is, and what to do about it.

When Not to Use It

Standard checkouts. If the merchant follows the common patterns, omit merchantGuidance. An empty string is rejected, and extra text costs tokens and adds nothing.
What to buy. Product, variant, quantity, and preferences belong in request.task, not in guidance.
Who is buying. Name, contact, and shipping belong in the buyer profile.
Anything that widens the order. Guidance cannot raise the cap, approve an alternative item, or accept terms on the buyer’s behalf. Those statements are ignored.

How to Use It

Pass merchantGuidance at the top level of the create request, next to request and constraints.

{
    request: {
        startUrl: "https://shop.example/products/trail-runner",
        task: "buy a pair in size 10, black",
    },
    merchantGuidance: [
        "Close the fit finder modal and use the size dropdown on the product page.",
        "The checkout button in the cart drawer stays disabled until the drawer finishes loading. Wait for it.",
    ].join(" "),
    buyerProfileId,
    constraints: { maxCost: { amount: "180.00", currency: "USD" } },
}

The field accepts up to 20,000 characters, but useful guidance is short. Write it the way you would brief a colleague who has done ordinary checkouts before but has never used this site: only the surprises, each as one plain sentence.

Verify

Run the same purchase again with the guidance attached and compare:

The run no longer stops at the step you identified. Check result.summary and the blocked code, if any.
The live browser session shows the agent taking the path you described.
The final total and items are unchanged. Guidance should change the route, never the order.

If the merchant later changes its layout, the agent follows the new page and your guidance becomes inert. Remove or update lines that no longer match.

Next Steps

Provide Purchase Context

Put the buyer’s identity, shipping, and intent where they belong

Buy from Authenticated Stores

Reuse a merchant login when the purchase needs an account

API Reference

The full create request schema

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Improve Merchant Success Rate

Prerequisites

What Guidance Can and Cannot Do

When to Use It

When Not to Use It

How to Use It

Verify

Next Steps

Provide Purchase Context

Buy from Authenticated Stores

API Reference

​Prerequisites

​What Guidance Can and Cannot Do

​When to Use It

​When Not to Use It

​How to Use It

​Verify

​Next Steps

Provide Purchase Context

Buy from Authenticated Stores

API Reference

Prerequisites

What Guidance Can and Cannot Do

When to Use It

When Not to Use It

How to Use It

Verify

Next Steps