Agent Surface

Agentic Commerce

Orders and After Purchase

Order status, cancellations, returns, and refunds as agent-callable operations after checkout completes

Last verified 2026-10-29

Summary

A successful payment is not the end of the task an agent was given - it needs to check the order actually shipped, cancel or change it if the buyer's plans changed, and handle a return or refund if the product was wrong. Most of the mechanics here are not commerce-specific: they are the same , , and error-handling patterns used everywhere else in Agent Surface, applied to order state. This page is the commerce-specific index into that existing guidance rather than a restatement of it.

  • Order status, cancellation, and returns/refunds need to be callable operations, not just an emailed confirmation
  • Order webhooks are the push side; a get_order-style call is the pull side - provide both where the platform allows (Shop launched without webhooks, so poll get_checkout)
  • Idempotent order creation prevents a retried checkout request from creating two orders
  • A payment succeeding and an order fulfilling are different facts - don't conflate them in the response an agent sees

Order status and cancellation as callable operations

An agent that completed a purchase, or is checking on one made earlier, needs a stable way to ask "what is the status of this order" and get back a machine-parseable answer - not a link to a human-facing order-history page. Expose this as an operation or MCP tool (Shopify's Order MCP get_order tool is one concrete example, and Shop MCP's signed-in search_orders finds a shopper's orders and tracking - see Shopify) that returns the order's current lifecycle state, not just whether payment succeeded.

Cancellation follows the same rule: extend machine-readable reasoning to post-purchase cancellation rather than switching to a support-ticket flow the moment payment has cleared. Keep it distinct from cancelling an unpaid checkout session, which a checkout protocol handles itself ('s /cancel accepts an optional structured intent_trace - see Checkout Protocols); that is not a post-purchase cancellation contract, so define your own reason vocabulary for orders.

On Shopify, since 2026-10-01 the 2026-10 Admin API orderCancel mutation returns a structured, cancellation-specific jobResult (status, errors, affected order) for its asynchronous job, and new buyer-requested order-edit APIs are available. Next Gen Events, the declarative replacement for classic webhooks, is generally available.

Order webhooks

Push order-lifecycle events - order.created, order.status_changed, order.shipped, order.cancelled, order.refunded, and the equivalent payment events - rather than requiring an agent to poll, and keep a pull call alongside them. Where a platform exposes no webhooks, polling is the only option: Shop MCP, launched 2026-10-13, has none, so an agent polls get_checkout for status. Webhooks and Events for Agents covers the full design: document webhooks in the webhooks field, give every event a discriminating event_type and unique event_id, include a full state snapshot rather than only a diff, and sign deliveries per the Standard Webhooks spec (webhook-id/webhook-timestamp/webhook-signature) so a receiver can verify a delivery without inventing bespoke verification. Everything in that page applies directly to order and payment events - this page does not repeat it.

Idempotent order creation

A network failure between an agent submitting a checkout and receiving a response is exactly the case idempotency keys exist for: the agent cannot tell whether the order was created before the connection dropped, and retrying without protection risks a duplicate charge and a duplicate order. Require an Idempotency-Key on order-creating and order-mutating requests, and return the original response - not a new order - when the same key arrives twice. Idempotency and Replay Protection covers how this composes with request-replay protection at the authentication layer; the full key-generation, storage, and TTL mechanics live on Idempotency. Both checkout-session creation (see the ACP flow on Checkout Protocols) and any order-mutation endpoint you expose directly need this.

Receipts and distinguishing payment from fulfilment

A successful payment is not necessarily successful fulfilment - a charge can clear while the item is out of stock, or a receipt can generate before a warehouse confirms the order. Return distinct, explicit states for "payment authorized," "payment captured," "order confirmed," and "order fulfilled" rather than collapsing them into one "success" response, and make sure whichever checkout protocol or webhook stream you use actually carries a receipt (an identifier, the charged amount, and a timestamp) an agent can hold and reconcile against later - Evaluating Product Journeys treats a receipt as proof of the payment stage only; the end-of-test check is the fulfilled order.

Returns and refunds

Treat a return or refund request the same way as a purchase: it needs a callable operation with a defined contract (what the buyer needs to supply, what state the order must be in, what the response looks like), structured errors when it's not possible (return window expired, item not eligible, already refunded - see RFC 9457 Problem Details), and a webhook or pollable status once initiated. Publish the return policy itself as structured data too - hasMerchantReturnPolicy on the product's Offer, covered in Product Data - so an agent can check eligibility before it asks, not only after a refund is rejected.

On this page

SummaryOrder status and cancellation as callable operationsOrder webhooksIdempotent order creationReceipts and distinguishing payment from fulfilmentReturns and refundsRelated Pages