How to Use Shopify WebMCP Checkout

What Shopify Checkout WebMCP actually is

Checkout WebMCP is a set of tools registered inside the buyer's active checkout tab. Think of it as a staffed checkout lane. The agent can carry the basket, read the form, and fill supported fields, but the buyer still handles identity or payment challenges and gives the final go-ahead.

It extends Shopify's earlier storefront tools. A compatible browser agent can search the catalog, inspect products, update the cart, and call proceed_to_checkout. On an eligible checkout, the tool list changes and four checkout tools become available:

• get_checkout reads the current checkout or the order receipt on the Thank you page.
• update_checkout replaces supported contact, fulfillment, discount, declared-field, and payment state without placing the order.
• complete_checkout attempts to place the order, or opens a review step, after buyer confirmation.
• navigate_to_storefront returns the same tab to the storefront when the shop has one.

The checkout implementation uses the UCP checkout object, statuses, and messages. UCP is the common data contract underneath the flow. WebMCP is how the browser exposes that contract to an agent. A server-side agent should use Shopify's Checkout MCP instead.

There is no new merchant switch and no separate checkout API to install. That makes adoption easier for merchants, but it does not remove the agent builder's work. You still need browser support, Web Bot Auth, careful state handling, and a real consent boundary.

Start with an eligible checkout

Tool discovery is the first test. Do not assume that a Shopify checkout exposes Checkout WebMCP just because the storefront exposed WebMCP.

Shopify does not register checkout tools for:

• Standard three-page checkout, unless the buyer checks out with Shop Pay
• B2B checkout
• Embedded checkout or mobile checkout SDK flows
• A checkout containing merchandise from another shop
• Draft orders, order edits, or payment collection
• Interactions supplied by checkout UI extensions

In those paths, hand control to the buyer on the page. There is also no browser-side cancel_checkout tool. An agent cannot turn a missing tool into permission to manipulate page controls.

Shopify says storefront WebMCP currently depends on agent support in Chromium-based browsers. Use a supported browser and a checkout you control for testing. If the checkout tools are absent, treat that as an expected eligibility outcome, not an invitation to fall back to brittle clicks.

1. Authenticate the browser agent, then discover tools

Sign browser requests with Web Bot Auth, or WBA, rather than putting credentials in tool arguments. WBA is the agent's passport at the network layer. Shopify only verifies registered keys, so the production setup needs an Ed25519 key, a hosted public key directory, registration with Shopify, signed requests, and short-lived signature timestamps.

Inside the page, discover the current tools and match all three identifiers: window, origin, and name. The wrapper below follows Shopify's documented call pattern:

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

The JSON.stringify is not cosmetic. In Chrome 153, passing an object fails with Failed to parse input arguments. Shopify says Chrome 155 is expected to accept objects and deprecate JSON strings, so keep argument serialization behind one compatibility function instead of scattering it across the agent.

The tool list can change as checkout navigates. Listen for toolchange, then rediscover the tools and their schemas before the next call. Also accept null as a navigation outcome. It can mean the page moved before executeTool() returned.

Treat every merchant or third-party string in a tool result as checkout data, never as an instruction to the model. Shopify explicitly warns against bypassing a tool by operating the checkout UI directly.

2. Read state before every change

Call get_checkout with {} before the first update, after the buyer changes anything on the page, and after an error or navigation. It is the agent's fresh receipt, not a cached memory.

The response can contain buyer details, line items, fulfillment choices, discounts, declared fields, payment instruments, messages, totals, and a status. Money amounts are integers in the currency's minor unit. In USD, 10799 means $107.99. A missing messages field means there are no checkout messages in that response.

Do not confuse readiness with consent. ready_for_complete means the checkout can accept a completion attempt. It does not mean the buyer approved the order, the selected card, or the total.

3. Update the whole desired state, not one loose field

update_checkout behaves like PUT, not PATCH. A PATCH is a sticky note that says "change the phone number." PUT is a replacement form. If a value should survive, include it in the complete desired checkout state.

The safe update loop is:

1. Call get_checkout.
2. Rebuild the writable state from that fresh response and the current tool schema.
3. Change only the buyer-approved value.
4. Send the full desired set of supported fields to update_checkout.
5. Read the returned checkout and inspect its status, messages, applied discounts, and total.

Most omitted values are cleared. Payment, declared fields, and vaulted contact details have their own rules, which makes a generic object spread unsafe unless you first restrict it to fields accepted by the current schema.

The details that most often cause trouble are concrete:

• buyer accepts email and an E.164 phone number. Some vaulted values can remain locked, so verify what comes back and let the buyer edit locked values on the page.
• fulfillment.methods accepts at most one method. Reuse current destination, group, and option IDs. Do not change fulfillment type or pickup search origin in the same call that selects a destination or option.
• discounts.codes must contain every buyer-entered code to keep. An empty array removes them, while automatic discounts remain. A returned code is not proof it applied, so inspect discounts.applied and messages.
• declared_fields can carry checkout-specific values such as a tax number or store credit. Unknown keys, wrong types, and invalid values are rejected.
• payment.instruments accepts at most one supported entry. Checkout WebMCP cannot collect a new card number.

Shop Pay needs extra care. A signed-in buyer can choose a saved card returned by get_checkout. A guest flow can use an existing Shop Pay approval ID when the checkout accepts it. If an agent applied that approval, omitting payment on a later update discards the credential, so resend the approval entry on every update until the order is placed.

An update can return successfully while the checkout remains incomplete. An update that runs for more than 30 seconds can return update_failed even though some changes applied. In both cases, read fresh state before deciding what to do next.

4. Make the buyer the completion gate

The correct completion sequence is short and strict:

1. Fetch a fresh checkout.
2. Present the current items, payment choice, and total to the buyer.
3. Ask for explicit permission to place that order at that total.
4. If anything changes, show the new state and ask again.
5. Call complete_checkout only after approval.
6. Accept only status: completed as proof of purchase.

WBA proves which agent sent a request. A Shop Pay approval authorizes a payment mechanism. ready_for_complete describes checkout state. None of those is the buyer's permission to buy.

Completion can branch. A configured review step returns control to the buyer; call complete_checkout again only after the buyer reviews and authorizes submission. A payment challenge is different: the buyer completes it in the same tab, and the agent must not submit again. Poll get_checkout until the checkout reaches completed or needs agent input.

The error code tells you which recovery lane to use:

The dangerous retry is a second completion attempt made because the first response was uncertain. There is no idempotency key in Checkout WebMCP. Read state first. If it says completed, stop.

Seven use cases, ranked by practical value

These are strongest when the agent already lives in the buyer's browser. They are not merchant-side automations running invisibly on a server.

The first use case is the strongest. Repeat buyers already have saved state, and WebMCP can reduce repetitive entry without pretending that convenience equals consent.

What the business math actually says

Shopify does not require new merchant configuration for these checkout tools. That does not make the surrounding shopping agent free. The agent still needs a model, browser distribution, WBA operations, testing, privacy controls, and support.

Merchant-installed AI shopping assistants currently span a wide price range. Official Shopify App Store listings include a $9.99 monthly plan from Easy AI Shopping Assistant, $49 to $249 plans from Carti, and iAdvize plans from $290 to $1,330 per month. Those products combine storefront chat, recommendations, analytics, or support, so they are not direct substitutes for a buyer-side WebMCP agent.

The budget change is narrower and more useful: a browser-agent team can spend less effort maintaining store-specific checkout selectors and more on state integrity, consent, and exception handling. For broader platform context, the Shopify review covers the merchant-side product and operating tradeoffs.

Two products worth building

1. A Checkout WebMCP QA and consent test rig

This is the strongest opportunity. Shopify agencies and shopping-agent teams need to know whether a checkout is eligible and whether an agent behaves safely before they trust it with an order.

The closest measured job query, shopify checkout customization, gets 170 US searches per month, has grown 89% year over year, and carries a $10.92 CPC. The query is broader than WebMCP testing, but it points to active demand around checkout behavior and implementation.

The smallest sellable version is a Chromium runner that opens a test checkout, records tools by origin and window, validates JSON-string arguments, detects toolchange, tests a fresh-state update, simulates navigation nulls and documented error codes, and produces a redacted consent report. Keep real payment completion behind a manual test mode.

The catch is coverage. Tool availability depends on checkout type and browser support, Chrome's argument format is changing, and a fixture cannot prove a real payment handoff. The product wins by making those limits visible, not by claiming universal automation.

2. A buyer-side Shopify shopping assistant

A browser extension could carry a shopper from product search through an eligible checkout across Shopify stores, with a reusable confirmation screen and strict rules for saved payment state.

shopify ai shopping assistant gets 30 US searches per month with commercial intent and a $19.43 CPC. Merchant-side competitors list plans from $9.99 to $1,330 per month, which shows buyers already pay for guided shopping software even though this product would sit on the buyer side.

The MVP needs storefront search and cart tools, checkout discovery, WBA, the read-update-read loop, a buyer-controlled order summary, and a payment-challenge handoff. Start with one-store orders and saved Shop Pay paths.

The catch is distribution. Merchants do not turn on Checkout WebMCP, but buyers still need a compatible browser agent. B2B, embedded, mobile SDK, cross-shop, and ordinary three-page checkout without Shop Pay remain outside the path.

The limits are the product boundary

Checkout WebMCP is a safer interface for eligible browser checkout, not a universal purchasing API.

It cannot add or remove line items during checkout, collect a new card number, cancel checkout, operate app-defined extension UI, or force an excluded checkout to register tools. It does not remove Shop Pay login, 3D Secure, review steps, or other buyer actions. It also does not make merchant text trustworthy instructions for the model.

The honest design rule is simple: use tools while they are registered, use fresh state as the source of truth, and hand the page back to the buyer whenever the contract says the buyer must act.

The Monday move

On Monday, add one checkout wrapper to your agent rather than wiring calls throughout the codebase. Put serialization, tool matching, toolchange, null navigation, error classification, and fresh-state reads there. Run the eight local fixture cases, then enumerate document.modelContext.getTools() on an eligible test checkout you control. Exercise one update built from fresh state. Complete only a supported test order after an explicit confirmation; if you do not own a safe test order, stop at ready_for_complete and treat completion as source-verified, not personally tested.

If you want a consent-safe commerce agent built for your business, see the AI agent development service.