How can a Token-tier UCP client obtain permission to call complete_checkout?

Agentic Commerce
1

Hi Shopify team,

We’re building Gratos, a buyer-authorized gifting platform, and have implemented Shopify’s agentic commerce flow across Catalog MCP, Cart MCP, and Checkout MCP.

We currently have:

  • Shopify Global API credentials
  • Token-tier authentication
  • A publicly hosted UCP agent profile
  • Working catalog search and cart creation
  • Working create_checkout and update_checkout calls
  • Checkout sessions that reach a state where they appear ready for completion

However, when attempting API-side checkout completion, we receive:

checkout_completion_ineligible
This checkout is ineligible for completion via API.

The documentation says that the API token must be granted permission to complete purchases, but we have not found a public application process or documentation describing how that permission is obtained.

Could someone clarify:

  1. How does a Token-tier platform apply for access to complete_checkout?
  2. Is the permission applied to the Global API client, the merchant, the payment handler, or a specific checkout?
  3. Is there a sandbox or test merchant where approved platforms can validate end-to-end completion?
  4. Does direct checkout completion currently require Shop Pay delegated payments?
  5. Can approved third-party network-token providers be used with the dev.shopify.card handler?
  6. Is there a separate process for obtaining Order MCP access and order webhooks?

Our initial use case is buyer-present and deterministic:

  • The buyer reviews the merchant, exact products, recipient, shipping method, and final total.
  • The buyer explicitly confirms the purchase.
  • Payment authorization is restricted to the approved checkout and amount.
  • The original Shopify merchant remains the merchant of record.
  • We do not store raw card numbers.
  • We support continue_url escalation when buyer interaction or 3DS is required.

We can provide our Partner organization ID, Global API client ID, agent profile URL, test-store details, request logs, and architecture privately.

Any guidance on the correct approval or integration-review path would be appreciated.

Thanks and Best,

Gratos Team

2

Hey @Peter_Amadon :waving_hand:

Token-tier authentication itself doesn’t grant access to complete_checkout. Under Shopify’s general-access flow, most agents complete via continue_url; direct completion is only available when an agent is eligible and Shopify has granted the client permission. There isn’t currently a public self-service application for this access at the moment unfortunately

Has Shopify onboarded your organization for native checkout completion, or do you have a Shopify partner contact sponsoring the integration? If so, if you can share some more info I can definitely look into this.

Happy to set up a DM with you if you’d prefer - just let me know and I can get that set up on my end. Hope to hear from you soon!

3

Jumping in because we’re in exactly the same position, and I can add one data point that might be useful.

We run a shopping app where a buyer holds one cart across several independent Shopify merchants, with checkout split per seller against each merchant’s own UCP endpoint. On buyer-linked tokens (Sign in with Shop, then the RFC 8693 exchange and RFC 7523 redemption from the buyer-linked tokens guide) we’re granted openid, email, name, phone and dev.ucp.shopping.catalog.search:read, and create_checkout, update_checkout and get_checkout all work authenticated. Today we complete via the continue_url handoff, which works fine and stays our fallback.

The extra data point: the gate is visible at the authorization server, not only at complete_checkout. Requesting dev.ucp.shopping.checkout:manage at accounts.shop.app/oauth/authorize comes back error=access_denied for our client_id, while a made-up scope comes back invalid_scope. So the scope exists and is switched on per client. It’s also listed in scopes_supported in the server’s OAuth metadata, but it doesn’t appear in any Dev Dashboard scope picker. Verified today.

Our completion path is already built and deployed behind a check on the granted scopes: we only ever echo back a Shop Pay instrument the merchant itself offered on the checkout, per the Shop Pay handler spec, so we never see or hold payment credentials. If the grant ever lands it switches on with no code change.

@Alan_G could you share what eligibility involves for this flow, and would you be open to a DM with us as well? Happy to share our client_id, agent profile and company details privately.

4

Hey @Alan_G, thanks for the quick answer.

To your questions: no, Shopify hasn’t onboarded us for native completion, and we don’t have a partner contact sponsoring us. We came in through the self-serve Catalog path so we don’t have an assigned partner manager. On the payments side we work with PayOS, so our agent transacts with network tokenized credentials (DPAN plus a per-transaction cryptogram) rather than raw cards. That’s the context behind question 5 in my original post.

A DM would be great. I can share our Partner org ID, Global API client ID, test store details, and request logs there. Two things I’d want to walk through:

  1. What eligibility and onboarding look like for direct completion for a platform without an assigned partner manager.
  2. Whether dev.shopify.card can accept an externally minted network token as a tokenized_card credential at complete_checkout, and what an eligible agent should declare in its profile’s payment_handlers. Ours is live at app.gratos.ai/.well-known/ucp/agent.json with that block intentionally empty to match the general access examples. Happy to fill it to spec once we know what belongs there.

Appreciate you looking into it.

5

Hey folks — thanks for the additional context. I’ve reached out internally to confirm whether there’s an appropriate intake path for native checkout completion and third-party payment credentials.

I don’t have an approval path or timeline to share yet, but I’ll update the thread if I receive guidance.

7

@Alan_G 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

Today we are completing Shopify orders using the browser agentic path and that is working fine. If there is a UCP path available, we would like to graduate to that. Please keep us in the loop on the agent onboarding process for agents that are already processing Shopify orders.

Here is a reproduction on a live production merchant, in case it helps.

Full chain, all HTTP 200:

create_cart (no auth) → cart created, 30 day TTL
create_checkout (Bearer, token tier) → status: incomplete
update_checkout (+ shipping addr) → status: ready_for_complete
$12.99 + $5.99 ship + $1.56 tax = $20.54
complete_checkout (tokenized card, UUID idempotency key)
→ status: requires_escalation

The response came back as a JSON-RPC result, not an error, with result.isError
true:

{
“type”: “error”,
“content_type”: “plain”,
“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”
}

order was null and payment.instruments came back empty. The instrument was
discarded before any payment attempt. No charge.

Our token is token tier, from Dev Dashboard credentials in the Catalog section,
and decodes to:

scopes: read_global_api_catalog_search write_global_api_app_events
limits: {“catalog”: {“max”: 5, “period”: 1}}

The merchant was advertising dev.shopify.card (visa, master, amex, discover,
diners) and dev.shopify.shop_pay under ucp.payment_handlers at the time.

That points to two independent gates. One is the token permission described in
the traffic tier docs. The other is a merchant level eligibility flag, and it
fires first. If that is right, getting the token permission on its own would not
be enough, because the merchant would still need to be eligible.

  1. Did the internal check on an intake path turn up anything?
  2. Is checkout_completion_ineligible merchant side, agent side, or both?
  3. If merchant side, can a merchant enable it themselves or does that need
    Shopify too?
  4. Is eligibility supposed to be checked before the token permission, or is that
    ordering incidental?

Happy to DM as well.

Regards,

Manil Uppal

8

@Alan_G — adding our data point to this thread, since it’s a step earlier in the chain than what’s been reported so far.

We’re STAASH, a multi-brand shopping app in India (similar setup to what Charles_Marsh described above — one buyer cart spanning several independent Shopify merchants, checkout split per seller against each merchant’s own UCP endpoint).

Unlike Manil’s case, we haven’t been able to meaningfully test complete_checkout at all yet — our blocker is earlier. Two of our connected merchants’ payment_handlers (Purecloth.co, IndyVarna) only list dev.shopify.card and com.google.pay. Neither Razorpay nor Cashfree — their actual configured gateways — shows up. We’re reaching out to both directly about publishing UCP handlers, but wanted to flag here too: even once a regional handler exists, it sounds like the token-permission and merchant-eligibility gates Manil hit would still apply on top.

A few questions, building on what’s already been asked above:

  1. Did the internal check on an intake path (your Aug 12 update) turn up anything since?
  2. On the merchant-eligibility flag Manil found — can a merchant enable that themselves, or does it require Shopify?
  3. Separately: does Shopify play any role in encouraging regional PSPs (Razorpay, Cashfree, etc.) to build UCP handlers, given your existing partner relationships with them — or is that purely on us to drive?

Happy to share more detail or DM if useful.

9

Hey folks - thanks for the patience here, and for the detailed data points. Here’s where things landed on our end:

Is there an intake path? Unfortunately, not at the moment. Direct complete_checkout is a granted on a case by case basis and there isn’t a public application or waitlist for self-serve platforms at the moment. Token-tier credentials from the Dev Dashboard don’t include the checkout-completion permission, and it’s not something you can add from the scope picker - which lines up with what @Charles_Marsh saw at the authorization server. If that changes, though, this would be mentioned in our changelogs.

Two gates - @Manil_Uppal your read is right. Completion requires both (1) the checkout permission on your client’s token, and (2) the merchant having your agent’s channel enabled on their shop. Both are evaluated together at complete_checkout, so you’ll see the same checkout_completion_ineligible if either is missing - the ordering isn’t something to lean on. To @Girish_Aduvalli’s question: the merchant side isn’t a toggle a merchant can flip for an arbitrary agent. It’s tied to the agent being onboarded for native checkout, so a regional payment handler existing wouldn’t be enough on its own.

One thing worth calling out: ready_for_complete describes the checkout’s data state (address, shipping, totals resolved), not your client’s entitlement to complete it, so I wouldn’t treat this as a green light for API completion.

Reading the codes: checkout_completion_ineligible = your client isn’t eligible for API completion (expected for general access). redirect_to_checkout_required = the checkout itself needs the buyer in the merchant’s UI (3DS, extension interaction, etc.). Anything else is usually a real input or payment issue worth debugging.

What you can do today: continue_url is the supported path for general access, and everyone here already has it as a fallback, so this is what I’d reccommend. If you want a more native handoff, take a look at Checkout Kit for embedding the merchant’s checkout instead of a full redirect.

Payment handlers (@Girish_Aduvalli): For Shopify merchants, Shopify advertises the UCP payment handlers on the merchant’s behalf - it’s not something an individual merchant publishes. Regional gateways like Razorpay and Cashfree aren’t UCP handlers today. I don’t have a roadmap to share on that, but I’ll pass the feedback along.

Network tokens via dev.shopify.card (@Peter_Amadon): still confirming this one - I’d rather get you a correct answer than a fast one, so I’ll loop back once I have it.

Order MCP / webhooks: webhook subscription isn’t self-serve either right now - the docs call this out under Monitor orders.

I know this isn’t the answer folks were hoping for, and I definitely get that the auth docs say “when your token has been granted permission” without saying how - I’ve flagged that gap on our end. Let me know if I can clarify anything on our end here and I hope this helps a little bit at least :slight_smile:

10

@Peter_Amadon - just looping back here, I was able to confirm this one. dev.shopify.card only accepts a Shopify-issued card token - there’s no way to submit an externally minted network token (DPAN + per-transaction cryptogram) through that handler today, and I’m not aware of anything planned there. If your goal is to avoid handling raw card data, Shop Pay (dev.shopify.shop_pay) is the documented
delegated-payment path - it’s the same approach Charles described above. To your other question: leaving payment_handlers empty in your agent profile is fine and matches the general access examples. It doesn’t affect completion eligibility either way, so there’s nothing to fill in there to unlock anything. Hope this helps as well.