Order lifecycle (post-purchase)

After checkout is completed and an order is placed, you must push status updates to Google using the order webhook.

Endpoint: https://shoppingdataintegration.googleapis.com/v1/webhooks/partners/[PARTNER_ID]/events/order?key=[API_KEY]
- Google will share your PARTNER_ID and API_KEY with you.
- You can 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]
- For more details on how to use API keys, see Using API keys.
Payload: You must send the full order entity, for all updates.

1. Auth and request signing

Refer to the version you selected for your implementation.

Version January 23 2026

You can do symmetric key signing using HMAC key shared by Google with you.

OR you can refer to following instructions for asymmetric signature:

Select a key from the signing_keys array in UCP profile.
Create a detached JWT (RFC 7797) over the request body using the selected key.
Include the JWT in the Request-Signature header.
Include the key ID in the JWT header's kid claim to allow the receiver to identify which key to use for verification.

Version April 8 2026

Compute SHA-256 digest of the raw request body and set Content-Digest header.
Select a signing key from signing_keys in your UCP profile.
Build signature base per RFC 9421.
- See the spec for signed components
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 for more information.

2. Mandatory order update events

The following order event updates are required for the integration.

2.1. Order created event

Trigger: Immediately after the order is confirmed (status: processing).

Example: This example shows an order create after a buyer complete the checkout.

Version 2026-04-08

Key changes in this version in this example:

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 (e.g., "subtotal", "tax", "fee", "total").

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z", // Update this to the latest fulfillment / adjustment event occurred time.
  "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}
      ],
      "status": "processing"
    }
  ],
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "fee", "display_text": "Service Fee", "amount": 100},
    {"type": "tax", "display_text": "Tax", "amount": 800},
    {"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",
        "fulfillable_on": "now"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/789"
}

Version 2026-01-23

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
   // 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", "amount": 10000},
        {"type": "total", "amount": 10000}
      ],
      "status": "processing"
    }
  ],
     "totals": [
     {"type": "subtotal", "amount": 10000},
     {"type": "total", "amount": 10000}
   ],
  "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",
        "fulfillable_on": "now"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/789"
}

Version 2026-01-23

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
   // Full line items must be included
  "line_items": [
    {
      "id": "line_1",
      "item":
        {
          "id": "product_123",
          "title": "Running Shoes",
          "price": 10000
        },
      "quantity": { "total": 1, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "total", "amount": 10000}
      ],
      "status": "processing"
    }
  ],
     "totals": [
     {"type": "subtotal", "amount": 10000},
     {"type": "total", "amount": 10000}
   ],
  "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",
        "fulfillable_on": "now"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/789"
}

2.2. Fulfillment events

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

shipped: When items in the order have been shipped. Include tracking information if available.
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.

Version 2026-04-08

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
  "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",
        "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",
        "description": "Package delivered"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "permalink_url": "https://merchant.example.com/orders/123"
}

Version 2026-01-23

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
  "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",
        "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",
        "description": "Package delivered"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "permalink_url": "https://merchant.example.com/orders/123"
}

2.3. 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.
return: When items in the order are returned by the customer.
refund: When a refund is issued for an order or specific items.

Example (cancellation & refund): This example shows an order where the item was cancelled and refunded shortly after the order was placed.

Version 2026-04-08

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.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_02",
  "checkout_id": "checkout_02",
  "created_time": "2026-03-23T19:00:00Z",
  "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",
      "reason": "Refund for cancelled item",
      "line_items": [{ "id": "line_2", "quantity": 1 }],
      "amounts": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
      "occurred_at": "2026-02-09T11:05:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/12345"
}

Version 2026-01-23

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_02",
  "checkout_id": "checkout_02",
  "created_time": "2026-03-23T19:00:00Z",
  "line_items": [
    {
      "id": "line_2",
      "item": {
        "id": "product_456",
        "title": "Smart Watch",
        "price": 29900
      },
      "quantity": { "total": 1, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
      "status": "processing"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 29900},
    {"type": "tax", "amount": 2400},
    {"type": "total", "amount": 32300}
  ],
  "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",
      "reason": "Refund for cancelled item",
      "line_items": [{ "id": "line_2", "quantity": 1 }],
      "amounts": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
      "occurred_at": "2026-02-09T11:05:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/12345"
}

Example (return & refund): This example shows an order where the item was shipped, delivered, and then returned and refunded.

Version 2026-04-08

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 (e.g., -1) to indicate items being taken back.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-04-08"}]
    }
  },
  "id": "order_03",
  "checkout_id": "checkout_03",
  "created_time": "2026-03-23T19:00:00Z",
  "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",
        "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",
        "description": "Item delivered"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "adjustments": [
    {
      "id": "adj_return_1",
      "type": "return",
      "reason": "Item not compatible",
      "line_items": [{ "id": "line_3", "quantity": -1 }],  // Uses a negative value (-1) to indicate a return.
      "occurred_at": "2026-02-09T09:00:00Z",
      "status": "completed",
      "return_id": "ret_abc_123",
      "tracking_number": "RMAXYZ123",
      "tracking_url": "https://carrier.example.com/track/RMAXYZ123"
    },
    {
      "id": "adj_refund_2",
      "type": "refund",
      "reason": "Refund for returned item",
      "line_items": [{ "id": "line_3", "quantity": 1 }],
      "amounts": [
        {"type": "subtotal", "amount": 14900},
        {"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"
}

Version 2026-01-23

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_03",
  "checkout_id": "checkout_03",
  "created_time": "2026-03-23T19:00:00Z",
  "line_items": [
    {
      "id": "line_3",
      "item": {
        "id": "product_789",
        "title": "Wireless Earbuds",
        "price": 14900
      },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 14900},
        {"type": "tax", "amount": 1200},
        {"type": "total", "amount": 16100}
      ],
      "status": "fulfilled"
    }
  ],
  "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",
        "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",
        "description": "Item delivered"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "adjustments": [
    {
      "id": "adj_return_1",
      "type": "return",
      "reason": "Item not compatible",
      "line_items": [{ "id": "line_3", "quantity": 1 }],
      "occurred_at": "2026-02-09T09:00:00Z",
      "status": "completed",
      "return_id": "ret_abc_123",
      "tracking_number": "RMAXYZ123",
      "tracking_url": "https://carrier.example.com/track/RMAXYZ123"
    },
    {
      "id": "adj_refund_2",
      "type": "refund",
      "reason": "Refund for returned item",
      "line_items": [{ "id": "line_3", "quantity": 1 }],
      "amounts": [
        {"type": "subtotal", "amount": 14900},
        {"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"
}

3. 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 lifecycle (post-purchase) Stay organized with collections Save and categorize content based on your preferences.

1. Auth and request signing

Version January 23 2026

Version April 8 2026

2. Mandatory order update events

2.1. Order created event

Version 2026-04-08

Version 2026-01-23

Version 2026-01-23

2.2. Fulfillment events

Version 2026-04-08

Version 2026-01-23

2.3. Adjustment events

Version 2026-04-08

Version 2026-01-23

Version 2026-04-08

Version 2026-01-23

3. Recommended order update events

Order lifecycle (post-purchase)