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=[PROD_API_KEY]
- Google will share your PARTNER_ID and PROD_API_KEY with you.
Payload: You must send the full order entity, for all updates.

1. Auth and request signing

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

{
  "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 the fulfillment.events array).

Identity linking (optional)

Order lifecycle (post-purchase) Stay organized with collections Save and categorize content based on your preferences.