About orders
After checkout completes, your agent can monitor the order's lifecycle: fulfillment events, returns, refunds, exchanges, and order edits.
Shopify's order capability (dev.ucp.shopping.order) implements the UCP order specification and exposes two surfaces:
- Order MCP: The
get_ordertool fetches the current state of an order on demand. Use it for buyer-initiated views, reconciling dropped webhook deliveries, or any case where you need fresh state right now. - Order webhooks: Shopify pushes the full current order state to your endpoint whenever a committed change occurs. Use webhooks as the primary signal for proactive notifications and timeline UIs.
Tool use is subject to access and rate limiting that scale with how your agent identifies itself. See Auth and rate limiting for traffic tiers and what each can do.
Tool use is subject to access and rate limiting that scale with how your agent identifies itself. See Auth and rate limiting for traffic tiers and what each can do.
Anchor to How it worksHow it works
Your agent originates a checkout using Checkout MCP or Embedded Checkout Protocol. After the checkout is complete, your agent can:
- Receive order webhooks at your registered endpoint as the order moves through fulfillment and post-purchase changes.
- Call
get_orderat any time to fetch the current state of an order by ID.
Anchor to PayloadPayload
Order MCP and order webhooks serialize the same fields in the same shape. The response from get_order matches the payload Shopify pushes to your webhook URL.
For the field-level reference and an example payload, see the Order data model on the Order MCP page.
Anchor to Capability negotiationCapability negotiation
The order capability is automatically advertised on every shop's /.well-known/ucp document. There's no shop-level flag or gating to enable it.
If your agent's profile declares dev.ucp.shopping.order, the capability is negotiated automatically.
Anchor to Order accessOrder access
Your agent can fetch only orders that were facilitated through it. Orders placed through other channels or experiences are not accessible using this capability.
Anchor to UCP versionsUCP versions
Two UCP versions are currently live: 2026-01-23 and 2026-04-08. This documentation describes 2026-04-08. Agents on the older version see the previous adjustment type names (order_cancel instead of cancellation, fulfillment_created instead of shipped/ready). When you bump your agent's UCP version, swap those terms in your event handlers.
Anchor to When to use which surfaceWhen to use which surface
Pick the surface that matches how the update is triggered. Use webhooks when Shopify pushes a change to react to, and get_order when your agent needs to read the current state on demand.
| Use case | Recommended approach |
|---|---|
| Proactive buyer notifications (shipping updates, refund confirmations) | Webhooks |
| Buyer-initiated "Where's my order?" views | get_order |
| Reconciling missed webhook deliveries | get_order |
| Building a timeline of post-purchase changes | Webhooks |
Webhooks are the primary update channel. Use get_order for reconciliation and on-demand reads. Don't reconstruct order state by replaying webhook history. Each delivery contains the full current state of the order.
Webhooks are the primary update channel. Use get_order for reconciliation and on-demand reads. Don't reconstruct order state by replaying webhook history. Each delivery contains the full current state of the order.
Anchor to Order MCPOrder MCP
Order MCP implements the UCP order capability over JSON-RPC. The capability exposes a single tool for retrieving an order on demand. Requests require a Global API JWT with the read_global_api_orders scope.
| Tool | Description |
|---|---|
get_order | Fetch the current state of an order by ID. |
Anchor to Order webhooksOrder webhooks
Order webhooks deliver the full current order state to your registered endpoint whenever a committed change occurs. Every delivery has the same UCP-shaped payload, so route all order webhooks through the same handler and inspect the data to determine what changed. Don't branch on the topic name.
For reference, deliveries fire on three underlying topics:
| Topic | When it fires |
|---|---|
orders/create | A new order is placed through your agent. |
orders/updated | The order changes (payment captured, fulfillment progresses, an adjustment commits, or other internal updates). |
orders/delete | An order is deleted. The payload still contains the order's last-known state. |
Delivery URL and topic are configured by Shopify. To subscribe or update an existing subscription, contact your Shopify partner manager.
Delivery URL and topic are configured by Shopify. To subscribe or update an existing subscription, contact your Shopify partner manager.
