Storefront API Gutscheine

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

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

Body-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
}

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

Paramter	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
      }
    ]
  }
}

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 einlösbaren Gutscheinen pro Bestellung wurde erreicht.
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.

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