Order lifecycle (post-purchase)

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

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.

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:

    • 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).
  • 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.

Next steps

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

Previous
Native checkout overview
Next
Error codes