In dieser Anleitung finden Sie die technische API-Referenz und Nutzlastschemata für das Senden vollständiger Bestellstatusaktualisierungen, Fulfillment-Ereignisse und Anpassungen an Google über Webhooks für Version 2026-04-08 des Universal Commerce Protocol (UCP).
Bevor Sie Ihre Endpunkte erstellen, lesen Sie die Übersicht zum Bestelllebenszyklus, um sich mit den allgemeinen Konzepten, obligatorischen Ereignissen und Details zu Webhook-Endpunkten vertraut zu machen.
Authentifizierung und Anfragensignatur
Zu den wichtigsten Änderungen in Version 2026-04-08 gehören die Einführung neuer obligatorischer Webhook-Header und spezifischer Verfahren für die Anfragensignatur.
Erforderliche Webhook-Header
Die folgenden HTTP-Header sind für alle Webhook-Anfragen obligatorisch:
Webhook-Id: Eine eindeutige Kennung für dieses bestimmte Webhook-Ereignis. Diese ID muss mit deriddes primären Ereignisses übereinstimmen, das gesendet wird (z. B. die ID des Fulfillment-Ereignisses oder die ID des Anpassungsereignisses).Webhook-Timestamp: Der Zeitstempel, der angibt, wann das Ereignis aufgetreten ist.
Diese Header ersetzen die Felder id und created_time, die zuvor in der Bestellnutzlast erwartet wurden.
Anfragensignatur
- Berechnen Sie den SHA-256-Digest des Roh-Anfragetexts und legen Sie den Header
Content-Digestfest. - Wählen Sie einen Signaturschlüssel aus
signing_keysin Ihrem UCP-Profil aus. - Erstellen Sie die Signaturbasis gemäß RFC
9421.
- Spezifikation für signierte Komponenten
- Legen Sie die Header
UCP-Agent,Signature-InputundSignaturefest.UCP-Agentist ein Link zu Ihrem UCP-Profil im Formatprofile="https://merchant.example.com/.well-known/ucp".Signature-Inputist ein als Dictionary strukturiertes Feld, das die in der Signatur enthaltenen Komponenten sowie die zum Signieren verwendetekeyidbeschreibt. Diese muss mit derkidIhres ausgewählten Signaturschlüssels aussigning_keysin Ihrem UCP-Profil übereinstimmen.- Der Header
Signatureenthält Ihre Signaturbasis, die mit Ihrem privaten Schlüssel signiert und dann base64-codiert wird.
Weitere Informationen finden Sie in der Signaturanleitung auf ucp.dev.
Ereignis „Bestellung erstellt“
- Trigger: Unmittelbar nach Bestätigung der Bestellung (
status: processing).
Wichtige Änderungen in dieser Version :
- Das Feld
currencyist jetzt auf der obersten Ebene des Order-Objekts erforderlich. - Das Feld
typein jedem Objekt im Arraytotalsist jetzt ein offener String (z. B. „subtotal“, „tax“, „fee“, „total“). - Der obligatorische Header
Webhook-Identhält eine eindeutige Kennung für das Webhook-Ereignis. Das Feldidin der Nutzlast mit der Bestellbestätigungs-ID ist weiterhin erforderlich. - Der obligatorische Header
Webhook-Timestampenthält die Erstellungszeit und ersetzt das bisherige Feldcreated_timein der Nutzlast.
Beispiel: In diesem Beispiel wird eine Bestellung gezeigt, die erstellt wurde, nachdem ein Käufer den Checkout abgeschlossen hat.
Erforderliche Header :
Webhook-Id: order_01Webhook-Timestamp: 2026-03-23T19:00:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_01",
"checkout_id": "checkout_01",
"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}
],
// The status of a line item must match total and fulfilled quantities (e.g., total 1, fulfilled 0 -> status: processing).
"status": "processing"
}
],
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 10000}, // Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
{"type": "fee", "display_text": "Service Fee", "amount": 100},
{"type": "tax", "display_text": "Tax", "amount": 800}, // Tax-inclusive markets: Omit this entry.
{"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", // Maximum length: 200 characters.
"fulfillable_on": "now"
}
]
},
"permalink_url": "https://merchant.example.com/orders/789"
}
Fulfillment-Ereignisse
Diese Ereignisse werden als Teil des Arrays fulfillment.events gesendet.
Bestellung versandt
Wenn Artikel in der Bestellung versandt wurden. Die Felder tracking_number und tracking_url sind für versandte Ereignisse erforderlich, da sie benötigt werden, um Artikel auf der Seite „Meine Bestellungen“ korrekt zu gruppieren.
Bestellung zugestellt
Wenn Artikel in der Bestellung zugestellt wurden.
Beispiel (shipped und delivered) : In diesem Beispiel wird eine Bestellaktualisierung gezeigt, nachdem der Artikel versandt und dann zugestellt wurde.
Erforderliche Header :
Webhook-Id: fulfill_evt_2Webhook-Timestamp: 2026-02-10T14:00:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_01",
"checkout_id": "checkout_01",
"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",
"carrier": "FedEx",
"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",
"carrier": "FedEx",
"description": "Package delivered"
}
],
"expectations": [{ "...": "..." }]
},
"permalink_url": "https://merchant.example.com/orders/123"
}
Beispiele für Bestellungen mit mehreren Artikeln
Die folgenden Beispiele zeigen, wie Aktualisierungen für Bestellungen mit mehreren Artikeln und getrennte Lieferungen strukturiert werden. Regeln zur Ableitung von Paketstatus finden Sie unter Paketstatus ermitteln.
Bestellung mit mehreren Artikeln, Lieferung im selben Paket
In diesem Beispiel wird eine Bestellaktualisierung für ein einzelnes Paket mit mehreren Artikeln gezeigt. Alle Positionen sind in einem einzigen shipped-Ereignis mit derselben Sendungsnummer gruppiert.
Erforderliche Header :
Webhook-Id: fulfill_evt_1Webhook-Timestamp: 2026-02-08T10:30:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_multi_01",
"checkout_id": "checkout_multi_01",
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": { "id": "product_1", "title": "Item 1", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "display_text": null, "amount": 5000},
{"type": "total", "display_text": null, "amount": 5000}
],
"status": "fulfilled"
},
{
"id": "line_2",
"item": { "id": "product_2", "title": "Item 2", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "display_text": null, "amount": 5000},
{"type": "total", "display_text": null, "amount": 5000}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
{"type": "fee", "display_text": "Shipping", "amount": 500},
{"type": "total", "display_text": "Total", "amount": 10500}
],
"fulfillment": {
"expectations": [
{
"id": "exp_1",
"line_items": [
{ "id": "line_1", "quantity": 1 },
{ "id": "line_2", "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": "Standard Shipping",
"fulfillable_on": "now"
}
],
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-08T10:30:00Z",
"type": "shipped",
"line_items": [
{ "id": "line_1", "quantity": 1 },
{ "id": "line_2", "quantity": 1 }
],
"tracking_number": "123456789",
"tracking_url": "https://fedex.com/track/123456789",
"carrier": "FedEx",
"description": "Both items shipped together"
}
]
},
"permalink_url": "https://merchant.example.com/orders/456"
}
Bestellung mit mehreren Artikeln, getrennte Lieferung
In diesem Beispiel wird eine Bestellaktualisierung für getrennte Lieferungen gezeigt. Es gibt mehrere shipped-Ereignisse, die jeweils auf die spezifischen line_items im jeweiligen Paket verweisen und unterschiedliche Sendungsnummern haben. Da jedes Paket eine eigene Fulfillment-Zusicherung darstellt (z. B. unterschiedliche Geschwindigkeiten und Kosten beim Checkout mit mehreren Gruppen), werden auch die expectations aufgeteilt.
Erforderliche Header :
Webhook-Id: fulfill_evt_2Webhook-Timestamp: 2026-02-09T14:00:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_multi_02",
"checkout_id": "checkout_multi_02",
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": { "id": "product_1", "title": "Item 1", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "display_text": null, "amount": 5000},
{"type": "total", "display_text": null, "amount": 5000}
],
"status": "fulfilled"
},
{
"id": "line_2",
"item": { "id": "product_2", "title": "Item 2", "price": 5000 },
"quantity": { "total": 1, "fulfilled": 1 },
"totals": [
{"type": "subtotal", "display_text": null, "amount": 5000},
{"type": "total", "display_text": null, "amount": 5000}
],
"status": "fulfilled"
}
],
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
{"type": "fee", "display_text": "Shipping", "amount": 1500},
{"type": "total", "display_text": "Total", "amount": 11500}
],
"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": "Standard Shipping",
"fulfillable_on": "now"
},
{
"id": "exp_2",
"line_items": [{ "id": "line_2", "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": "Express Shipping",
"fulfillable_on": "now"
}
],
"events": [
{
"id": "fulfill_evt_1",
"occurred_at": "2026-02-08T10:30:00Z",
"type": "shipped",
"line_items": [{ "id": "line_1", "quantity": 1 }],
"tracking_number": "PKG1_TRACKING",
"tracking_url": "https://fedex.com/track/PKG1_TRACKING",
"carrier": "FedEx",
"description": "First item shipped in package 1"
},
{
"id": "fulfill_evt_2",
"occurred_at": "2026-02-09T14:00:00Z",
"type": "shipped",
"line_items": [{ "id": "line_2", "quantity": 1 }],
"tracking_number": "PKG2_TRACKING",
"tracking_url": "https://fedex.com/track/PKG2_TRACKING",
"carrier": "FedEx",
"description": "Second item shipped in package 2"
}
]
},
"permalink_url": "https://merchant.example.com/orders/457"
}
Beispiele für Anpassungsereignisse
Die folgenden Beispiele zeigen, wie Aktualisierungen für Erstattungen, Rückgaben und Stornierungen strukturiert werden. Eine Liste der unterstützten Ereignisse und ihrer Definitionen finden Sie in der Übersicht zum Bestelllebenszyklus unter Anpassungs ereignisse.
Bestellstornierung und Erstattung
In diesem Beispiel wird eine Bestellung gezeigt, bei der der Artikel kurz nach der Bestellung storniert und erstattet wurde.
Wichtige Änderungen in dieser Version in diesem Beispiel :
- Für Positionen, die von einer
cancellationbetroffen sind, wird jetzt"status": "removed"im Hauptarrayline_itemsverwendet. - Wenn
line_items.statusden Wertremovedhat:- Der Wert von
line_items.quantity.totalwird auf0gesetzt. - Die ursprüngliche Menge wird im neuen Feld
line_items.quantity.originalgespeichert.
- Der Wert von
Erforderliche Header :
Webhook-Id: adj_refund_1Webhook-Timestamp: 2026-02-09T11:05:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_02",
"checkout_id": "checkout_02",
"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",
"description": "Refund for cancelled item",
"line_items": [{ "id": "line_2", "quantity": -1 }],
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": -29900}, // Negative amounts indicate money returned to the buyer. Tax-inclusive markets: Set display_text to "Subtotal (including taxes)". Amount must include tax.
{"type": "tax", "amount": -2400}, // Tax-inclusive markets: Omit this entry.
{"type": "total", "display_text": "Total", "amount": -32300}
],
"occurred_at": "2026-02-09T11:05:00Z",
"status": "completed"
}
],
"permalink_url": "https://merchant.example.com/orders/12345"
}
Bestellrückgabe und Erstattung
In diesem Beispiel wird eine Bestellung gezeigt, bei der der Artikel versandt, zugestellt und dann zurückgegeben und erstattet wurde.
Wichtige Änderungen in dieser Version in diesem Beispiel :
- Für Positionen, die von einer
returnbetroffen sind, wird jetzt"status": "removed"im Hauptline_itemsArray verwendet. - Wenn
line_items.statusden Wertremovedhat:- Der Wert von
line_items.quantity.totalwird auf0gesetzt. - Die ursprüngliche Menge wird im neuen Feld
line_items.quantity.originalgespeichert.
- Der Wert von
- In
adjustmentsvom Typreturnwird im Feldline_items.quantityinnerhalb der Anpassung ein negativer Wert (z. B.-1) verwendet, um zurückgenommene Artikel anzugeben.
Erforderliche Header :
Webhook-Id: adj_refund_2Webhook-Timestamp: 2026-02-10T10:00:00Z
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.order": [{"version": "2026-04-08"}]
}
},
"id": "order_03",
"checkout_id": "checkout_03",
"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",
"carrier": "FedEx",
"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",
"carrier": "FedEx",
"description": "Item delivered"
},
{
"id": "fulfill_evt_3",
"occurred_at": "2026-02-09T09:00:00Z",
"type": "returned",
"line_items": [{ "id": "line_3", "quantity": 1 }],
"tracking_number": "987654321",
"tracking_url": "https://fedex.com/track/987654321",
"carrier": "FedEx",
"description": "Item returned"
}
],
"expectations": [{ "...": "..." }]
},
"adjustments": [
{
"id": "adj_return_1",
"type": "return", // a matching fulfillment event is also added to represent return shipping.
"description": "Item not compatible",
"line_items": [{ "id": "line_3", "quantity": -1 }], // Uses a negative value (such as -1) to indicate a return.
"occurred_at": "2026-02-09T09:00:00Z",
"status": "completed"
},
{
"id": "adj_refund_2",
"type": "refund",
"description": "Refund for returned item",
"line_items": [{ "id": "line_3", "quantity": -1 }],
"totals": [
{"type": "subtotal", "amount": -14900}, // Negative amounts indicate money returned to the buyer.
{"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"
}