Reference note
UCP Orders after purchase: state, events, and returns
The UCP Order model after Checkout: current snapshots, webhooks, fulfillment, refunds, returns, adjustments, and attribution.
Published . Part of agentic commerce.
After Checkout completes, UCP represents the order as a complete snapshot of current state. The merchant returns the same structure for synchronous reads and webhook events, so the platform does not have to rebuild state from fragments.
Key takeaways
GET /orders/{id}returns the latest full state.- Fulfillment events form an append-only log.
- Adjustments cover returns, refunds, credits, disputes, and cancellations.
What is the Order resource for?
The Order specification separates the completed transaction from post-purchase tracking. The resource carries line items, fulfillment expectations, events, adjustments, and optionally a snapshot of the originating Checkout attribution.
Every response must include the full entity. This simplifies recovery after a missed
event: a new read restores current state. The permalink_url remains authoritative for
the complete merchant-hosted order experience and complex post-purchase actions.
How is an order retrieved securely?
The standard read operation is GET /orders/{id}. The merchant must authenticate access
before returning data. UCP allows mechanisms including OAuth 2.0, mTLS, API keys, and
HTTP Message Signatures.
Two known scopes govern user access:
dev.ucp.shopping.order:readfor orders owned by the authenticated user;dev.ucp.shopping.order:managefor cancellations, returns, and other changes.
Knowing the identifier alone must never authorize access.
Fulfillment expectations and events
Expectations describe what the merchant plans: window, destination, method, or quantity. Fulfillment events record what happened. They reference line items and may include carrier tracking.
The specification favors an append-only event log. Common types include processing,
shipped, in_transit, delivered, and returned_to_sender, but the field remains
open. Platforms must display an unknown type safely instead of dropping it.
How are returns and refunds represented?
Adjustments are independent from fulfillment and may occur before, during, or after
delivery. The type is open; common values include refund, return, credit,
price_adjustment, dispute, and cancellation.
Quantities and amounts are signed. A reduction is negative and an addition positive. An adjustment can target line items or the whole order, such as a shipping refund.
An append-only ledger remains preferable. A merchant without adjustment history may update an entry in place, but loses evidence that can matter during an agentic payment dispute.
Why do webhooks contain the full state?
The merchant pushes lifecycle changes to a platform-provided URL. The payload is the same complete entity returned by Get Order. This symmetry reduces code branches and makes idempotent consumption easier.
Order webhooks must be signed. Without a signature, recipients cannot authenticate a server-initiated event. A platform should verify the signature, deduplicate delivery, and replace its local snapshot with the latest valid state.
Post-purchase checklist
- Protect every order through owner-bound authorization.
- Return the complete entity for reads and webhooks.
- Keep fulfillment events ordered and append-only.
- Use signed amounts for adjustments.
- Sign all webhooks and deduplicate their processing.
- Keep
permalink_urlas the human fallback.
This post-purchase layer completes the path described on the agentic commerce overview.