Vai al contenuto
Docs

Coupon

Crea coupon e gestisci i loro pool di codici unici per le email.

URL di basehttps://api.emailit.com/v2AutenticazioneErroriLimiti di frequenza

Crea un coupon

Crea un coupon. Inseriscilo in un’email con {{coupon "key"}}: quando l’email viene elaborata, ogni destinatario riceve un codice. Richiede una chiave API con il permesso full.

  • Un coupon unique contiene un pool di codici monouso. A ogni destinatario viene assegnato il codice libero più vecchio, uno per campagna o automazione, e riceve di nuovo lo stesso codice ogni volta che quell’email viene elaborata per lui. Carica qui i codici del tuo negozio o con Aggiungi codici a un coupon, oppure genera i codici in Emailit e importali nel negozio.
  • Un coupon static ha un solo codice per tutti, static_code.

Quando un ordine elenca un codice in coupon_codes, il codice viene contrassegnato come utilizzato. Vedi Prodotti, coupon e carrello.

POST/coupons

Corpo della richiesta

keystringObbligatorio

Il nome che usi nel contenuto, univoco nel workspace. Da 1 a 64 lettere minuscole, cifre, - o _, che inizia con una lettera o una cifra. Le maiuscole vengono convertite in minuscole.

namestringObbligatorio

Nome del coupon mostrato nel pannello, fino a 191 caratteri.

descriptionstring | null

Nota per il tuo team. Il testo più lungo viene troncato a 1000 caratteri.

kindstring

unique (predefinito) o static.

static_codestring | null

Fino a 191 caratteri. Obbligatorio per un coupon static: il codice che ricevono tutti. Per un coupon unique, il testo che ricevono i destinatari quando il pool è vuoto o il coupon è scaduto. Senza, ricevono una stringa vuota.

discount_labelstring | null

Breve descrizione dello sconto, come 10% off. Il testo più lungo viene troncato a 191 caratteri.

expires_atstring | null

Data e ora ISO 8601. Dopo questo momento, i destinatari di un coupon unique ricevono static_code invece di un codice, anche nelle email elaborate di nuovo. Emailit non applica la scadenza nel tuo negozio.

codesstring[] | string

Codici da aggiungere al pool: un array, oppure un testo con un codice per riga. Per un testo CSV viene letta la prima colonna e un’intestazione come code o coupon_code viene saltata. Un codice è composto da 2 a 64 lettere, cifre, -, _ o ., e inizia con una lettera o una cifra. I codici non validi vengono esclusi e i duplicati vengono aggiunti una sola volta. Fino a 10.000 codici.

Restituisce

201 Created con l’oggetto coupon. Restituisce 422 quando un campo non è valido o un altro coupon ha già la chiave.

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

Recupera un coupon

Recupera un coupon tramite il suo ID o la sua chiave, con il conteggio dei suoi codici. Richiede una chiave API con il permesso full.

GET/coupons/{id}

Parametri di percorso

idstringObbligatorio

L’ID del coupon (cpn_...) o la key del coupon.

L’oggetto coupon

objectstring

Sempre coupon.

idstring

ID del coupon (cpn_...).

keystring

Il nome che usi nel contenuto delle email: {{coupon "welcome-10"}}. Vedi Prodotti, coupon e carrello.

namestring

Nome del coupon mostrato nel pannello.

descriptionstring | null

Nota per il tuo team.

kindstring

  • unique: un pool di codici monouso. Ogni destinatario riceve il proprio codice, uno per campagna o automazione, e di nuovo lo stesso codice quando l’email viene elaborata di nuovo.

  • static: un solo codice per tutti, static_code.

static_codestring | null

Il codice condiviso di un coupon static. Per un coupon unique, il testo che ricevono i destinatari quando non resta nessun codice o il coupon è scaduto. Senza, ricevono una stringa vuota.

discount_labelstring | null

Breve descrizione dello sconto, come 10% off.

expires_atstring | null

Dopo questo momento, i destinatari di un coupon unique ricevono static_code invece di un codice.

codes_totalinteger

Codici nel pool.

codes_availableinteger

Codici che si possono ancora distribuire: non assegnati a un contatto e non usati in un ordine.

codes_assignedinteger

Codici assegnati a un contatto, compresi quelli già utilizzati.

codes_redeemedinteger

Codici usati in un ordine (coupon_codes).

created_at, updated_atstring

Quando il coupon è stato creato e quando è cambiato l’ultima volta, in ISO 8601 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"
}

Aggiorna un coupon

Aggiorna un coupon. Cambiano solo i campi che invii. Per aggiungere codici usa Aggiungi codici a un coupon: codes in questa richiesta viene ignorato. Richiede una chiave API con il permesso full.

Se cambi la key, aggiorna anche i tag {{coupon "key"}} nelle tue email: Emailit cerca i coupon in base alla chiave presente nel contenuto.

POST/coupons/{id}

Parametri di percorso

idstringObbligatorio

L’ID del coupon (cpn_...) o la key attuale del coupon.

Corpo della richiesta

Uno qualsiasi tra key, name, description, kind, static_code, discount_label ed expires_at, con le regole di Crea un coupon. Invia null per description, static_code, discount_label o expires_at per svuotare il campo. Un coupon che è o diventa static deve mantenere uno static_code.

Restituisce

200 OK con l’oggetto coupon aggiornato. Restituisce 404 se nessun coupon corrisponde a id e 422 quando un campo non è valido o la nuova chiave è già in uso.

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

Elenca i coupon

Elenca i coupon del workspace, a partire dal più recente, con il conteggio dei loro codici. Richiede una chiave API con il permesso full.

GET/coupons

Parametri di query

pageinteger

Numero di pagina per la paginazione (minimo: 1, predefinito: 1).

limitinteger

Numero di coupon da restituire (minimo: 1, massimo: 100, predefinito: 25).

searchstring

Corrispondenza sul nome o sulla chiave del coupon, senza distinzione tra maiuscole e minuscole.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

Filtri e ordinamento

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

ChiaveTipoCondizioniNote
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_exactValori: unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Chiavi di ordinamento

Passa in order una di queste chiavi e in direction il valore asc o desc: key, name, kind, expires_at, created_at

Restituisce

Una pagina di oggetti coupon in data, con total_records, next_page_url e previous_page_url. Gli URL delle pagine riportano solo page e limit, quindi aggiungi di nuovo la ricerca e i filtri quando li segui.

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
}

Elimina un coupon

Elimina un coupon insieme a tutti i suoi codici, compresi quelli assegnati e utilizzati. Gli ordini mantengono i codici nel loro coupon_codes. Richiede una chiave API con il permesso full.

DELETE/coupons/{id}

Parametri di percorso

idstringObbligatorio

L’ID del coupon (cpn_...) o la key del coupon.

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
}

Elenca i codici di un coupon

Elenca i codici di un coupon, a partire dal meno recente: l’ordine in cui vengono distribuiti. Usa format=csv per esportarli, ad esempio per importare nel negozio i codici generati. Richiede una chiave API con il permesso full.

GET/coupons/{id}/codes

Parametri di percorso

idstringObbligatorio

L’ID del coupon (cpn_...) o la key del coupon.

Parametri di query

pageinteger

Numero di pagina per la paginazione (minimo: 1, predefinito: 1).

limitinteger

Numero di codici da restituire (minimo: 1, massimo: 100, predefinito: 50).

statusstring

  • available: non assegnato a un contatto e non usato in un ordine, quindi si può ancora distribuire.

  • assigned: assegnato a un contatto e non utilizzato.

  • redeemed: usato in un ordine.

formatstring

json (predefinito) o csv. Il CSV restituisce in un unico file tutti i codici che corrispondono a status, senza paginazione, con le colonne code, status, email, assigned_at e redeemed_at. I filtri key.condition e l’ordinamento non si applicano al CSV.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

Filtri e ordinamento

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

ChiaveTipoCondizioniNote
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

Chiavi di ordinamento

Passa in order una di queste chiavi e in direction il valore asc o desc: code, email, assigned_at, redeemed_at, created_at

Restituisce

Una pagina di codici coupon in data, con total_records, next_page_url e previous_page_url. Ogni codice ha:

objectstring

Sempre coupon_code.

idstring

ID del codice (cpc_...).

codestring

Il codice.

contact_id, emailstring | null

Il contatto a cui è assegnato il codice, oppure null.

source_idstring | null

La campagna (cmp_...) o l’automazione (aut_...) la cui email ha ricevuto il codice.

assigned_atstring | null

Quando è stato assegnato il codice.

redeemed_at, redeemed_order_idstring | null

Quando è stato utilizzato il codice e da quale ordine (ord_...).

created_atstring

Quando il codice è stato aggiunto al pool.

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
}

Aggiungi codici a un coupon

Aggiungi codici al pool di un coupon a codici unici. Puoi caricare con codes i codici che esistono nel tuo negozio, oppure lasciare che Emailit crei codici casuali con generate e poi importarli nel negozio con Elenca i codici di un coupon (format=csv). I codici già presenti nel pool vengono saltati. I coupon static hanno un solo codice e restituiscono 422. Richiede una chiave API con il permesso full.

POST/coupons/{id}/codes

Parametri di percorso

idstringObbligatorio

L’ID del coupon (cpn_...) o la key del coupon.

Corpo della richiesta

Invia codes o generate. Se li invii entrambi, viene usato generate.

codesstring[] | string

Fino a 10.000 codici: un array, oppure un testo con un codice per riga. Per un testo CSV viene letta la prima colonna e un’intestazione come code o coupon_code viene saltata. Un codice è composto da 2 a 64 lettere, cifre, -, _ o ., e inizia con una lettera o una cifra. I codici che non rispettano queste regole vengono restituiti in invalid.

generateobject

Crea codici casuali con lettere maiuscole e cifre, senza 0, O, 1 e I, che si confondono facilmente.

  • count (integer, obbligatorio): da 1 a 10.000 codici.

  • prefix (string): fino a 20 lettere, cifre, - o _, inserito davanti a ogni codice. Ad esempio WELCOME-.

  • length (integer): caratteri casuali dopo il prefisso, da 4 a 32. Il valore predefinito è 8. I valori fuori dall’intervallo vengono riportati al limite più vicino.

Restituisce

addedinteger

Codici aggiunti al pool.

skippedinteger

Codici che erano già nel pool.

invalidstring[]

Valori caricati che non sono codici validi e non sono stati aggiunti.

couponobject

L’oggetto coupon con i nuovi conteggi.

Restituisce 404 se nessun coupon corrisponde a id, e 422 per un coupon static, quando non è stato inviato nessun codice valido, quando sono stati inviati più di 10.000 codici o quando generate.count o generate.prefix è fuori dall’intervallo.

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

Questa pagina ti è stata utile?

Grazie del feedback.

Grazie, leggiamo ogni messaggio.

Esc

Popolari

↑↓per spostarti↵per aprireEscper chiudere