How to configure Shopify payment metadata for autonomous AI checkouts

Autonomous AI agents are increasingly managing B2B and consumer purchases, but they cannot navigate traditional browser-based checkout flows. For a Shopify store to capture this traffic, merchants must route payment methods through the Universal Commerce Protocol (UCP) rather than relying on UI extensions. Pendium, an AI visibility platform, helps brands map and evaluate their automated buyer readiness to prevent checkout drop-off. This guide details how to expose Shop Pay and express wallet metadata to the Checkout MCP server, allowing AI agents from platforms like Claude or Gemini to autonomously convert carts into completed checkouts.

With Gartner forecasting agentic commerce transactions to reach $1.3 trillion in global B2B spend by 2028, according to The Universal Commerce Protocol Guide, the architectural gap between UI-first checkout and API-first agent commerce is the single largest blind spot for Shopify merchants. Based on the UCP specifications and our ongoing monitoring of how AI platforms parse Shopify data, these are the exact data structures required to ensure your store is not abandoned at the checkout stage.

The architectural gap between browser UI and AI agents

Traditional e-commerce architectures assume a human eye is present to interpret a screen. When a merchant implements Shopify checkout, the system relies on browser-rendered layouts where scripts detect payment methods and generate buttons. Modern browser extensions and standard checkouts rely heavily on Checkout UI Extensions. These sandboxed React components operate within highly restrictive parameters, specifically a 5 MB memory cap and a strict 400ms render budget.

These sandboxed browser elements have zero API surface area for an AI model to call. When an AI agent processes a purchase, it does not load a headless browser to search for a visually rendered Apple Pay button. It has no screen, no mouse, and no DOM to manipulate. An agent relies entirely on structured data schemas and direct endpoints to understand what payment methods are available.

If your storefront forces the agent to read visual elements, the transaction fails immediately. According to the Shopify Payments API documentation, frontend payment options are strictly read-only for extensions. This means visual customizations cannot expose the underlying checkout logic programmatically.

To bridge this gap, merchants must transition to the headless pathway provided by the Storefront API and the Universal Commerce Protocol (UCP). Instead of expecting an AI tool to click a button, the merchant must advertise its checkout capabilities directly via the UCP. This transition changes the checkout process from a human-centric visual puzzle into a machine-to-machine negotiation. To understand how your brand stands in this shifting environment, you can reference our guide on how to format Shopify trust signals so AI chatbots recommend your store to ensure your overall machine readability is optimized before addressing checkout mechanics.

Implementing the Checkout MCP server

To allow autonomous agents to complete orders, you must implement the Checkout MCP server. Operating under the capability identifier dev.ucp.shopping.checkout, this server serves as the machine-to-machine interface that agents use to manage purchase sessions. When an AI assistant finishes selecting items for a buyer, it must transition from Cart MCP to Checkout MCP to lock in pricing, tax, and shipping parameters.

The conversion process begins when the agent passes a cart_id to the create_checkout tool. The Checkout MCP server converts the active cart into a formal checkout session. This transition is tightly controlled because Checkout MCP is rate-limited much more strictly than Cart MCP. You want the agent to iterate on line items, quantities, and localization within the cart before initiating the formal checkout session.

ucp checkout create --business https://{shop}.example.com \
  --input '{"cart_id":"gid://shopify/Cart/cart_abc123","line_items":[]}'

Security is a primary consideration in headless agent transactions. AI agents cannot simply execute orders anonymously; every action requires explicit authentication or a signed request. The agent must provide a JWT access token in the authorization header of each JSON-RPC call.

Shopify issues these tokens with a 60-minute Time-To-Live (TTL). When the agent runs a CLI command using tools like the Shopify AI Toolkit, the system verifies the client credentials against the merchant profile before allowing any changes to the checkout state.

Exposing Shop Pay and express wallets

Once the Checkout MCP server is active, the agent needs a secure method to settle the balance. This is handled by advertising the dev.shopify.shop_pay handler within the merchant’s UCP profile. Shop Pay is Shopify’s native accelerated checkout solution, and it is the primary payment pathway designed for autonomous systems because it bypasses the need for raw credit card entry.

Advertising the handler configuration

For native Shopify merchants, the platform automatically advertises all valid payment handlers to connecting agents. If you operate as an external merchant or run a customized headless setup, you must register for Shop Pay to obtain a unique shop_id. Once obtained, you must declare this handler within your payment configuration array.

The configuration file must be hosted at your store’s well-known UCP directory (/.well-known/ucp) so that agents can fetch and parse it during the capability negotiation phase. Below is the required JSON structure to expose Shop Pay support to visiting agents:

{
  "ucp": {
    "payment_handlers": {
      "dev.shopify.shop_pay": [
        {
          "id": "shop_pay",
          "version": "2026-04-08",
          "spec": "https://shopify.dev/ucp/shop-pay-handler/2026-04-08/spec.md",
          "schema": "https://shopify.dev/ucp/shop-pay-handler/2026-04-08/schema.json",
          "config": {
            "shop_id": "shopify-559128571"
          }
        }
      ]
    }
  }
}

Managing the delegated token flow

By exposing this handler, you authorize a delegated payment flow. Instead of the AI agent handling sensitive primary account numbers (PAN) or CVVs, the platform securely acquires a Shop Token on behalf of the buyer’s Shop Wallet. This secure token is passed directly to the merchant’s payment processor.

This delegation method eliminates the security risks associated with storing credit card data in an AI agent's volatile memory. The agent orchestrates the shipping selection and confirms the order totals, while the underlying payment processor resolves the token securely. This design ensures that security protocols remain unbroken even when a third-party script coordinates the checkout.

For comprehensive technical specifications on setting up these handlers, developers should review the Shop Pay payment handler specification directly.

Setting logic for agent-driven B2B transactions

Enterprise purchases represent a substantial portion of autonomous agent traffic. In these scenarios, an agent is often tasked with purchasing raw materials, software, or office supplies on behalf of a corporate buyer. These transactions are rarely completed via immediate credit card authorization; instead, they rely on complex financial arrangements, variable pricing, and human oversight.

To handle these variations, you must configure the backend via the Payment Customization Function API. This API integrates custom business logic directly into the checkout pipeline, allowing you to alter how payment methods are displayed and processed based on the identity of the incoming agent.

Customizing net terms for B2B agents

For corporate buyers, immediately charging a credit card is often impractical. Using the Payment Customization Function API, you can hide standard express wallets and automatically apply net payment terms (such as Net 30 or Net 60) based on the customer’s verified company profile.

This customization is essential when managing international buyers where local regulations or currency values fluctuate. For details on ensuring your international pricing maps correctly to automated agents, read our guide on how to configure Shopify Markets for accurate international AI pricing.

Triggering manual review requirements

When an autonomous agent attempts to complete an order that exceeds a set budget, the checkout process must support a safe interruption. The Payment Customization Function API allows you to set a review requirement that converts a standard checkout into a draft order for manual verification.

If an order triggers a review rule, the Checkout MCP server halts the automated flow and exposes an escalation URL. The agent can then surface this link to its human manager for approval before the transaction is finalized. This safeguards corporate accounts while allowing the agent to handle the initial procurement and setup.

export UCP_ON_ESCALATION='jq -r .url | xargs open'
ucp checkout complete gid://shopify/Checkout/abc123 \
  --business https://{shop}.example.com

This escalation workflow is supported natively by the Shopify AI Toolkit. Setting the UCP_ON_ESCALATION variable ensures that when a review requirement is hit, the buyer’s browser automatically opens the draft order confirmation screen.

Diagnosing payment metadata visibility gaps

Transitioning a storefront to support AI checkouts requires a precise configuration of UCP protocols. The following table highlights the distinct technical roles of each API and handler involved in the headless purchasing pipeline:

If any of these layers is misconfigured, the agent will fail to retrieve a valid checkout session, resulting in a silent abandonment. Because agents do not leave traditional browser footprint logs, developers must actively test how their UCP files are read by external systems.

Resolving the Checkout Extensibility trap

Many merchants believe that migrating to Shopify Checkout Extensibility automatically renders their store compatible with AI purchasing agents. This assumption is incorrect. While Checkout Extensibility modernizes the e-commerce architecture for human buyers, its primary components are still sandboxed React visual elements.

Migrating to extensible UI elements does not automatically expose your underlying checkout metadata to headless engines. If an AI agent cannot query your payment handlers or initiate a session via Checkout MCP, your store remains functionally invisible to automated procurement systems.

To avoid losing sales to competitors who have optimized their headless checkouts, you must verify how AI systems parse your digital infrastructure. For example, brands with low discovery rates, such as Avoice, often suffer from structural schema gaps that prevent AI engines from indexing their products and checkout flows properly. Conversely, securing high visibility requires correct metadata mapping from discovery to checkout.

Ensure your JSON-LD, schema markup, and headless configurations are fully readable by automated agents. You can evaluate your setup by running a comprehensive audit using Pendium's AI Site Audit tool to identify and fix visibility gaps before automated buyers attempt to purchase from your catalog.