Gutscheincodes und Rabatte implementieren

In diesem Leitfaden finden Sie die technische API-Referenz und die Nutzlastschemata für den Umgang mit Aktionscodes und Rabatten in Version 2026-04-08 des Universal Commerce Protocol (UCP).

Bevor Sie Ihre Endpunkte erstellen, sollten Sie sich die Übersicht zu Aktionscodes und Rabatten ansehen, um sich mit den allgemeinen Konzepten, mathematischen Invarianten und Regeln zur Fehlerbehandlung vertraut zu machen.

Discovery

Wenn Sie Rabattcodes von Google erhalten möchten, müssen Sie in Ihrem Profil angeben, dass Sie Rabatte unterstützen. In Version 2026-04-08 prüfen Plattformen, ob die Checkout-Funktion erweitert wurde, bevor sie Rabattcodes senden.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "extends": ["dev.ucp.shopping.checkout"],
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
        }
      ]
    }
  }
}

Auswirkungen auf Werbebuchungen und Summen

Angewendete Rabatte werden in den Checkout-Kernfeldern mit zwei verschiedenen Summentypen angegeben. Wenn ein Rabatt allocations hat, die auf Werbebuchungen verweisen, wird er zu items_discount hinzugefügt. Rabatte ohne Zuweisungen oder mit Zuweisungen zu Versandkosten oder Gebühren werden zu discount hinzugefügt.

Rabatttyp Summentyp Wo angegeben
Rabatt auf Werbebuchungsebene items_discount line_items[].totals[type=items_discount]
Rabatt auf Bestellungsebene discount totals[type=discount]

Versionsanforderung :

Für Version 2026-04-08 müssen Rabatteinträge in totals[] und line_items[].totals[] negative Werte verwenden, um ihre subtraktive Wirkung auf die Rechnung widerzuspiegeln. Beträge in den Arrays discounts.applied und allocations bleiben immer positive Ganzzahlen.

API-Beispiele für automatisch angewendete Angebote

In den folgenden Beispielen werden automatisch angewendete Rabatte veranschaulicht. Die Anfragenutzlasten enthalten kein discounts.codes-Array, die Antworten enthalten jedoch "automatic": true und lassen das Feld code weg.

Automatisch angewendeter Rabatt auf Artikelbasis

Ein 10 %-Rabatt auf die gesamte Website, der automatisch auf eine bestimmte Werbebuchung angewendet wird.

Beispielanfrage:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1
    }
  ]
}

Beispielantwort:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 9000}
      ]
    }
  ],
  "discounts": {
    "applied": [
      {
        "title": "10% Off Sitewide Sale",
        "amount": 1000,
        "automatic": true,
        "method": "each",
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1000}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 9000}
  ]
}

Automatisch angewendeter Rabatt auf Bestellungsebene

Eine Angebotsregel (z.B. „10 € Rabatt auf Bestellungen über 50 €“), die auf die gesamte Bestellung angewendet wird, ohne bestimmte Zuweisungen auf Werbebuchungsebene.

Beispielanfrage:

{
  "line_items": [ ... ]
}

Beispielantwort:

{
  "line_items": [ ... ],
  "discounts": {
    "applied": [
      {
        "title": "$10 Off Orders Over $50",
        "amount": 1000,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 6000},
    {"type": "discount", "display_text": "Order Promo", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 5000}
  ]
}

API-Beispiele für von Nutzern angewendete Angebote

In den folgenden Beispielen werden Rabatte veranschaulicht, die ausgelöst werden, wenn ein Nutzer einen Aktionscode eingibt. Die Anfragenutzlasten enthalten die angeforderten Codes und die Antworten geben sie zurück, während die angewendeten Beträge zugewiesen werden.

Rabatt auf Bestellungsebene

Ein Pauschalrabatt, der auf die Bestellsumme angewendet wird. Es sind keine Zuweisungen erforderlich. Der Rabatt gilt für die gesamte Bestellung und verwendet type: "discount".

Beispielanfrage:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"]
  }
}

Beispielantwort:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ]
}

Gemischte Rabatte (Artikel- und Bestellungsebene)

In diesem Beispiel werden beide Rabatttypen gezeigt: ein Rabatt pro Artikel (20% Rabatt), der Werbebuchungen zugewiesen wird, und ein automatischer Versandrabatt auf Bestellungsebene.

Beispielanfrage:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20"]
  }
}

Beispielantwort:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 2000 },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -800},
        {"type": "total", "amount": 3200}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 800,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 800}
        ]
      },
      {
        "title": "Free shipping on orders over $30",
        "amount": 599,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
    {"type": "discount", "display_text": "Order Discounts", "amount": -599},
    {"type": "fulfillment", "display_text": "Shipping", "amount": 0},
    {"type": "total", "display_text": "Total", "amount": 2601}
  ]
}

Abgelehnter Rabattcode

Wenn ein Code ungültig ist, wird er in codes wiedergegeben, aber aus applied weggelassen. Die Ablehnung wird mit einer warning im Array messages[] mitgeteilt.

Beispielanfrage:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"]
  }
}

Beispielantwort:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ],
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[1]",
      "content": "Code 'EXPIRED50' expired on December 1st"
    }
  ]
}

Gestapelte Rabatte mit Zuweisungen

Mehrere Rabatte mit vollständigen Zuweisungsaufschlüsselungen.

Beispielanfrage:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"]
  }
}

Beispielantwort:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 6000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 6000},
        {"type": "items_discount", "amount": -1500},
        {"type": "total", "amount": 4500}
      ]
    },
    {
      "id": "li_2",
      "item": { "title": "Socks", "price": 4000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 3000}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 2000,
        "method": "each",
        "priority": 1,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1200},
          {"path": "$.line_items[1]", "amount": 800}
        ]
      },
      {
        "code": "EXTRA5",
        "title": "Extra $5 Off",
        "amount": 500,
        "method": "across",
        "priority": 2,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 300},
          {"path": "$.line_items[1]", "amount": 200}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
    {"type": "total", "display_text": "Total", "amount": 7500}
  ]
}
Zurück
Warenkorb-API