Zum Inhalt springen
Doku

Gutscheine

Gutscheine erstellen und ihre Pools mit eindeutigen Codes für E-Mails verwalten.

Basis-URLhttps://api.emailit.com/v2AuthentifizierungFehlerRate Limits

Gutschein erstellen

Erstellt einen Gutschein. Fügen Sie ihn mit {{coupon "key"}} in eine E-Mail ein: Wenn die E-Mail gerendert wird, erhält jeder Empfänger einen Code. Erfordert einen API-Schlüssel mit dem Scope full.

  • Ein Gutschein vom Typ unique enthält einen Pool von Codes zur einmaligen Verwendung. Jedem Empfänger wird der älteste freie Code zugewiesen, einer pro Kampagne oder Automatisierung, und er erhält denselben Code erneut, sobald diese E-Mail wieder für ihn gerendert wird. Laden Sie die Codes Ihres Shops hier oder mit Gutscheincodes hinzufügen hoch, oder generieren Sie Codes in Emailit und importieren Sie sie in Ihren Shop.
  • Ein Gutschein vom Typ static hat einen Code für alle, static_code.

Wenn eine Bestellung einen Code in coupon_codes aufführt, wird der Code als eingelöst markiert. Siehe Produkte, Gutscheine und der Warenkorb.

POST/coupons

Anfrage-Body

keystringErforderlich

Der Name, den Sie in Inhalten verwenden, eindeutig im Workspace. 1 bis 64 Kleinbuchstaben, Ziffern, - oder _, beginnend mit einem Buchstaben oder einer Ziffer. Großbuchstaben werden in Kleinbuchstaben umgewandelt.

namestringErforderlich

Name des Gutscheins, der in der Weboberfläche angezeigt wird, bis zu 191 Zeichen.

descriptionstring | null

Notiz für Ihr Team. Längerer Text wird auf 1.000 Zeichen gekürzt.

kindstring

unique (Standardwert) oder static.

static_codestring | null

Bis zu 191 Zeichen. Erforderlich bei einem statischen Gutschein: der Code, den alle erhalten. Bei einem Gutschein vom Typ unique der Text, den Empfänger erhalten, wenn der Pool leer oder der Gutschein abgelaufen ist. Ohne ihn erhalten sie einen leeren String.

discount_labelstring | null

Kurze Beschreibung des Rabatts, etwa 10% off. Längerer Text wird auf 191 Zeichen gekürzt.

expires_atstring | null

Datum mit Uhrzeit im Format ISO 8601. Danach erhalten Empfänger eines Gutscheins vom Typ unique static_code statt eines Codes, auch in erneut gerenderten E-Mails. Emailit setzt den Ablauf nicht in Ihrem Shop durch.

codesstring[] | string

Codes, die dem Pool hinzugefügt werden: ein Array oder Text mit einem Code pro Zeile. Bei CSV-Text wird die erste Spalte gelesen und eine Kopfzeile wie code oder coupon_code übersprungen. Ein Code besteht aus 2 bis 64 Buchstaben, Ziffern, -, _ oder . und beginnt mit einem Buchstaben oder einer Ziffer. Ungültige Codes werden ausgelassen, Duplikate einmal hinzugefügt. Bis zu 10.000 Codes.

Rückgabe

201 Created mit dem Gutschein-Objekt. Gibt 422 zurück, wenn ein Feld ungültig ist oder ein anderer Gutschein den Schlüssel bereits hat.

POST/coupons
Terminal
curl -X POST https://api.emailit.com/v2/coupons \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "welcome-10",
    "name": "Welcome 10% off",
    "description": "First-order discount for new subscribers.",
    "kind": "unique",
    "static_code": "WELCOME10",
    "discount_label": "10% off",
    "expires_at": "2026-12-31T23:59:59Z",
    "codes": ["WELCOME-7KQ2M9XA", "WELCOME-H4TZ8RCN", "WELCOME-P2WD6YFE"]
  }'
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "codes_total": 3,
  "codes_available": 3,
  "codes_assigned": 0,
  "codes_redeemed": 0,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-01T09:00:12.304Z"
}

Gutschein abrufen

Ruft einen Gutschein über seine ID oder seinen Schlüssel ab, mit der Anzahl seiner Codes. Erfordert einen API-Schlüssel mit dem Scope full.

GET/coupons/{id}

Pfadparameter

idstringErforderlich

Die Gutschein-ID (cpn_...) oder der key des Gutscheins.

Das Gutschein-Objekt

objectstring

Immer coupon.

idstring

Gutschein-ID (cpn_...).

keystring

Der Name, den Sie in E-Mail-Inhalten verwenden: {{coupon "welcome-10"}}. Siehe Produkte, Gutscheine und der Warenkorb.

namestring

Name des Gutscheins, der in der Weboberfläche angezeigt wird.

descriptionstring | null

Notiz für Ihr Team.

kindstring

  • unique: ein Pool von Codes zur einmaligen Verwendung. Jeder Empfänger erhält einen eigenen Code, einen pro Kampagne oder Automatisierung, und denselben Code erneut, wenn die E-Mail erneut gerendert wird.

  • static: ein Code für alle, static_code.

static_codestring | null

Der gemeinsame Code eines statischen Gutscheins. Bei einem Gutschein vom Typ unique der Text, den Empfänger erhalten, wenn kein Code mehr übrig oder der Gutschein abgelaufen ist. Ohne ihn erhalten sie einen leeren String.

discount_labelstring | null

Kurze Beschreibung des Rabatts, etwa 10% off.

expires_atstring | null

Nach diesem Zeitpunkt erhalten Empfänger eines Gutscheins vom Typ unique static_code statt eines Codes.

codes_totalinteger

Codes im Pool.

codes_availableinteger

Codes, die noch vergeben werden können: keinem Kontakt zugewiesen und in keiner Bestellung verwendet.

codes_assignedinteger

Einem Kontakt zugewiesene Codes, einschließlich der bereits eingelösten.

codes_redeemedinteger

In einer Bestellung verwendete Codes (coupon_codes).

created_at, updated_atstring

Zeitpunkt der Erstellung und der letzten Änderung des Gutscheins, im Format ISO 8601 in UTC.

GET/coupons/{id}
Terminal
curl https://api.emailit.com/v2/coupons/welcome-10 \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "codes_total": 5000,
  "codes_available": 3812,
  "codes_assigned": 1188,
  "codes_redeemed": 143,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-01T09:00:12.304Z"
}

Gutschein aktualisieren

Aktualisiert einen Gutschein. Nur die Felder, die Sie senden, ändern sich. Um Codes hinzuzufügen, verwenden Sie Gutscheincodes hinzufügen: codes wird in dieser Anfrage ignoriert. Erfordert einen API-Schlüssel mit dem Scope full.

Wenn Sie den key ändern, aktualisieren Sie auch die Platzhalter {{coupon "key"}} in Ihren E-Mails: Emailit findet Gutscheine über den Schlüssel im Inhalt.

POST/coupons/{id}

Pfadparameter

idstringErforderlich

Die Gutschein-ID (cpn_...) oder der aktuelle key des Gutscheins.

Anfrage-Body

Beliebige der Felder key, name, description, kind, static_code, discount_label und expires_at, mit den Regeln von Gutschein erstellen. Senden Sie null für description, static_code, discount_label oder expires_at, um den Wert zu löschen. Ein Gutschein, der static ist oder wird, muss einen static_code behalten.

Rückgabe

200 OK mit dem aktualisierten Gutschein-Objekt. Gibt 404 zurück, wenn kein Gutschein zu id passt, und 422, wenn ein Feld ungültig ist oder der neue Schlüssel bereits vergeben ist.

POST/coupons/{id}
Terminal
curl -X POST https://api.emailit.com/v2/coupons/welcome-10 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2027-01-31T23:59:59Z" }'
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2027-01-31T23:59:59.000Z",
  "codes_total": 5000,
  "codes_available": 3812,
  "codes_assigned": 1188,
  "codes_redeemed": 143,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-09T15:47:20.061Z"
}

Gutscheine auflisten

Listet die Gutscheine Ihres Workspaces auf, neueste zuerst, mit der Anzahl ihrer Codes. Erfordert einen API-Schlüssel mit dem Scope full.

GET/coupons

Query-Parameter

pageinteger

Seitennummer für die Paginierung (Minimum: 1, Standardwert: 1).

limitinteger

Anzahl der zurückgegebenen Gutscheine (Minimum: 1, Maximum: 100, Standardwert: 25).

searchstring

Abgleich mit dem Namen oder Schlüssel des Gutscheins, ohne Beachtung der Groß-/Kleinschreibung.

matchstring

all (Standardwert) verlangt, dass alle Filter zutreffen. or trifft zu, wenn ein beliebiger Filter passt. Siehe Filtern und Sortieren.

orderstring

Sortierschlüssel für diese Liste. Siehe die Sortierschlüssel unten.

directionstring

asc oder desc.

Filter und Sortierung

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

SchlüsselTypBedingungenHinweise
keystringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
kindenumexact, not_exactWerte: unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Sortierschlüssel

Übergeben Sie in order einen dieser Schlüssel und in direction den Wert asc oder desc: key, name, kind, expires_at, created_at

Rückgabe

Eine Seite mit Gutschein-Objekten in data, dazu total_records, next_page_url und previous_page_url. Die Seiten-URLs enthalten nur page und limit; fügen Sie Ihre Suche und Filter daher erneut hinzu, wenn Sie ihnen folgen.

GET/coupons
Terminal
curl "https://api.emailit.com/v2/coupons?kind.exact=unique" \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "object": "coupon",
      "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
      "key": "welcome-10",
      "name": "Welcome 10% off",
      "description": "First-order discount for new subscribers.",
      "kind": "unique",
      "static_code": "WELCOME10",
      "discount_label": "10% off",
      "expires_at": "2026-12-31T23:59:59.000Z",
      "codes_total": 5000,
      "codes_available": 3812,
      "codes_assigned": 1188,
      "codes_redeemed": 143,
      "created_at": "2026-10-01T09:00:12.304Z",
      "updated_at": "2026-10-01T09:00:12.304Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Gutschein löschen

Löscht einen Gutschein zusammen mit allen seinen Codes, einschließlich zugewiesener und eingelöster. Bestellungen behalten die Codes in ihren coupon_codes. Erfordert einen API-Schlüssel mit dem Scope full.

DELETE/coupons/{id}

Pfadparameter

idstringErforderlich

Die Gutschein-ID (cpn_...) oder der key des Gutscheins.

DELETE/coupons/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "deleted": true
}

Gutscheincodes auflisten

Listet die Codes eines Gutscheins auf, älteste zuerst: die Reihenfolge, in der sie vergeben werden. Mit format=csv exportieren Sie sie, zum Beispiel um generierte Codes in Ihren Shop zu importieren. Erfordert einen API-Schlüssel mit dem Scope full.

GET/coupons/{id}/codes

Pfadparameter

idstringErforderlich

Die Gutschein-ID (cpn_...) oder der key des Gutscheins.

Query-Parameter

pageinteger

Seitennummer für die Paginierung (Minimum: 1, Standardwert: 1).

limitinteger

Anzahl der zurückgegebenen Codes (Minimum: 1, Maximum: 100, Standardwert: 50).

statusstring

  • available: keinem Kontakt zugewiesen und in keiner Bestellung verwendet, kann also noch vergeben werden.

  • assigned: einem Kontakt zugewiesen und nicht eingelöst.

  • redeemed: in einer Bestellung verwendet.

formatstring

json (Standardwert) oder csv. CSV gibt alle Codes, die zu status passen, in einer Datei ohne Paginierung zurück, mit den Spalten code, status, email, assigned_at und redeemed_at. Filter der Form key.condition und die Sortierung gelten nicht für die CSV-Datei.

matchstring

all (Standardwert) verlangt, dass alle Filter zutreffen. or trifft zu, wenn ein beliebiger Filter passt. Siehe Filtern und Sortieren.

orderstring

Sortierschlüssel für diese Liste. Siehe die Sortierschlüssel unten.

directionstring

asc oder desc.

Filter und Sortierung

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

SchlüsselTypBedingungenHinweise
codestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
assigned_atdateexact, before, after, empty, not_empty
redeemed_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Sortierschlüssel

Übergeben Sie in order einen dieser Schlüssel und in direction den Wert asc oder desc: code, email, assigned_at, redeemed_at, created_at

Rückgabe

Eine Seite mit Gutscheincodes in data, dazu total_records, next_page_url und previous_page_url. Jeder Code hat:

objectstring

Immer coupon_code.

idstring

Code-ID (cpc_...).

codestring

Der Code.

contact_id, emailstring | null

Der Kontakt, dem der Code zugewiesen ist, oder null.

source_idstring | null

Die Kampagne (cmp_...) oder Automatisierung (aut_...), deren E-Mail den Code erhalten hat.

assigned_atstring | null

Zeitpunkt, zu dem der Code zugewiesen wurde.

redeemed_at, redeemed_order_idstring | null

Zeitpunkt, zu dem der Code eingelöst wurde, und von welcher Bestellung (ord_...).

created_atstring

Zeitpunkt, zu dem der Code dem Pool hinzugefügt wurde.

GET/coupons/{id}/codes
Terminal
curl "https://api.emailit.com/v2/coupons/welcome-10/codes?status=assigned&limit=2" \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "object": "coupon_code",
      "id": "cpc_3s6oCjlRbLFujYObEAcuiZmGKqu",
      "code": "WELCOME-H4TZ8RCN",
      "contact_id": "con_3MjLVacsYA6keJucAbOs3o3XhyA",
      "email": "grace@example.com",
      "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "assigned_at": "2026-10-08T09:00:41.773Z",
      "redeemed_at": null,
      "redeemed_order_id": null,
      "created_at": "2026-10-01T09:00:12.304Z"
    },
    {
      "object": "coupon_code",
      "id": "cpc_3u9TrZTopqOgaqT9FcZFareUFGj",
      "code": "WELCOME-P2WD6YFE",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "assigned_at": "2026-10-08T09:00:41.802Z",
      "redeemed_at": null,
      "redeemed_order_id": null,
      "created_at": "2026-10-01T09:00:12.304Z"
    }
  ],
  "total_records": 1045,
  "next_page_url": "/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ/codes?page=2&limit=2",
  "previous_page_url": null
}

Gutscheincodes hinzufügen

Fügt dem Pool eines Gutscheins vom Typ unique Codes hinzu. Laden Sie entweder mit codes Codes hoch, die in Ihrem Shop existieren, oder lassen Sie Emailit mit generate zufällige Codes erstellen und importieren Sie sie dann mit Gutscheincodes auflisten (format=csv) in Ihren Shop. Codes, die bereits im Pool sind, werden übersprungen. Statische Gutscheine haben einen einzigen Code und geben 422 zurück. Erfordert einen API-Schlüssel mit dem Scope full.

POST/coupons/{id}/codes

Pfadparameter

idstringErforderlich

Die Gutschein-ID (cpn_...) oder der key des Gutscheins.

Anfrage-Body

Senden Sie codes oder generate. Wenn Sie beides senden, wird generate verwendet.

codesstring[] | string

Bis zu 10.000 Codes: ein Array oder Text mit einem Code pro Zeile. Bei CSV-Text wird die erste Spalte gelesen und eine Kopfzeile wie code oder coupon_code übersprungen. Ein Code besteht aus 2 bis 64 Buchstaben, Ziffern, -, _ oder . und beginnt mit einem Buchstaben oder einer Ziffer. Codes, die nicht passen, werden in invalid zurückgegeben.

generateobject

Erstellt zufällige Codes aus Großbuchstaben und Ziffern, ohne die leicht verwechselbaren Zeichen 0, O, 1 und I.

  • count (integer, erforderlich): 1 bis 10.000 Codes.

  • prefix (string): bis zu 20 Buchstaben, Ziffern, - oder _, die jedem Code vorangestellt werden. Zum Beispiel WELCOME-.

  • length (integer): zufällige Zeichen nach dem Präfix, von 4 bis 32. Standardwert 8. Werte außerhalb des Bereichs werden auf die Grenzen gesetzt.

Rückgabe

addedinteger

Dem Pool hinzugefügte Codes.

skippedinteger

Codes, die bereits im Pool waren.

invalidstring[]

Hochgeladene Werte, die keine gültigen Codes sind und nicht hinzugefügt wurden.

couponobject

Das Gutschein-Objekt mit den neuen Zahlen.

Gibt 404 zurück, wenn kein Gutschein zu id passt, und 422 bei einem statischen Gutschein, wenn kein gültiger Code gesendet wurde, wenn mehr als 10.000 Codes gesendet wurden oder wenn generate.count oder generate.prefix außerhalb des zulässigen Bereichs liegt.

POST/coupons/{id}/codes
Terminal
curl -X POST https://api.emailit.com/v2/coupons/welcome-10/codes \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "generate": { "count": 5000, "prefix": "WELCOME-", "length": 8 } }'
JSON
{
  "added": 5000,
  "skipped": 0,
  "invalid": [],
  "coupon": {
    "object": "coupon",
    "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
    "key": "welcome-10",
    "name": "Welcome 10% off",
    "description": "First-order discount for new subscribers.",
    "kind": "unique",
    "static_code": "WELCOME10",
    "discount_label": "10% off",
    "expires_at": "2026-12-31T23:59:59.000Z",
    "codes_total": 5003,
    "codes_available": 5003,
    "codes_assigned": 0,
    "codes_redeemed": 0,
    "created_at": "2026-10-01T09:00:12.304Z",
    "updated_at": "2026-10-01T09:00:12.304Z"
  }
}

War diese Seite hilfreich?

Danke für Ihr Feedback.

Danke, wir lesen jede Nachricht.

Esc

Beliebt

↑↓zum Navigieren↵zum ÖffnenEsczum Schließen