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=[PROD_API_KEY]
- Google will share your PARTNER_ID and PROD_API_KEY with you.
- Payload:You must send the fullorder entity, for all updates.
1. Auth and request signing
- Compute SHA-256 digest of the raw request body and set
Content-Digestheader. - Select a signing key from
signing_keysin your UCP profile. - Build signature base per RFC
9421
.
- See the spec for signed components
- Set
UCP-Agent,Signature-Input, andSignatureheaders.-
UCP-Agentis a link to your UCP profile in the formatprofile="https://merchant.example.com/.well-known/ucp". -
Signature-Inputis a dictionary structured field describing the components contained within the signature, as well as thekeyidused to sign, which must match thekidof your selected signing key fromsigning_keysin your UCP profile. -
Signatureheader 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).
{
"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"
:
{
"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.
{
"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.
{
"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.
{
"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 thefulfillment.eventsarray).
-
