Coupon Update API für Online-Gutscheine

API Version

PUT

/api/coupon/v2/update

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "nm": "$10 discount coupon",
    "disc": 10,
    "endYmd": "2025-12-31",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

cpnNostringrequired: Coupon-Nummer.
domain string: Coupon-Domain.
In Premium-Tarifen und höher verfügbar: Sie können eine benutzerdefinierte Domain angeben.
webhookEnableYn string
Enum: YN: Einstellung für die Webhook-Nutzung.
Der globale Webhook muss aktiviert sein.
Diese Funktion ist nur im Enterprise-Tarif verfügbar.
nmstring: Coupon-Name.
discTypeIdxinteger: Rabatt-Typ. (457: Prozentsatz %, 458: Fester Betrag)
discdouble: Für Prozentsatz (457): Bereich 1–100 %. Für festen Betrag (458): Betrag eingeben.
discCurrencystring: Währungseinheit. Erforderlich bei Verwendung eines festen Betragsrabattes (discTypeIdx:458).
strtYmddate: Startdatum der Coupon-Gültigkeit. Beispiel: 2024-10-01
endYmddate: Ablaufdatum des Coupons. Beispiel: 2024-12-31
Das Ablaufdatum kann nur bis zum 31. Dezember des folgenden Jahres festgelegt werden.
useLimitinteger: Nutzungsbeschränkung des Coupons. (0: Unbegrenzt, 1–5: Begrenzte Nutzung)
Wenn auf 2 oder mehr festgelegt, muss der Wert userId angegeben werden.
grpIdxinteger: Coupon-Gruppe. Wird verwendet, um Coupons in Gruppen zu verwalten. Die Gruppen-ID (IDX) kann im Dashboard eingesehen werden.
Wenn Gruppeneinstellungen und Coupon-Einstellungen überschneiden, haben die Gruppeneinstellungen Vorrang.
tmplIdxinteger: Coupon-Vorlage. Wird beim Erstellen eines Coupons als Referenz verwendet. Die Vorlagen-ID (IDX) kann im Dashboard eingesehen werden.
onsiteYnstring: Vor-Ort-Coupon. Zeigt die Schaltfläche „Coupon einlösen“ auf der Coupon-Seite an.
Erforderlich, wenn Mitarbeiter in einem Offline-Shop den Coupon einlösen.
onsitePwdstring: Passwort für Vor-Ort-Coupon. Erforderlich bei der Nutzung des Coupons.
memostring: Interne Notiz für Referenzzwecke.
urlstring: Wenn eine URL eingegeben wird, erscheint auf der Coupon-Seite eine Schaltfläche „Zum Einlösen gehen“.
Beim Klicken auf die Schaltfläche oder das Bild wird auf die URL weitergeleitet.
colorstring: Schriftfarbe des Coupons. HEX-Wert eingeben. Beispiel: #4F4F4F
backgroundstring: Hintergrundfarbe des Coupons. HEX-Wert eingeben. Beispiel: #FFFFFF
userIdstring: Wird verwendet, um den Empfänger des Coupons zu verwalten.
Pflichtfeld, wenn die Nutzungsbeschränkung auf 2–5 festgelegt ist. Normalerweise die Login-ID oder der Name des Benutzers.
userNmstring: Name des Coupon-Nutzers. Für interne Verwaltung.
userPhnnostring: Telefonnummer des Coupon-Nutzers. Für interne Verwaltung.
userEmlstring: E-Mail des Coupon-Nutzers. Für interne Verwaltung.
userEtc1string: Zusätzliches internes Verwaltungsfeld.
userEtc2string: Zusätzliches internes Verwaltungsfeld.
branchIdx integer: IDX der ausgebenden Filiale. Ohne Angabe erfolgt die Ausgabe durch die Zentrale; senden Sie 0, um den Wert zu leeren.
Ab dem Business-Tarif verfügbar.
storeIdx integer: IDX des ausgebenden Geschäfts. Bei Angabe wird die Filiale, zu der das Geschäft gehört, zur ausgebenden Filiale. Eine abweichende Filiale führt zu einem Fehler.
useScope string: Nutzungsbereich. Zulässig sind nur ALL (alle Geschäfte) oder BRANCH (eine bestimmte Filiale). Ohne Angabe gilt ALL.
useBranchIdx integer: IDX der Nutzungsfiliale. Nur erforderlich, wenn useScope = BRANCH; bei ALL immer leer.

{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer: Antwortcode: 0 = Erfolg, andere Werte = Fehler
message string: Antwortnachricht. Wenn der Code nicht 0 ist, wird eine Fehlermeldung zurückgegeben.
result null

Ausgebende Filiale, ausgebendes Geschäft und Nutzungsbereich

Die hier angegebenen Werte sind die bei der Ausgabe gespeicherte Richtlinie. "Wo wurde ausgegeben" (ausgebende Filiale, ausgebendes Geschäft) und "wo kann der Kunde es einlösen" (Nutzungsbereich, Nutzungsfiliale) sind unterschiedliche Konzepte, daher sind die Parameter getrennt.

Parameter	Bedeutung	Beschreibung
`branchIdx`	Ausgebende Filiale	Ohne Angabe gibt die Zentrale aus. Senden Sie `0`, um auf die Zentrale zurückzusetzen.
`storeIdx`	Ausgebendes Geschäft	Bei Angabe wird die Filiale des Geschäfts zur ausgebenden Filiale. Eine abweichende Filiale wird abgelehnt.
`useScope`	Nutzungsbereich	`ALL` (alle Geschäfte) oder `BRANCH` (eine Filiale). Standard ist `ALL`.
`useBranchIdx`	Nutzungsfiliale	Nur bei `useScope=BRANCH` erforderlich. Bei `ALL` immer leer.

Nicht verwendbare Parameter — processStoreIdx (verarbeitendes Geschäft) bezeichnet das Geschäft, in dem eine Prüfung, Einlösung, Gutschrift oder Abbuchung tatsächlich stattgefunden hat, und kann in dieser API nicht verwendet werden. Bei Angabe wird mit 400 (Fehlercode 1227) abgelehnt.

Filial- und Geschäftsfunktionen stehen nur ab dem Business-Tarif zur Verfügung.

Idempotency-Key

Um nach einem Netzwerkfehler sicher erneut zu senden, übermitteln Sie im Header Idempotency-Key einen pro Anfrage eindeutigen Wert. Alternativ können Sie ihn als requestId im Body senden; werden beide mit unterschiedlichen Werten gesendet, wird die Anfrage abgelehnt. Zulässig sind 8–64 Zeichen aus Buchstaben, Ziffern und . _ : -.

Wird dieselbe Anfrage mit demselben Key erneut gesendet, wird das ursprüngliche Ergebnis zurückgegeben, ohne erneut zu verarbeiten. Nichts wird doppelt verarbeitet und Webhooks werden nicht erneut gesendet.

Verwenden Sie denselben Key nur für Wiederholungen derselben logischen Operation. Für eine andere Operation verwenden Sie stets einen neuen Key. Derselbe Key mit anderem Anfrageinhalt oder für eine andere Operation kann mit 409 abgelehnt werden.

Wann diese API verwenden

Verwenden Sie diese API, wenn Sie die Bedingungen bereits ausgestellter Gutscheine ändern möchten.

Sie eignet sich zur Verwaltung laufender Kampagnen, z. B. zur Verlängerung von Aktionszeiträumen, zur Anpassung von Rabatten oder zum Hinzufügen von Nutzerbeschränkungen.

Da der Gutscheincode unverändert bleibt, können Sie Bedingungen aktualisieren, ohne bereits verteilte Gutscheine neu auszustellen oder zurückzuziehen.

Ablaufdatum verlängern

Um das Ablaufdatum zu verlängern, setzen Sie einen neuen Wert im Parameter endYmd.
Abgelaufene Gutscheine können durch ein zukünftiges Datum wieder aktiviert werden. Verwenden Sie das Format YYYY-MM-DD.

Anwendungsfälle

Verlängerung von Aktionen: Aktualisieren Sie endYmd, um die Gültigkeit einer Kampagne zu verlängern
Anpassung von Rabatten: Ändern Sie disc entsprechend Ihrer Strategie
Erhöhung der Nutzungslimits: Erhöhen Sie useLimit für VIP-Kunden zur mehrfachen Nutzung
Neuzuweisung von Gruppen: Ändern Sie grpIdx, um den Gutschein in eine andere Gruppe zu verschieben
Zielgruppenspezifische Angebote: Personalisierte Rabatte basierend auf E-Mail oder Benutzer-ID
Änderung der Zielseite: Aktualisieren Sie die Ziel-URL des Gutscheins

Wichtige Hinweise

Wenn cpNo (Gutscheincode) ungültig ist, schlägt die Aktualisierung fehl.
Einige Felder können nach der Nutzung eingeschränkt sein.
Änderungen am Rabatt können die Nutzererfahrung beeinflussen.
Abgelaufene Gutscheine sind möglicherweise nicht sofort wieder nutzbar.
Bei Vor-Ort-Gutscheinen sollte das Passwort bei Personalwechsel aktualisiert werden.

API zur Aktualisierung von Gutscheinen (v2)