Skip to main content
For a standard store — add to cart, go to cart, proceed to checkout, enter shipping and payment — the agent already knows the pattern and handles it on its own. You don’t need merchantContext there. merchantContext is for the unusual checkouts that don’t follow that pattern: a site with no cart, its own vocabulary, or a path to pay the agent wouldn’t guess. It’s a free-text field where you tell the agent exactly how to get through this site.

​
When to use it

Reach for it when the flow isn’t standard e-commerce — for example:
  • There’s no cart. Paying a medical bill, an invoice, or a utility account has no “add to cart” → “checkout” — the agent has to find a “Pay” or “Make a payment” action instead.
  • The site uses its own vocabulary. The buttons aren’t labeled “Add to cart”, “Checkout”, or “Place order”, so the agent can’t rely on the usual cues.
  • The path to pay is non-obvious. The agent first has to enter an account or invoice number, choose a specific option, or click through a step it wouldn’t guess on its own.

​
How to use it

Pass merchantContext on target. Where request says what to buy or pay, merchantContext says exactly what to click on this site. 
target: {
    kind: "direct_url",
    url: "https://provider.example/patient/billing",
    request: "pay the outstanding balance for account 4839221",
    merchantContext: [
        "This is a medical bill portal — there is no cart or 'add to cart'.",
        "Enter the account number in the 'Account #' field, then click 'Look up balance'.",
        "Click 'Pay now', choose 'Pay full balance', then continue to the payment form.",
    ].join(" "),
}
It’s free text (up to 4,000 characters). Write it the way you’d brief a person doing this checkout for the first time — name the exact buttons and the order of steps. Skip anything the agent already handles, like filling standard forms or a normal cart-to-checkout flow.