Der Endpunkt vouchers/ stellt Ihnen eine Schnittstelle zur Verfügung mit der Sie Gutscheine in unserem Shop-System verwalten können. Mit dieser Schnittstelle können Sie Gutscheine erzeugen, löschen, Vorlagen erstellen und und vorhandene Gutscheine einsehen.

Inhaltsverzeichnis:

1 1. Unterstützte Methoden
2 2. Datenfelder
3 3. Methoden zur Verwaltung von Gutscheinen
- 3.1 3.1 GET vouchers
- 3.2 3.2 PUT vouchers/{id} - Coming soon
- 3.3 3.3 POST vouchers
- 3.4 3.4 DELETE vouchers/{id}
4 4. Methoden für Gutschein-Chargen
5 5. Methoden für Gutschein-Blaupausen
6 6. Methoden für Gutschein-Vorlagen
7 7. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Gutscheine	vouchers/
Gutschein-Chargen	vouchers/charges/
Gutschein-Blaupausen	vouchers/templates/
Gutschein-Vorlagen	vouchers/presets/

2. Datenfelder

2.1 Datenfelder eines Gutscheins

Name	Typ	Bedeutung

Name	Typ	Bedeutung
active	Boolean	Gibt an, ob der Gutschein aktiv ist (true = aktiv, false = deaktiviert).
chargeId	String	ID der Charge, zu der der Gutschein gehört.
createdAt	String	Zeitpunkt der Erstellung des Gutscheins.
id	String	Eindeutige ID des Gutscheins.
labels	String[]	Tags oder Bezeichnungen zur Gruppierung oder Identifikation des Gutscheins (z. B. Marketingaktionen).
maxUseCount	Integer	Maximale Anzahl an Einlösungen, bevor der Gutschein deaktiviert wird.
pool	Boolean	Gibt an, ob der Gutschein Teil eines Pools ist (gemeinsamer Kontingent).
types.appOnly	Boolean	Gutschein kann nur über die App eingelöst werden.
types.discount	Boolean	Werbegutschein / Kaufgutschein
types.freeShipping	Boolean	Gutschein gewährt kostenlosen Versand.
types.keepSurplus	Boolean	Verbleibender Restwert darf behalten und später erneut eingelöst werden.
types.multipleCustomer	Boolean	Gutschein ist mehrfach von verschiedenen Kunden einlösbar.
types.newCustomersOnly	Boolean	Gutschein darf nur von Neukunden verwendet werden.
types.maxUseCountSet	Boolean	Gutschein ist pro Benutzer begrenzt einlösbar.
types.maxUseCountPerUser	Integer	Maximale Anzahl an Einlösungen pro Benutzer
updatedAt	String	Zeitpunkt der letzten Aktualisierung des Gutscheins.
validCustomers[].id	Integer	ID eines Kunden, der berechtigt ist, den Gutschein einzulösen.
validCustomers[].number	String	Kundennummer eines berechtigten Kunden.
validProducts[].number	String	Produktnummer, für das der Gutschein gültig ist.
validProducts[].quantity	Integer	Mindestanzahl des Produkts im Warenkorb, damit Gutschein gilt.
validSubshops[]	String[]	Liste der Subshop-IDs, in denen der Gutschein gültig ist.
values[].currency	String	Währungscode (z. B. EUR, GBP), für den der jeweilige Wert gilt.
values[].percentValue	Float	Prozentualer Rabatt (z. B. 0.1 für 10 %).
values[].taxId	String	Steuer-ID, die auf den Gutscheinwert angewendet wird.
values[].usedValue	Float	Bereits eingelöster Wert des Gutscheins (für Mehrfachnutzung).
values[].value	Float	Gesamtwert des Gutscheins in der jeweiligen Währung.
values[].minOrderValue	Float	Mindestbestellwert in der Währung, um den Gutschein einzulösen.

Beispiel:

{
    "active": true,
    "chargeId": "example-charge",
    "createdAt": "2025-01-17T07:57:26.000Z",
    "id": "VOUCHER-XY57Z3",
    "labels": [
        "summer2025"
    ],
    "maxUseCount": 5,
    "pool": false,
    "types": {
        "appOnly": false,
        "discount": false,
        "freeShipping": false,
        "keepSurplus": true,
        "multipleCustomer": false,
        "newCustomersOnly": false,
        "maxUseCountPerUser": 122
        "maxUseCountSet": true
    },
    "updatedAt": "2025-01-17T07:57:26.000Z",
    "validCustomers": [
        {
            "id": 48
        },
        {
            "number": "1234"
        }
    ],
    "validProducts": [
        {
            "number": "go1",
            "quantity": 1
        }
    ],
    "validSubshops": [
        "deutsch",
    ],
    "values": [
        {
            "currency": "EUR",
            "percentValue": 0.0,
            "taxId": "",
            "usedValue": 10.0,
            "value": 42.0
        },
        {
            "currency": "GBP",
            "minOrderValue": 50.0,
            "percentValue": 0.0,
            "taxId": "",
            "value": 10.0
        }
    ]
}

2.2 Datenfelder einer Gutschein-Charge

Name	Typ	Bedeutung

Name	Typ	Bedeutung
createdAt	String	Zeitpunkt der Erstellung der Gutscheinladung (ISO 8601-Format, UTC).
creator	Integer	ID des Benutzers, der die Charge erstellt hat.
description	String	Freitextbeschreibung der Gutschein-Charge.
id	String	Eindeutige ID der Gutschein-Charge.
name	String	Name der Gutschein-Charge.
redeemed	Integer	Gibt an, ob Gutscheine der Charge eingelöst wurden. Mögliche Werte: `0 = NotRedeemed` `1 = PartiallyRedeemed` `2 = Redeemed`
updatedAt	String	Zeitpunkt der letzten Aktualisierung der Charge (ISO 8601-Format, UTC).
voucherChargeCount	Integer	Anzahl der mit dieser Charge erstellten Gutscheine.
voucherData	Objekt	Details zu Gutscheinen. Alle Felder stimmen mit den Feldern der Gutscheine überein.

Beispiel:

{
    "createdAt": "2025-04-11T13:25:53.000Z",
    "creator": 1,
    "description": "",
    "id": "82",
    "name": "myCharge",
    "redeemed": 0,
    "updatedAt": "2025-04-11T13:25:53.000Z",
    "voucherChargeCount": 1,
    "voucherData": {
        "labels": [
            "82"
        ],
        "maxUseCount": 999,
        "pool": false,
        "types": {
            "appOnly": false,
            "discount": true,
            "freeShipping": true,
            "keepSurplus": false,
            "maxUseCountSet": false,
            "multipleCustomer": true,
            "newCustomersOnly": false
        },
        "validProducts": [
            {
                "id": "100-41232",
                "quantity": 1
            }
        ],
        "values": [
            {
                "currency": "EUR",
                "minOrderValue": 1,
                "percentValue": 0,
                "taxId": "19",
                "usedValue": 0,
                "value": 55
            }
        ]
    }
}

2.3 Datenfelder einer Gutschein-Vorlage

Name	Typ	Bedeutung

Name	Typ	Bedeutung
active (optional)	Boolean	Gibt an, ob die Blaupause aktiv ist.
createdAt	String	Zeitpunkt, zu dem die Blaupause erstellt wurde (ISO 8601-Format, UTC).
templateId	String	Technische ID oder eindeutiger Name der Gutscheinblaupause.
updatedAt	String	Zeitpunkt der letzten Aktualisierung der Blaupause (ISO 8601-Format, UTC).
validFrom (optional)	String	Beginn der Gültigkeit.
validUntil (optional)	String	Ende der Gültigkeit.

Weitere Felder stimmen mit den Feldern der Gutscheine überein.

Beispiel:

{
    "active": true,
    "chargeId": "53",
    "createdAt": "2025-04-09T08:57:59.000Z",
    "labels": [],
    "templateId": "newTemplateName2",
    "types": {
        "appOnly": false,
        "discount": false,
        "freeShipping": false,
        "keepSurplus": false,
        "maxUseCountSet": false,
        "multipleCustomer": false,
        "newCustomersOnly": false
    },
    "updatedAt": "2025-04-29T08:48:39.000Z",
    "values": [
        {
            "currency": "EUR",
            "minOrderValue": 10,
            "percentValue": 0,
            "taxId": "",
            "value": 1
        }
    ]
}

2.4 Datenfelder einer Gutschein-Vorlage

Name	Typ	Bedeutung

Name	Typ	Bedeutung
createdAt	String	Zeitpunkt, zu dem die Vorlage erstellt wurde (ISO 8601-Format, UTC).
updatedAt	String	Zeitpunkt der letzten Aktualisierung der Vorlage (ISO 8601-Format, UTC).
presetId	String	Technische ID oder eindeutiger Name der Gutscheinvorlage.
system	Boolean	Gibt an, ob die Vorlage von Websale bereitgestellt wurde. Bei solchen Vorlagen können nicht alle Felder bearbeitet werden.
data.count	Integer	Anzahl der Gutscheine
data.data	Objekt	Details zum Gutschein. Alle Felder stimmen mit den Feldern der Gutscheine überein.

Beispiel:

{
    "createdAt": "1970-01-01T00:33:45.000Z",
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "basketProducts": [],
            "chargeId": "",
            "labels": [],
            "maxUseCount": 19,
            "name": "myPreset",
            "types": {
                "appOnly": false,
                "discount": true,
                "freeShipping": false,
                "keepSurplus": false,
                "maxUseCountSet": false,
                "multipleCustomer": true
            },
            "values": [
                {
                    "currency": "GBP",
                    "minOrderValue": 40,
                    "taxId": "19",
                    "value": 20
                }
            ]
        }
    },
    "presetId": "myPreset",
    "system": false,
    "updatedAt": "1970-01-01T00:33:45.000Z"
}

3. Methoden zur Verwaltung von Gutscheinen

In diesem Abschnitt werden alle Endpunkte zur Verwaltung einzelner Gutscheine beschrieben. Über die Schnittstelle können Gutscheine erstellt, aktualisiert, gelöscht und abgerufen werden. Die Verwaltung von Gutschein-Chargen wird in einem eigenen Abschnitt separat behandelt.

Für alle Operationen sind entsprechende Lese-, Schreib-, Erstell- oder Löschberechtigungen erforderlich.

3.1 GET vouchers

Diese Methode liefert eine paginierte Liste aller im System vorhandenen Gutscheine.

Über Filter- und Sortierparameter können die Ergebnisse gezielt eingeschränkt und geordnet werden. Die zurückgegebenen Gutscheindaten umfassen Informationen zu Aktivität, Gültigkeit, Einlösebedingungen und Wertangaben.

Für den Zugriff sind Leseberechtigungen erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/vouchers?size=100

Antwort:

{
    "endReached": true,
    "items": [
        {
            "active": true,
            "chargeId": "example-charge",
            "createdAt": "2025-01-17T07:57:26.000Z",
            "id": "VOUCHER-XY57Z3",
            "labels": [
                "summer2025"
            ],
            "maxUseCount": 5,
            "pool": false,
            "types": {
                "appOnly": false,
                "discount": false,
                "freeShipping": false,
                "keepSurplus": true,
                "multipleCustomer": false,
                "newCustomersOnly": false,
                "oncePerUser": false
            },
            "updatedAt": "2025-01-17T07:57:26.000Z",
            "validCustomers": [
                {
                    "id": 48
                },
                {
                    "number": "1234"
                }
            ],
            "validProducts": [
                {
                    "number": "go1",
                    "quantity": 1
                }
            ],
            "validSubshops": [
                "deutsch",
            ],
            "values": [
                {
                    "currency": "EUR",
                    "percentValue": 0.0,
                    "taxId": "",
                    "usedValue": 10.0,
                    "value": 42.0
                },
                {
                    "currency": "GBP",
                    "minOrderValue": 50.0,
                    "percentValue": 0.0,
                    "taxId": "",
                    "value": 10.0
                }
            ]
        }
    ],
    "nextPageToken": "Mw",
    "totalCount": 1
}

Filterfelder:

id, active, pool, chargeId, createdAt, updatedAt, validFrom, validUntil, maxUseCount

Sortierfelder:

id, active, pool, chargeId, createdAt, updatedAt, validFrom, validUntil, maxUseCount

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten.
400 Bad Request	"invalidValue"	`size` ∉ [1;300] `sort` ∉ {"asc", "desc"} `pageToken` ist keine Zahl oder kleiner als 0.
400 Bad Request	"unknownDataField"	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	"unknownOperation"	Ein Filtertyp ist ungültig.
400 Bad Request	"invalidCharacters"	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	"syntaxError"	`sort` enthält mehr als einen oder keinen ":".

3.2 PUT vouchers/{id} - Coming soon

Diese Methode aktualisiert die Eigenschaften eines bestehenden Gutscheins anhand seiner eindeutigen ID. Über den Request-Body können verschiedene Felder wie Aktivierungsstatus, Gültigkeitszeiträume, Werte oder Einlösebedingungen geändert werden. Nach erfolgreicher Aktualisierung wird eine Bestätigung zurückgegeben.

Schreibberechtigungen für Gutschein-Daten sind erforderlich.

Diese Methode ist derzeit noch nicht implementiert und für eine zukünftige Version geplant.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/vouchers/1CUA-8341-FD8Q-KPJ2

Antwort:

{
    "updateVoucher": "not implemented"
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Gutschein-Daten.

3.3 POST vouchers

Diese Methode erstellt einen oder mehrere neue Gutscheine. Die Gutscheine können entweder einer neuen Charge zugeordnet oder an eine bestehende Charge angehängt werden. Damit eine neue Charge erstellt wird, muss das Feld chargeId im Request Body leer sein.

Pro Anfrage können maximal 10.000 Gutscheine erstellt werden. Nach erfolgreicher Erstellung werden die zugehörige Charge-ID sowie die Anzahl der erzeugten Gutscheine zurückgegeben.

Erstellberechtigungen für Gutschein-Daten sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/vouchers

Request Body:

{
    "count": 1,
    "data": {
        "active": true,
        "name": "cvcv89",
        "chargeId": "",
        "maxUseCount": 1,
        "values": [
            {
                "value": 55,
                "currency": "GBP",
                "minOrderValue": 55,
                "taxId": ""
            }
        ],
        "types": {
            "keepSurplus": false,
            "discount": true,
            "freeShipping": false,
            "oncePerUser": true,
            "multipleCustomer": true,
            "appOnly": false
        },
        "basketProducts": [],
        "labels": []
    }
}

Antwort:

{
	"chargeId": "122",
	"count": 1
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Gutschein-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidFormat"	`count` ist keine Zahl.
400 Bad Request	"missing"	`appendToCharge` ist `true`, und `chargeId` fehlt.
400 Bad Request	"invalidValue"	`count` ∉ [0;10000] `data` fehlt oder ist kein Objekt.
400 Bad Request	"invalidCombination"	`count` ≠ 1 und `voucherId` ist nicht leer. Beim Erstellen von mehreren Gutscheinen wird die Id automatisch generiert und kann nicht manuell gesetzt werden. `newCustomersOnly` und `existingCustomersOnly` sind gesetzt.
400 Bad Request	"duplicateEntry"	`voucherId` oder `chargeId` existieren bereits.

API-Referenz Gutscheine

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. Datenfelder

2.1 Datenfelder eines Gutscheins

Beispiel:

2.2 Datenfelder einer Gutschein-Charge

Beispiel:

2.3 Datenfelder einer Gutschein-Vorlage

Beispiel:

2.4 Datenfelder einer Gutschein-Vorlage

Beispiel:

3. Methoden zur Verwaltung von Gutscheinen

3.1 GET vouchers

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 PUT vouchers/{id} - Coming soon

Beispiel:

Antwort:

Fehlercodes:

3.3 POST vouchers

Beispiel:

Request Body:

Antwort:

Fehlercodes: