This guide provides the technical API reference and payload schemas for pushing
full order status updates, fulfillment events, and adjustments to Google using
webhooks for version `2026-04-08` of the Universal Commerce Protocol
(UCP).

Before building your endpoints, ensure you have reviewed the [Order lifecycle
overview](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle) for the high-level
concepts, mandatory events, and webhook endpoint details.

> [!TIP]
> **Tip:** To ensure reliable webhook delivery and handle latency spikes gracefully, review the [webhook timeout and retry guidance](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle#webhook-latency).

## Auth and request signing

Key changes in version `2026-04-08` include the introduction of new
mandatory webhook headers and specific request signing procedures.

### Required webhook headers

The following HTTP headers are mandatory for all webhook requests:

- `Webhook-Id`: a unique identifier for this specific webhook event. This ID should match the `id` of the primary event being sent (for example, the fulfillment event ID or adjustment event ID).
- `Webhook-Timestamp`: the timestamp indicating when the event occurred.

These headers replace the `id` and `created_time` fields previously expected in
the order payload.

> [!NOTE]
> **Note:** Google uses this header to evaluate order freshness. An order update will be rejected if this timestamp is older than the latest recorded update.

### Request signing

1. Compute SHA-256 digest of the raw request body and set `Content-Digest` header.
2. Select a signing key from `signing_keys` in your UCP profile.
3. Build signature base per [RFC
   9421](https://www.rfc-editor.org/rfc/rfc9421).
   - See the spec for signed components
4. Set `UCP-Agent`, `Signature-Input`, and `Signature` headers.
   - `UCP-Agent` is a link to your UCP profile in the format `profile="https://merchant.example.com/.well-known/ucp"`.
   - `Signature-Input` is a dictionary structured field describing the components contained within the signature, as well as the `keyid` used to sign, which must match the `kid` of your selected signing key from `signing_keys` in your UCP profile.
   - `Signature` header contains your signature base which is signed using your private key and then base64 encoded.

See the [signing instructions on
ucp.dev](https://ucp.dev/draft/specification/order/#signing-business)
for more information.

## Acknowledgment and response

Google acknowledges valid order webhook requests with an `HTTP 200 OK` (or any
`2xx`) status code.

For version `2026-04-08`, the expected response body is either empty `{}`
or includes the protocol version:

    {
      "ucp": {
        "version": "2026-04-08"
      }
    }

For detailed guidance on error handling and retry strategies for non-2xx codes,
see [Acknowledgment and response](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle#acknowledgment-and-response)
in the Order lifecycle overview.

## Order created event

- **Trigger:** immediately after the order is confirmed (`status:
  processing`).

**Key changes in this version:**

- The `currency` field is now required at the top level of the Order object.
- The `type` field within each object in the `totals` array is now an open string (for example, "subtotal", "tax", "fee", "total").
- The mandatory `Webhook-Id` header contains a unique identifier for the webhook event. Note that the `id` field in the payload containing the order confirmation ID is still required.
- The mandatory `Webhook-Timestamp` header provides the creation time, replacing the former `created_time` field in the payload.

**Example:** This example shows an order created after a buyer completes the
checkout.

**Required Headers:**

- `Webhook-Id: order_01`
- `Webhook-Timestamp: 2026-03-23T19:00:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_01",
      "checkout_id": "checkout_01",
      "currency": "USD",
       // Always include all line items, even for single-item checkouts. This ensures any add-ons, gifts, or separate charges are accounted for.
      "line_items": [
        {
          "id": "line_1",
          "item":
            {
              "id": "product_123",
              "title": "Running Shoes",
              "price": 10000
            },
          "quantity": { "total": 1, "fulfilled": 0 },
          "totals": [
            {"type": "subtotal", "display_text": null, "amount": 10000},
            {"type": "total", "display_text": null, "amount": 10000}
          ],
          // The status of a line item must match total and fulfilled quantities (e.g., total 1, fulfilled 0 -> status: processing).
          "status": "processing"
        }
      ],
      "totals": [
        {"type": "subtotal", "display_text": "Subtotal", "amount": 10000}, // Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
        {"type": "fee", "display_text": "Service Fee", "amount": 100},
        {"type": "tax", "display_text": "Tax", "amount": 800}, // Tax-inclusive markets: Omit this entry.
        {"type": "total", "display_text": "Total", "amount": 10900}
      ],
      "fulfillment": {
        "expectations": [
          {
            "id": "exp_1",
            "line_items": [{ "id": "line_1", "quantity": 1 }],
            "method_type": "shipping",
            "destination": {
              "first_name": "Alice",
              "last_name": "Example",
              "street_address": "123 Main St",
              "address_locality": "Austin",
              "address_region": "TX",
              "address_country": "US",
              "postal_code": "78701"
            },
            "description": "Arrives in 2-3 business days",  // Maximum length: 200 characters.
            "fulfillable_on": "now"
          }
        ]
      },
      "permalink_url": "https://merchant.example.com/orders/789"
    }

## Fulfillment events

These events are sent as part of the `fulfillment.events` array.

> [!NOTE]
> **Note:** When fulfillment events occur, the `expectations` object must be kept consistent with any updates. For example, if the events indicate that the order comprises two packages, `expectations` should also reflect this. Expectations don't need to be updated for adjustments (for example, cancellations).

### Order shipped

When items in the order have been shipped. The `tracking_number` and
`tracking_url` fields are required for shipped events, as these are required to
group items on the "My orders" page accurately.

### Order delivered

When items in the order have been delivered.

**Example (`shipped` and `delivered`):** This example shows an order update
after the item has been shipped and then delivered.

**Required Headers:**

- `Webhook-Id: fulfill_evt_2`
- `Webhook-Timestamp: 2026-02-10T14:00:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_01",
      "checkout_id": "checkout_01",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_1",
          "item":
            {
              "id": "product_123",
              "title": "Running Shoes",
              "price": 10000
            },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "amount": 10000},
            {"type": "total", "amount": 10000}
          ],
          "status": "fulfilled"
        }
      ],
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "total", "amount": 10000}
      ],
      // Updated fulfillment details
      "fulfillment": {
        "events": [
          {
            "id": "fulfill_evt_1",
            "occurred_at": "2026-02-08T10:30:00Z",
            "type": "shipped",
            "line_items": [{ "id": "line_1", "quantity": 1 }],
            "tracking_number": "123456789",
            "tracking_url": "https://fedex.com/track/123456789",
            "carrier": "FedEx",
            "description": "Shipping departed from warehouse"
          },
          {
            "id": "fulfill_evt_2",
            "occurred_at": "2026-02-10T14:00:00Z",
            "type": "delivered",
            "line_items": [{ "id": "line_1", "quantity": 1 }],
            "tracking_number": "123456789",
            "tracking_url": "https://fedex.com/track/123456789",
            "carrier": "FedEx",
            "description": "Package delivered"
          }
        ],
        "expectations": [{ "...": "..." }]
      },
      "permalink_url": "https://merchant.example.com/orders/123"
    }

## Multi-item order examples

The following examples demonstrate how to structure updates for multi-item
orders and split shipments. For rules on how package statuses are derived, see
[How package status is
determined](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle#package-status).

### Multi-item order, same package delivery

This example shows an order update for a single package containing multiple
items. All line items are grouped within a single `shipped` event sharing the
same tracking number.

**Required Headers:**

- `Webhook-Id: fulfill_evt_1`
- `Webhook-Timestamp: 2026-02-08T10:30:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_multi_01",
      "checkout_id": "checkout_multi_01",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_1",
          "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "display_text": null, "amount": 5000},
            {"type": "total", "display_text": null, "amount": 5000}
          ],
          "status": "fulfilled"
        },
        {
          "id": "line_2",
          "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "display_text": null, "amount": 5000},
            {"type": "total", "display_text": null, "amount": 5000}
          ],
          "status": "fulfilled"
        }
      ],
      "totals": [
        {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
        {"type": "fee", "display_text": "Shipping", "amount": 500},
        {"type": "total", "display_text": "Total", "amount": 10500}
      ],
      "fulfillment": {
        "expectations": [
          {
            "id": "exp_1",
            "line_items": [
              { "id": "line_1", "quantity": 1 },
              { "id": "line_2", "quantity": 1 }
            ],
            "method_type": "shipping",
            "destination": {
              "first_name": "Alice",
              "last_name": "Example",
              "street_address": "123 Main St",
              "address_locality": "Austin",
              "address_region": "TX",
              "address_country": "US",
              "postal_code": "78701"
            },
            "description": "Standard Shipping",
            "fulfillable_on": "now"
          }
        ],
        "events": [
          {
            "id": "fulfill_evt_1",
            "occurred_at": "2026-02-08T10:30:00Z",
            "type": "shipped",
            "line_items": [
              { "id": "line_1", "quantity": 1 },
              { "id": "line_2", "quantity": 1 }
            ],
            "tracking_number": "123456789",
            "tracking_url": "https://fedex.com/track/123456789",
            "carrier": "FedEx",
            "description": "Both items shipped together"
          }
        ]
      },
      "permalink_url": "https://merchant.example.com/orders/456"
    }

### Multi-item order, split shipment

This example shows an order update for split shipments. There are multiple
`shipped` events, each referencing the specific `line_items` within that
respective package, with distinct tracking numbers. Since each package
represents a distinct fulfillment commitment (for example, different speeds and
costs from a multi-group checkout), the `expectations` are also split.

**Required Headers:**

- `Webhook-Id: fulfill_evt_2`
- `Webhook-Timestamp: 2026-02-09T14:00:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_multi_02",
      "checkout_id": "checkout_multi_02",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_1",
          "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "display_text": null, "amount": 5000},
            {"type": "total", "display_text": null, "amount": 5000}
          ],
          "status": "fulfilled"
        },
        {
          "id": "line_2",
          "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "display_text": null, "amount": 5000},
            {"type": "total", "display_text": null, "amount": 5000}
          ],
          "status": "fulfilled"
        }
      ],
      "totals": [
        {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
        {"type": "fee", "display_text": "Shipping", "amount": 1500},
        {"type": "total", "display_text": "Total", "amount": 11500}
      ],
      "fulfillment": {
        "expectations": [
          {
            "id": "exp_1",
            "line_items": [{ "id": "line_1", "quantity": 1 }],
            "method_type": "shipping",
            "destination": {
              "first_name": "Alice",
              "last_name": "Example",
              "street_address": "123 Main St",
              "address_locality": "Austin",
              "address_region": "TX",
              "address_country": "US",
              "postal_code": "78701"
            },
            "description": "Standard Shipping",
            "fulfillable_on": "now"
          },
          {
            "id": "exp_2",
            "line_items": [{ "id": "line_2", "quantity": 1 }],
            "method_type": "shipping",
            "destination": {
              "first_name": "Alice",
              "last_name": "Example",
              "street_address": "123 Main St",
              "address_locality": "Austin",
              "address_region": "TX",
              "address_country": "US",
              "postal_code": "78701"
            },
            "description": "Express Shipping",
            "fulfillable_on": "now"
          }
        ],
        "events": [
          {
            "id": "fulfill_evt_1",
            "occurred_at": "2026-02-08T10:30:00Z",
            "type": "shipped",
            "line_items": [{ "id": "line_1", "quantity": 1 }],
            "tracking_number": "PKG1_TRACKING",
            "tracking_url": "https://fedex.com/track/PKG1_TRACKING",
            "carrier": "FedEx",
            "description": "First item shipped in package 1"
          },
          {
            "id": "fulfill_evt_2",
            "occurred_at": "2026-02-09T14:00:00Z",
            "type": "shipped",
            "line_items": [{ "id": "line_2", "quantity": 1 }],
            "tracking_number": "PKG2_TRACKING",
            "tracking_url": "https://fedex.com/track/PKG2_TRACKING",
            "carrier": "FedEx",
            "description": "Second item shipped in package 2"
          }
        ]
      },
      "permalink_url": "https://merchant.example.com/orders/457"
    }

## Adjustment event examples

The following examples demonstrate how to structure updates for refunds,
returns, and cancellations. For a list of supported events and their
definitions, see [Adjustment
events](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle#adjustment-events) in the
Order lifecycle overview.

### Order cancellation and refund

This example shows an order where the item was canceled and refunded shortly
after the order was placed.

**Key changes in this version in this example:**

- Line items affected by a `cancellation` now use `"status": "removed"` in the main `line_items` array.
- When `line_items.status` is `removed`:
  - The `line_items.quantity.total` is set to `0`.
  - The original quantity is stored in the new `line_items.quantity.original` field.

**Required Headers:**

- `Webhook-Id: adj_refund_1`
- `Webhook-Timestamp: 2026-02-09T11:05:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_02",
      "checkout_id": "checkout_02",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_2",
          "item": {
            "id": "product_456",
            "title": "Smart Watch",
            "price": 29900
          },
          "quantity": {
            "total": 0,  // Item removed from order total.
            "original": 1,  // Original quantity before removal.
            "fulfilled": 0 //  Item was not fulfilled before cancellation.
          },
          "totals": [
            {"type": "subtotal", "amount": 29900},
            {"type": "tax", "amount": 2400},
            {"type": "total", "amount": 32300}
          ],
          "status": "removed" // Item is cancelled, returned, or refunded.
        }
      ],
      "totals": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
        // Fulfillment expectations should still be present even if cancelled early.
      "fulfillment": {
        "expectations": [
          {
            "id": "exp_1",
            "line_items": [{ "id": "line_2", "quantity": 1 }],
            "method_type": "shipping",
            "destination": {
              "first_name": "Bob",
              "last_name": "Consumer",
              "street_address": "456 Oak Ave",
              "address_locality": "Anytown",
              "address_region": "CA",
              "address_country": "US",
              "postal_code": "90210"
            },
            "description": "Standard Shipping",
            "fulfillable_on": "now"
          }
        ]
        // "events": [] // No fulfillment events occurred before cancellation.
        },
      "adjustments": [
        {
          "id": "adj_cancel_1",
          "type": "cancellation",
          "description": "Customer changed mind",
          "line_items": [{ "id": "line_2", "quantity": -1 }],
          "occurred_at": "2026-02-09T11:00:00Z",
          "status": "completed"
        },
        {
          "id": "adj_refund_1",
          "type": "refund",
          "description": "Refund for cancelled item",
          "line_items": [{ "id": "line_2", "quantity": -1 }],
          "totals": [
            {"type": "subtotal", "display_text": "Subtotal", "amount": -29900}, // Negative amounts indicate money returned to the buyer. Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
            {"type": "tax", "amount": -2400}, // Tax-inclusive markets: Omit this entry.
            {"type": "total", "display_text": "Total", "amount": -32300}
          ],
          "occurred_at": "2026-02-09T11:05:00Z",
          "status": "completed"
        }
      ],
      "permalink_url": "https://merchant.example.com/orders/12345"
    }

### Order return and refund

This example shows an order where the item was shipped, delivered, and then
returned and refunded.

**Key changes in this version in this example:**

- Line items affected by a `return` now use `"status": "removed"` in the main `line_items` array.
- When `line_items.status` is `removed`:
  - The `line_items.quantity.total` is set to `0`.
  - The original quantity is stored in the new `line_items.quantity.original` field.
- In `adjustments` of type `return`, the `line_items.quantity` field within the adjustment uses a negative value (for example, `-1`) to indicate items being taken back.

**Required Headers:**

- `Webhook-Id: adj_refund_2`
- `Webhook-Timestamp: 2026-02-10T10:00:00Z`

    {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
        }
      },
      "id": "order_03",
      "checkout_id": "checkout_03",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_3",
          "item": {
            "id": "product_789",
            "title": "Wireless Earbuds",
            "price": 14900
          },
          "quantity": {
            "total": 0,  // Item removed from order total.
            "original": 1,  // Original quantity before removal.
            "fulfilled": 1 // Was fulfilled before return.
          },
          "totals": [
            {"type": "subtotal", "amount": 14900},
            {"type": "tax", "amount": 1200},
            {"type": "total", "amount": 16100}
          ],
          "status": "removed" // Item is cancelled, returned, or refunded.
        }
      ],
      "totals": [
        {"type": "subtotal", "amount": 14900},
        {"type": "tax", "amount": 1200},
        {"type": "total", "amount": 16100}
      ],
      "fulfillment": {
        "events": [
          {
            "id": "fulfill_evt_1",
            "occurred_at": "2026-02-05T09:00:00Z",
            "type": "shipped",
            "line_items": [{ "id": "line_3", "quantity": 1 }],
            "tracking_number": "987654321",
            "tracking_url": "https://fedex.com/track/987654321",
            "carrier": "FedEx",
            "description": "Item shipped"
          },
          {
            "id": "fulfill_evt_2",
            "occurred_at": "2026-02-07T16:00:00Z",
            "type": "delivered",
            "line_items": [{ "id": "line_3", "quantity": 1 }],
            "tracking_number": "987654321",
            "tracking_url": "https://fedex.com/track/987654321",
            "carrier": "FedEx",
            "description": "Item delivered"
          },
          {
            "id": "fulfill_evt_3",
            "occurred_at": "2026-02-09T09:00:00Z",
            "type": "returned",
            "line_items": [{ "id": "line_3", "quantity": 1 }],
            "tracking_number": "987654321",
            "tracking_url": "https://fedex.com/track/987654321",
            "carrier": "FedEx",
            "description": "Item returned"
          }
        ],
        "expectations": [{ "...": "..." }]
      },
      "adjustments": [
        {
          "id": "adj_return_1",
          "type": "return", // a matching fulfillment event is also added to represent return shipping.
          "description": "Item not compatible",
          "line_items": [{ "id": "line_3", "quantity": -1 }],  // Uses a negative value (such as -1) to indicate a return.
          "occurred_at": "2026-02-09T09:00:00Z",
          "status": "completed"
        },
        {
          "id": "adj_refund_2",
          "type": "refund",
          "description": "Refund for returned item",
          "line_items": [{ "id": "line_3", "quantity": -1 }],
          "totals": [
            {"type": "subtotal", "amount": -14900}, // Negative amounts indicate money returned to the buyer.
            {"type": "tax", "amount": -1200},
            {"type": "total", "amount": -16100}
          ],
          "occurred_at": "2026-02-10T10:00:00Z",
          "status": "completed"
        }
      ],
      "permalink_url": "https://merchant.example.com/orders/67890"
    }