Storefront API Gutscheine

Gutscheincodes in der Storefront über die Storefront API prüfen, einlösen und entfernen sowie aktualisierte Warenkorbsummen und Rabatte abrufen.

Die Storefront API Gutscheine ermöglicht es, Gutscheincodes in der Storefront einzulösen und zu entfernen. Die API prüft dabei automatisch, ob ein Code gültig ist, und liefert nach der Einlösung die aktualisierten Warenkorbwerte (z. B. Rabatte und Summen) sowie bei Bedarf Hinweise/Fehlermeldungen zurück.

---

​

Unterstützte Methoden

Angabe aller Unterstützten Methoden

Befehl	Endpunkte	GET	PUT	POST	DELETE
Gutschein Daten auslesen	voucher/get
Gutschein einlösen	voucher/redeem
Gutschein löschen	voucher/delete

​

Fehlerformat

Alle Fehler werden mit HTTP 400 und folgendem Rumpf beantwortet:

{
  "error": "actionFailed",
  "detail": "Action Failed",
  "actionErrors": [
    { "code": "invalidVoucherId", "subCode": "", "field": "id", "text": "…", "details": {} }
  ]
}

• error = invalidParameters bei Fehlern in Parametern/Feldtypen (Details in paramErrors, Schlüssel = Parametername, Wert {"type": "missing" | "invalidFormat" | "invalidValue" | "unknownField" | …}).
• error = actionFailed bei fachlichen Fehlern. Die in den folgenden Tabellen genannten Fehlercodes stehen dann in actionErrors[].code.
• Ein Aufruf mit falscher HTTP-Methode wird mit HTTP 404 beantwortet (nicht 405).
• Fehlt die Session (x-session), wird mit HTTP 400 geantwortet.

​

Methoden für Gutscheine

Diese Methoden ermöglichen das Prüfen, Einlösen und Entfernen von Gutscheinen direkt im Warenkorb oder im Checkout.

​

GET voucher/get

Dieser Aufruf liest Stammdaten zu einem Gutscheincode aus (z.B. Wert, Währung, Mindestbestellwert). Diese Informationen können im Warenkorb und Checkout verwendet werden, um einen Gutschein vor dem Einlösen zu prüfen und Infos wie Betrag und Bedingungen anzuzeigen.

Beispiel-Aufruf für den Gutschein mit der Gutscheinnummer 7G3M-L2UU-CK1B-A2J2:

GET https://<ihr-shop>.de/api/v1/voucher/get?id=7G3M-L2UU-CK1B-A2J2

​

Parameterübersicht

​

Query-Parameter

Parameter	Typ	Beschreibung
id	String	Pflichtfeld Gutscheincode, der abgefragt werden soll.

​

Beispiel-Response

{
  "currency": "EUR",
  "id": "7G3M-L2UU-CK1B-A2J2",
  "minOrderValue": 0,
  "taxId": "19",
  "value": 10.5
}

Feld	Typ	Beschreibung
id	string	Gutscheincode.
value	float	Aktuell wirksamer Wert (absoluter Wert plus errechneter Prozentanteil, gedeckelt durch maxDiscountValue). Ist der Mindestbestellwert nicht erreicht, ist der Wert 0.
currency	string	Währung des Gutscheins.
taxId	string	Steuerschlüssel des Gutscheins.
usedValue	float	Bereits verbrauchter Wert. Nur vorhanden, wenn gesetzt.
minOrderValue	float	Mindestbestellwert. Nur vorhanden, wenn gesetzt.
maxDiscountValue	float	Maximaler Rabattbetrag bei Prozentgutscheinen. Nur vorhanden, wenn gesetzt.
validFrom / validUntil	string (ISO 8601)	Gültigkeitszeitraum. Nur vorhanden, wenn gesetzt.

​

POST voucher/redeem

Dieser Aufruf löst einen Gutscheincode für den aktuellen Warenkorb ein und liefert Informationen zum eingelösten Gutschein und zum verbleibenden Wert. Dieser Befehl kann verwendet werden, um im Warenkorb oder Checkout den Gutschein zu verrechnen oder den eingelösten Betrag und ggf. den Restwert anzuzeigen.

Beispiel-Aufruf für die Einlösung des Gutscheins 7G3M-L2UU-CK1B-A2J2:

POST https://<ihr-shop>.de/api/v1/voucher/redeem

​

Beispiel-Request

{
  "id": "7G3M-L2UU-CK1B-A2J2"
}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
id	string	Pflichtfeld Gutscheincode, der einzulösen ist.

​

Beispiel-Response

{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 10.5,
    "vouchers": [
      {
        "currency": "EUR",
        "id": "7G3M-L2UU-CK1B-A2J2",
        "taxId": "19",
        "usedValue": 0,
        "value": 10.5
      }
    ]
  }
}

Wirkungslose Gutscheine

voucher/redeem prüft nur die Gültigkeit des Codes, nicht seine Wirkung auf den aktuellen Warenkorb. Ein Gutschein kann ohne Fehler eingelöst werden und trotzdem 0,00 Rabatt ergeben. Prüfen Sie deshalb nach dem Einlösen ineffectiveVoucherErrors und isOrderBlockedByIneffectiveVoucher aus den Checkout-Daten.

Code	Bedeutung
noValidProducts	Im Warenkorb liegt kein Produkt, für das der Gutschein gilt.
minOrderValueNotReached	Der Mindestbestellwert des Gutscheins ist nicht erreicht.

Jeder Eintrag hat die Felder code, subCode (immer leer), field (immer leer), text (übersetzter Meldungstext) und details.voucherId (fehlt, wenn sich der Fehler auf die Summe mehrerer Gutscheine bezieht). Ist isOrderBlockedByIneffectiveVoucher = true, lehnt der Shop die Bestellbestätigung mit dem Fehlercode voucherIneffective ab.

​

Fehlercodes

Fehlercode	Beschreibung
invalidVoucherId	Die angegebene ID ist kein gültiger Gutscheincode.
deactivated	Der Gutschein wurde deaktiviert.
expired	Der Gutschein ist abgelaufen.
notYetValid	Der Gutschein ist noch nicht gültig.
maxCountExceeded	Die maximale Anzahl an Gutscheinen pro Bestellung wurde erreicht. Die Obergrenze wird pro Shop konfiguriert. Der Standardwert ist 1. Der aktuell geltende Wert steht im Feld maximumCount der Gutscheinübersicht.
valueSpent	Der Gesamtwert des Gutscheins ist bereits verbraucht.
currencyMismatch	Die Gutscheinwährung passt nicht zur Shop-Währung.
invalidCustomer	Der Gutschein darf von diesem Kunden nicht eingelöst werden.
invalidSubshop	Der Gutschein darf in diesem Subshop nicht eingelöst werden.
missingId	Es wurde kein Gutscheincode übergeben.
duplicateId	Dieser Gutscheincode ist bereits im Warenkorb eingelöst.
expressCheckoutNotAllowed	Ein Express-Checkout ist aktiv - Gutscheine dürfen derzeit nicht geändert werden.
insuffientAmount	Der verfügbare Gutscheinwert reicht nicht aus. (Schreibweise wie im Code, mit fehlendem „ic“.)
repoUpdateFailed	Der Gutschein konnte technisch nicht aktualisiert werden.
invalidVoucherConfiguration	Der Gutschein ist fehlerhaft konfiguriert (kein Typ hinterlegt).

​

DELETE voucher/delete

Dieser Aufruf entfernt einen eingelösten Gutscheincode aus dem aktuellen Warenkorb und aktualisiert die Gutscheinübersicht. Dieser Befehl kann verwendet werden, um im Warenkorb oder Checkout eine versehentlich eingelöste oder nicht gewünschte Gutscheinanwendung rückgängig zu machen.

Beispiel-Aufruf für das Entfernen des Gutscheins mit dem Code 7G3M-L2UU-CK1B-A2J2:

DELETE https://<ihr-shop>.de/api/v1/voucher/delete

​

Beispiel-Request

{
  "id": "7G3M-L2UU-CK1B-A2J2"
}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
id	String	Pflichtfeld Gutscheincode, der entfernt werden soll.

​

Beispiel-Response

{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 0,
    "vouchers": []
  }
}

​

Fehlercodes

Fehlercode	Beschreibung
invalidVoucherId	Die angegebene ID ist kein gültiger Gutscheincode.
expressCheckoutNotAllowed	Ein Express-Checkout ist aktiv - der Gutschein darf derzeit nicht entfernt werden.