Přejít na obsah
Dokumentace

Kupony

Vytvářejte kupony a spravujte jejich zásoby jedinečných kódů pro e-maily.

Základní URLhttps://api.emailit.com/v2AutentizaceChybyLimity rychlosti

Vytvoření kuponu

Vytvoří kupon. Do e-mailu ho vložíte pomocí {{coupon "key"}}: když se e-mail vykreslí, každý příjemce dostane kód. Vyžaduje API klíč s oprávněním full.

  • Kupon typu unique obsahuje zásobu jednorázových kódů. Každému příjemci se přidělí nejstarší volný kód, jeden pro každou kampaň nebo automatizaci, a stejný kód dostane znovu pokaždé, když se mu tento e-mail vykreslí. Kódy ze svého obchodu nahrajte tady nebo endpointem Přidání kódů ke kuponu, nebo kódy vygenerujte v Emailitu a naimportujte je do svého obchodu.
  • Kupon typu static má jeden kód, static_code, pro všechny.

Když objednávka uvede kód v coupon_codes, kód se označí jako uplatněný. Viz Produkty, kupony a košík.

POST/coupons

Tělo požadavku

keystringPovinné

Název, který používáte v obsahu, jedinečný ve workspace. 1 až 64 malých písmen, číslic, - nebo _, na začátku písmeno nebo číslice. Velká písmena se převedou na malá.

namestringPovinné

Název kuponu zobrazovaný ve webovém rozhraní, nejvýše 191 znaků.

descriptionstring | null

Poznámka pro váš tým. Delší text se zkrátí na 1 000 znaků.

kindstring

unique (výchozí hodnota), nebo static.

static_codestring | null

Nejvýše 191 znaků. Povinné u kuponu typu static: kód, který dostanou všichni. U kuponu typu unique text, který příjemci dostanou, když je zásoba prázdná nebo kupon vypršel. Bez něj dostanou prázdný řetězec.

discount_labelstring | null

Krátký popis slevy, například 10% off. Delší text se zkrátí na 191 znaků.

expires_atstring | null

Datum a čas ve formátu ISO 8601. Po něm dostanou příjemci kuponu typu unique místo kódu static_code, a to i v e-mailech vykreslených znovu. Emailit platnost ve vašem obchodě nevynucuje.

codesstring[] | string

Kódy, které se přidají do zásoby: pole, nebo text s jedním kódem na řádek. U textu ve formátu CSV se čte první sloupec a záhlaví jako code nebo coupon_code se přeskočí. Kód má 2 až 64 písmen, číslic, -, _ nebo . a začíná písmenem nebo číslicí. Neplatné kódy se vynechají a duplicity se přidají jednou. Až 10 000 kódů.

Odpověď

201 Created s objektem kuponu. Pokud je některé pole neplatné nebo stejný klíč už má jiný kupon, vrací 422.

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

Načtení kuponu

Načte kupon podle jeho ID nebo klíče s počty jeho kódů. Vyžaduje API klíč s oprávněním full.

GET/coupons/{id}

Parametry v cestě

idstringPovinné

ID kuponu (cpn_...), nebo key kuponu.

Objekt kuponu

objectstring

Vždy coupon.

idstring

ID kuponu (cpn_...).

keystring

Název, který používáte v obsahu e-mailu: {{coupon "welcome-10"}}. Viz Produkty, kupony a košík.

namestring

Název kuponu zobrazovaný ve webovém rozhraní.

descriptionstring | null

Poznámka pro váš tým.

kindstring

  • unique: zásoba jednorázových kódů. Každý příjemce dostane vlastní kód, jeden pro každou kampaň nebo automatizaci, a když se mu e-mail vykreslí znovu, dostane stejný kód.

  • static: jeden kód, static_code, pro všechny.

static_codestring | null

Sdílený kód kuponu typu static. U kuponu typu unique text, který příjemci dostanou, když už nezbývá žádný kód nebo kupon vypršel. Bez něj dostanou prázdný řetězec.

discount_labelstring | null

Krátký popis slevy, například 10% off.

expires_atstring | null

Po tomto čase dostanou příjemci kuponu typu unique místo kódu static_code.

codes_totalinteger

Kódy v zásobě.

codes_availableinteger

Kódy, které lze ještě rozdat: nejsou přidělené žádnému kontaktu ani použité v objednávce.

codes_assignedinteger

Kódy přidělené kontaktu, včetně těch, které už byly uplatněny.

codes_redeemedinteger

Kódy použité v objednávce (coupon_codes).

created_at, updated_atstring

Kdy byl kupon vytvořen a kdy se naposledy změnil, ve formátu ISO 8601 v 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"
}

Úprava kuponu

Upraví kupon. Změní se jen pole, která pošlete. Kódy přidáte endpointem Přidání kódů ke kuponu: codes se v tomto požadavku ignoruje. Vyžaduje API klíč s oprávněním full.

Pokud změníte key, upravte i značky {{coupon "key"}} ve svých e-mailech: Emailit kupony dohledává podle klíče v obsahu.

POST/coupons/{id}

Parametry v cestě

idstringPovinné

ID kuponu (cpn_...), nebo aktuální key kuponu.

Tělo požadavku

Kterékoli z polí key, name, description, kind, static_code, discount_label a expires_at s pravidly endpointu Vytvoření kuponu. Pokud chcete description, static_code, discount_label nebo expires_at vymazat, pošlete null. Kupon, který je typu static nebo se jím stane, musí mít static_code.

Odpověď

200 OK s upraveným objektem kuponu. Pokud parametru id neodpovídá žádný kupon, vrací 404, a pokud je některé pole neplatné nebo je nový klíč už obsazený, vrací 422.

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

Výpis kuponů

Vypíše kupony ve vašem workspace, nejnovější jako první, s počty jejich kódů. Vyžaduje API klíč s oprávněním full.

GET/coupons

Parametry dotazu

pageinteger

Číslo stránky pro stránkování (nejméně 1, výchozí hodnota 1).

limitinteger

Počet kuponů, které se vrátí (nejméně 1, nejvýše 100, výchozí hodnota 25).

searchstring

Hledá v názvu nebo klíči kuponu bez ohledu na velikost písmen.

matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

Filtry a řazení

Filtry výpisů jsou jedna úroveň parametrů dotazu ve tvaru key.condition=value. Parametry match, order a direction a seznam podmínek pro každý typ najdete na stránce Filtrování.

Klíče filtrů

KlíčTypPodmínkyPoznámky
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_exactHodnoty: unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: key, name, kind, expires_at, created_at

Odpověď

Stránka objektů kuponů v poli data a k tomu total_records, next_page_url a previous_page_url. URL stránek nesou jen page a limit, takže když na ně přejdete, přidejte znovu své vyhledávání a filtry.

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
}

Smazání kuponu

Smaže kupon spolu se všemi jeho kódy, včetně přidělených a uplatněných. Objednávky si kódy ve svém coupon_codes ponechají. Vyžaduje API klíč s oprávněním full.

DELETE/coupons/{id}

Parametry v cestě

idstringPovinné

ID kuponu (cpn_...), nebo key kuponu.

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
}

Výpis kódů kuponu

Vypíše kódy kuponu, nejstarší jako první: v pořadí, v jakém se rozdávají. Pomocí format=csv je vyexportujete, například abyste vygenerované kódy naimportovali do svého obchodu. Vyžaduje API klíč s oprávněním full.

GET/coupons/{id}/codes

Parametry v cestě

idstringPovinné

ID kuponu (cpn_...), nebo key kuponu.

Parametry dotazu

pageinteger

Číslo stránky pro stránkování (nejméně 1, výchozí hodnota 1).

limitinteger

Počet kódů, které se vrátí (nejméně 1, nejvýše 100, výchozí hodnota 50).

statusstring

  • available: kód není přidělený žádnému kontaktu ani použitý v objednávce, takže ho lze ještě rozdat.

  • assigned: kód je přidělený kontaktu a není uplatněný.

  • redeemed: kód byl použit v objednávce.

formatstring

json (výchozí hodnota), nebo csv. CSV vrátí všechny kódy odpovídající status v jednom souboru, bez stránkování, se sloupci code, status, email, assigned_at a redeemed_at. Filtry key.condition a řazení se na CSV nevztahují.

matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

Filtry a řazení

Filtry výpisů jsou jedna úroveň parametrů dotazu ve tvaru key.condition=value. Parametry match, order a direction a seznam podmínek pro každý typ najdete na stránce Filtrování.

Klíče filtrů

KlíčTypPodmínkyPoznámky
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

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: code, email, assigned_at, redeemed_at, created_at

Odpověď

Stránka kódů kuponu v poli data a k tomu total_records, next_page_url a previous_page_url. Každý kód má:

objectstring

Vždy coupon_code.

idstring

ID kódu (cpc_...).

codestring

Samotný kód.

contact_id, emailstring | null

Kontakt, kterému je kód přidělený, nebo null.

source_idstring | null

Kampaň (cmp_...) nebo automatizace (aut_...), jejíž e-mail kód dostal.

assigned_atstring | null

Kdy byl kód přidělen.

redeemed_at, redeemed_order_idstring | null

Kdy byl kód uplatněn a kterou objednávkou (ord_...).

created_atstring

Kdy byl kód přidán do zásoby.

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
}

Přidání kódů ke kuponu

Přidá kódy do zásoby kuponu typu unique. Buď nahrajte kódy, které existují ve vašem obchodě, pomocí codes, nebo nechte Emailit vytvořit náhodné kódy pomocí generate a pak je naimportujte do svého obchodu přes Výpis kódů kuponu (format=csv). Kódy, které už v zásobě jsou, se přeskočí. Kupony typu static mají jeden kód a vracejí 422. Vyžaduje API klíč s oprávněním full.

POST/coupons/{id}/codes

Parametry v cestě

idstringPovinné

ID kuponu (cpn_...), nebo key kuponu.

Tělo požadavku

Pošlete codes, nebo generate. Když pošlete obojí, použije se generate.

codesstring[] | string

Až 10 000 kódů: pole, nebo text s jedním kódem na řádek. U textu ve formátu CSV se čte první sloupec a záhlaví jako code nebo coupon_code se přeskočí. Kód má 2 až 64 písmen, číslic, -, _ nebo . a začíná písmenem nebo číslicí. Kódy, které tomu neodpovídají, se vrátí v invalid.

generateobject

Vytvoří náhodné kódy z velkých písmen a číslic, bez snadno zaměnitelných znaků 0, O, 1 a I.

  • count (integer, povinné): 1 až 10 000 kódů.

  • prefix (string): nejvýše 20 písmen, číslic, - nebo _, které se vloží před každý kód. Například WELCOME-.

  • length (integer): počet náhodných znaků za předponou, od 4 do 32. Výchozí hodnota je 8. Hodnoty mimo tento rozsah se upraví na nejbližší povolenou hodnotu.

Odpověď

addedinteger

Kódy přidané do zásoby.

skippedinteger

Kódy, které už v zásobě byly.

invalidstring[]

Nahrané hodnoty, které nejsou platnými kódy a nepřidaly se.

couponobject

Objekt kuponu s novými počty.

Pokud parametru id neodpovídá žádný kupon, vrací 404. 422 vrací u kuponu typu static, když nebyl odeslán žádný platný kód, když bylo odesláno víc než 10 000 kódů, nebo když je generate.count nebo generate.prefix mimo povolený rozsah.

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

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.

Esc

Oblíbené

↑↓procházet↵otevřítEsczavřít