Order Post-Processing Events in the UCP Order Lifecycle

An agentic-commerce channel is an AI assistant such as Google Gemini that transacts through the Universal Commerce Protocol (UCP). When a shopper places an order through that channel, the agent platform keeps its own current-state copy of the order, which it can surface to the shopper. To keep that copy accurate after checkout, B2C Commerce must tell the agent platform whenever the order changes.

Most changes happen after the purchase, in your Order Management System (OMS): the order is shipped, delivered, cancelled, or returned. This guide explains how those order post-processing events drive UCP order-lifecycle updates—how a shipment, cancellation, or return becomes a fresh, full-order snapshot—carrying a cryptographic signature—delivered to the agent platform so the shopper always sees an up-to-date order.

How those events reach B2C Commerce depends on which OMS manages the order. There are two models:

• Salesforce Order Management (Salesforce OMS)—updates are detected and forwarded automatically. You do nothing beyond your normal order operations.
• A third-party OMS—your OMS posts each event to a dedicated B2C Commerce API.

Whichever model you use, the outcome is identical: a full-order snapshot carrying a cryptographic signature, delivered asynchronously to the agent platform.

UCP requires each update to be a complete, current-state snapshot of the order—not an incremental delta. So for every post-processing event, B2C Commerce re-fetches the whole order, attaches the new entry, and sends the entire order to the agent platform.

Two kinds of entry can be attached, and the agent surface renders them differently:

Both are append-only logs: each event adds an entry; earlier entries are never removed. The fulfillment object is always present on every snapshot.

When your UCP orders are managed in Salesforce OMS, there is nothing to build or configure for these updates. As you ship, cancel, and process returns in Salesforce OMS, B2C Commerce detects each change and forwards it to the agent platform automatically.

The event kind and sign (+/−) are derived from the order-management operation:

Notes on behavior:

• The initiator doesn’t matter. A cancellation or return may be initiated by the shopper (self-service through the storefront or the agent platform), a service rep, or your operations team. In every case the resulting Salesforce OMS state change is what drives the UCP update—it is detected and forwarded automatically.
• The platform fills in the details. Timestamps come straight from the Order Management event, and cancellations and returns are reported as settled (completed) money movements—you don’t author any of this.
• Each action produces its own update. When an order ships, you get a shipment update; when it is canceled or returned, you get an adjustment update. So a shipment and a cancellation on the same order arrive as two updates. But when several line items change together in one action—for example, a fulfillment that ships multiple items at once—that is a single update for the order, not one per line item. An order shipped in several parts produces one shipment update per part; because every update carries the full order, the fulfillment events accumulate in the log.

A fulfillment ships two of the order’s lines together. Even though multiple items ship, this is one action, so it produces a single UCP update—one shipped event listing all the shipped line items:

1{
2  "fulfillment": {
3    "events": [
4      {
5        "type": "shipped",
6        "occurred_at": "2026-01-15T10:30:00Z",
7        "line_items": [
8          { "id": "10uVF0000002fn4YAA", "quantity": 1 },
9          { "id": "10uVF0000002fn5ZBB", "quantity": 2 }
10        ]
11      }
12    ]
13  }
14}

This shipment ships three units across two lines but arrives as one webhook—not three, and not one per line.

Two lines are returned together—one unit at $30.00 and two units at $20.00 each—for a $70.00 refund. As with the shipment, this is one action, so it produces a single UCP update—one return adjustment listing all the returned lines:

1{
2  "id": "adj_return_10uVF0000002fn4YAA",
3  "type": "return",
4  "occurred_at": "2026-01-15T10:30:00Z",
5  "status": "completed",
6  "line_items": [
7    { "id": "10uVF0000002fn4YAA", "quantity": -1 },
8    { "id": "10uVF0000002fn5ZBB", "quantity": -2 }
9  ],
10  "totals": [
11    { "type": "total", "amount": -7000 }
12  ]
13}

Note the negative amount (-7000, that is, −$70.00 in cents) and negative quantities—money and units flowing back to the shopper. Both returned lines arrive as one webhook, not one per line. A cancellation looks the same with "type": "cancellation".

When your UCP orders are managed by a third-party OMS, B2C Commerce can’t observe your OMS’s internal changes. Instead, your OMS calls a dedicated API to notify B2C Commerce of each post-processing event. B2C Commerce then reassembles the current order (through your OMS retrieval integration), attaches the event you posted, and delivers the snapshot—carrying a cryptographic signature—to the agent platform.

Unlike the Salesforce OMS model—where B2C Commerce derives the event—your OMS supplies the fully-formed event: its type, timestamp, affected line items, tracking, totals, and signs (+/−).

The API, its authorization, request schema, response codes, and sample request bodies are documented in Connect a Third-Party Order Management System (OMS), under Push Status Updates to the Platform, with the endpoint reference at createOmsStatusEvent. That guide is the authoritative reference for the endpoint; this page doesn’t repeat it.

The essentials, for orientation:

• You POST exactly one fulfillmentEvent or adjustment per call to oms-status-events.
• A fulfillmentEvent becomes an entry in fulfillment.events[]; an adjustment becomes an entry in adjustments[].
• You author the whole event—its type, timestamp, affected line items, tracking, totals, and signs (+/−). Follow the sign (+/−) convention: quantities and amounts flowing back to the buyer are negative; fulfillment quantities are non-negative. This is the one place the platform can’t derive intent for you, so the correctness of the UCP snapshot depends on the values you send.
• The endpoint is available only when your third-party OMS integration is active for the site (feature enabled and all order hooks registered); otherwise it returns 409 Conflict.

What is specific to this topic—and not covered by the OMS connection guide—is what B2C Commerce does with the event after it accepts it:

1. It reassembles the current order by calling your OMS retrieve hook (the same hook used for order look-ups), so the snapshot reflects your OMS’s live state.
2. It appends the event you posted—the fulfillmentEvent to fulfillment.events[], the adjustment to adjustments[]. Entries your retrieval hook already returns are preserved.
3. It applies the cryptographic signature and delivers the full-order snapshot to the agent platform—the same signature-protected payload the Salesforce OMS model produces.

Because the reassembly runs through your retrieval hook, the snapshot is only as current as what that hook returns; the posted event is layered on top of it.

Every update is one delivery containing the full order, with:

• the always-present fulfillment object (including any events[] such as shipped), and
• the adjustments[] log (any cancellations, returns, or refunds to date).

Delivery is:

• Signature-protected—each webhook carries a cryptographic signature (HTTP Message Signatures, RFC 9421) so the agent platform can verify it came from B2C Commerce. Saving UCP settings in Business Manager generates the signing keys advertised on the business profile.
• Asynchronous—sending happens off to the side and never blocks or slows your order operations.

To mutate the payload immediately before signed delivery, implement sfcc.ucp.orderWebhook.v1.modifyEventPayload. If that hook fails or returns a non-OK status, the webhook is retried. See Business Profile and Order Webhooks.

• Configuration and Discovery—Business Manager UCP settings, OMS options, and signing keys
• Implementation Considerations—order webhook hook, including modifyEventPayload
• Connect a Third-Party Order Management System (OMS)—building and registering the order hooks the third-party model depends on, and the oms-status-events API
• UCP order specification

j

Announcements

Choose Your B2C Commerce Storefront Type

Universal Commerce Protocol (UCP) Integration

Configuration and Discovery

Checkout Session Authentication

Technical Audit

Implementation Considerations

Transaction Management

Enabling Google as a Platform

Order Post-Processing Events

B2C Commerce

SCAPI

Agentforce Commerce Vibes

Storefront Next

Composable Storefront

Storefront Reference Architecture (SFRA)

Agentforce Commerce Client

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community