Seeking guidance on `complete_checkout` for agentic commerce platform

Agentic Commerce
1

Hello Shopify Team…We are CartAI (cartai.ai), a developer-first API for agentic checkout. Our infrastructure lets any AI agent automate, embed, or enable transactions across merchants.

We have implemented the full UCP flow end-to-end against live Shopify merchants: catalog search, cart creation, and checkout creation all working.

Checkout reaches status: ready_for_complete with payment handlers advertised (dev.shopify.card, com.google.pay), buyer identity, shipping, line items, and totals fully populated.

When we call complete_checkout we consistently get:

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"AuthenticationFailed","data":"Missing required buyer IP header."}}

We’re authenticating at Token tier using credentials from Dev Dashboard (Catalogs section). We’ve tried supplying the buyer IP in every way we can think of — none work:

  • X-Forwarded-For HTTP header
  • X-Real-IP HTTP header
  • meta.buyer_ip field inside the JSON request body

All three return the same Missing required buyer IP header error. The header name does not appear anywhere in the UCP docs or Shopify agent docs.

Questions:

  1. What is the exact header name Shopify expects for the buyer IP on complete_checkout calls?
  2. For an autonomous agent flow (AP2), where the agent acts on behalf of a buyer without a live browser session, how should the buyer IP be supplied?
  3. Are there additional requirements beyond the buyer IP to reach a successful complete_checkout — such as a payment instrument in the request body, or a specific token scope beyond read_global_api_catalog_search?
  4. Is there an early access program or partner track for agentic commerce infrastructure platforms? We’re building toward both autonomous (AP2) and embedded (ECP) checkout flows and want to engage with the right team at Shopify.

For reference, our request:

curl -s -X POST "https://{shop}.myshopify.com/api/ucp/mcp" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "complete_checkout",
      "arguments": {
        "id": "{checkout_id}",
        "meta": {
          "ucp-agent": {"profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"},
          "idempotency-key": "{uuid}",
          "buyer_ip": "{buyer_ip}"
        }
      }
    }
  }'

Any guidance appreciated.

2

Use this in the header

'Shopify-Buyer-IP': buyerIp
3

Update on our end — we’ve made more progress and have a more specific question now.

We resolved the buyer IP issue using Shopify-Buyer-IP (tip from this community) and worked through the full request structure. complete_checkout is now executing and returning a fully populated checkout object — line items, totals, fulfillment, buyer identity all present. The schema is accepted with no validation errors.

The blocker we’re now hitting:

{
  "type": "error",
  "code": "checkout_completion_ineligible",
  "content": "This checkout is ineligible for completion via API. Use the continue_url to complete checkout on the merchant's storefront.",
  "severity": "requires_buyer_review"
}

Status returns as requires_escalation.

We understand from the UCP engineering post that some checkouts complete via API and others require human involvement based on merchant policies or agent capabilities. What we can’t determine is what controls which side of that line a merchant is on.

We checked several merchants’ /.well-known/ucp profiles — the capability declarations look identical between merchants. Nothing in the profile appears to signal whether API completion is permitted.

The specific question: What is the gate that controls checkout_completion_ineligible? Is it a merchant-level setting, a platform trust tier, or something the agent needs to declare in its own UCP profile? And is it discoverable before calling complete_checkout, or is the only signal the escalation response itself?

4

“What is the gate that controls checkout_completion_ineligible? Is it a merchant-level setting, a platform trust tier, or something the agent needs to declare in its own UCP profile? And is it discoverable before calling complete_checkout, or is the only signal the escalation response itself?”

Anyone?