After checkout is completed and an order is placed, you must push status updates to Google using Webhooks. The API key must be sent in query params or headers.
1. Order Created Event
- Trigger: Immediately after the order is confirmed (
status: processing). - Endpoint:
POST /webhooks/partners/{partner_id}/events/order
Payload: You must send the full order entity.
{
"ucp": { "version": "2026-01-23", "capabilities": [...] },
"id": "order_01",
"checkout_id": "checkout_01",
// 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. Order Updates
- Trigger: When there is an update to the order status (e.g., item ships or is canceled).
- Requirement: You must send the full order entity again, not just a partial update.
The following event types are mandatory:
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",
"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"
}
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",
"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",
"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).