After checkout is completed and an order is placed, you must push status updates
to Google using the order webhook. Pushing these events ensures that order
tracking, shipping, and returns are accurately reflected on the consumer **My
orders** page.

## Webhook endpoint

To push order updates, send a `POST` request containing the full order entity
payload to the following endpoint:

    POST https://shoppingdataintegration.googleapis.com/v1/webhooks/partners/PARTNER_ID/events/order?key=API_KEY

Google shares a specific `PARTNER_ID` and `API_KEY` with you during onboarding.
Provide the API key in one of two ways:

- As a URL query parameter: `?key=API_KEY`
- Using the HTTP header: `X-Goog-Api-Key: API_KEY`

## Acknowledgment and response

When you push order updates to the webhook endpoint, Google returns an HTTP
response to acknowledge receipt. A `200 OK` (or any `2xx` status code) indicates
that the payload was received successfully.

For details on the expected response body, see the version-specific
implementation guides. To select your version, see [Next steps](https://developers.google.com/merchant/ucp/guides/overview/order-lifecycle#next-steps).

### Error handling and retries

- **5xx server errors:** a `5xx` status code indicates a temporary issue. Retry the request using exponential backoff.
- **4xx client errors:** a `4xx` status code (such as `400 Bad Request` or `401 Unauthorized`) indicates a problem with the payload or authentication. Investigate these errors immediately and don't retry without modifying the request.

For more information about error codes, see [Error codes](https://developers.google.com/merchant/ucp/guides/overview/error-codes).

## Mandatory order update events

You must report the following order status changes:

- **Order created:** triggered immediately after the order is confirmed (`status: processing`).
- **Order shipped:** triggered when items in the order leave the warehouse. Requires `tracking_number` and `tracking_url`.
- **Order delivered:** triggered when items are delivered to the recipient.

> [!NOTE]
> **Note:** a sequential progression from `shipped` to `delivered` is mandatory.

## Recommended order update events

To provide the best user experience, we also recommend sending updates for the
following events:

- **Adjustment events:**

  - `dispute`: when a customer disputes a charge.
- **Fulfillment events:**

  - `canceled`: when a fulfillment is canceled (sent within the `fulfillment.events` array).

## Order logic and status mapping

To render the "My orders" page correctly, Google relies on specific logic
mapping within your payload.

### Line item requirements

- Line items must not be empty, and must include `item` product information.
- A line item's status must accurately reflect the `total` and `fulfilled`
  quantities (where `fulfilled` represents delivered items), per the [UCP
  spec](https://ucp.dev/latest/specification/order/#order-line-item):

  - `processing`: when `fulfilled` is 0 and `total` \> 0 (for example, `total: 2`, `fulfilled: 0`).
  - `partial`: when `fulfilled` is greater than 0 but less than `total` (for example, `total: 2`, `fulfilled: 1`).
  - `fulfilled`: when `fulfilled` equals `total` and `total` \> 0 (for example, `total: 2`, `fulfilled: 2`).
  - `removed`: when `total` is 0 (for example, `total: 0`, `fulfilled: 0`).

### Adjustment events

Any events involving money movement should be sent as part of the `adjustments`
array.

- `cancellation`: when an entire order or specific items within an order are cancelled prior to fulfillment.
- `return`: when items in the order are returned by the customer after fulfillment.
- `refund`: when a refund is issued for an order or specific items.

### Multi-item orders

The following sections explain how multi-item orders and packages are grouped
and tracked.

#### Multi-item package grouping

Items on the "My orders" page are grouped by packages (that have the same
`tracking_url`). If a package is partially returned, the returned items are
split out to a separate section on the "My orders" page.

#### Package status

The statuses shown for the package are one of the following: ordered, shipped,
delivered, returned, refunded, canceled. Package statuses are derived from the
`type` attribute of the `fulfillment` events and `adjustments` objects.

#### How package status is determined

If there is an adjustment event with `status: completed`, then the package will
display the appropriate status of Returned, Refunded, or Cancelled, based on the
adjustment event type.

| Adjustment Event properties | Package status |
|---|---|
| `type: return`, `status: completed` | Returned |
| `type: refund`, `status: completed` | Refunded |
| `type: cancellation`, `status: completed` | Cancelled |

If there is no completed adjustment, then the status will be based on the
fulfillment event type:

| Fulfillment Event properties | Package status |
|---|---|
| `type: shipped` | Shipped (Expected by \<date\>) |
| `type: delivered` | Delivered |
| No fulfillment event | Ordered |

## Technical validation rules

To ensure that order updates are processed successfully, your webhook payloads
must adhere to specific data validation and pricing formatting rules.

### Order rejection causes

Google validates incoming webhook payloads and rejects updates if they meet any
of the following conditions:

- The request body doesn't contain an order entity.
- The payload is missing a `checkout_id` or `id` (the [order confirmation
  ID](https://ucp.dev/latest/specification/checkout/#order-confirmation)).
- The payload contains a timestamp older than the latest recorded update.
- An adjustment event is sent with a type other than `refund`, `return`, `credit`, `price_adjustment`, `dispute`, or `cancellation`.
- Any shipping description exceeds 200 characters.

### Tax-inclusive pricing

If you operate in markets where tax is included in the subtotal, the order
entity must reflect the following in the `totals` array across all webhook
events:

- **Subtotal:** include all applicable taxes in the `subtotal` amount and set the `display_text` to `"Subtotal (including taxes)"`.
- **Fulfillment:** include a `display_text` entry for shipping or fulfillment costs (for example, `"Shipping"`).
- **Tax:** omit separate `"tax"` entries from the `totals` array.

## Webhook latency and retries

To ensure reliable delivery of order updates and prevent client-side timeouts or
retry storms, configure your webhook client using the following guidelines:

- **Timeouts:** set your HTTP client timeout to **10 seconds** (at minimum 5--10 seconds) in all environments. While typical P99 processing latency is under 1 second, this longer timeout accommodates occasional latency from cross-region network transit and cold-cache verifications.
- **Retries:** automatically retry requests that time out or fail with a server error (`5xx`) using exponential backoff.
- **Idempotency:** send the exact same `Idempotency-Key` header for all retries of a specific event to prevent duplicate processing.

## Next steps

To view version-specific JSON payload examples, webhook headers, and request
signing instructions, see the implementation guide for your target UCP version:

- [Order lifecycle implementation for version 2026-04-08](https://developers.google.com/merchant/ucp/implementation/2026-04-08/order-lifecycle)
- [Order lifecycle implementation for version 2026-01-23](https://developers.google.com/merchant/ucp/implementation/2026-01-23/order-lifecycle)