Pular para o conteúdo
Docs

Cupons

Crie cupons e gerencie os pools de códigos únicos deles para os seus e-mails.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

Criar um cupom

Cria um cupom. Coloque-o em um e-mail com {{coupon "key"}}: quando o e-mail é renderizado, cada destinatário recebe um código. Requer uma chave de API com escopo full.

  • Um cupom unique tem um pool de códigos de uso único. Cada destinatário recebe o código livre mais antigo, um por campanha ou automação, e recebe o mesmo código de novo sempre que esse e-mail for renderizado para ele. Envie os códigos da sua loja aqui ou com Adicionar códigos a um cupom, ou gere códigos no Emailit e importe-os na sua loja.
  • Um cupom static tem um único código, static_code, para todos.

Quando um pedido lista um código em coupon_codes, o código é marcado como resgatado. Consulte Produtos, cupons e o carrinho.

POST/coupons

Corpo da requisição

keystringObrigatório

O nome que você usa no conteúdo, único no workspace. De 1 a 64 letras minúsculas, dígitos, - ou _, começando com uma letra ou um dígito. As letras maiúsculas são convertidas em minúsculas.

namestringObrigatório

Nome do cupom mostrado no painel, com até 191 caracteres.

descriptionstring | null

Observação para a sua equipe. Textos mais longos são cortados em 1.000 caracteres.

kindstring

unique (padrão) ou static.

static_codestring | null

Até 191 caracteres. Obrigatório para um cupom static: o código que todos recebem. Para um cupom unique, o texto que os destinatários recebem quando o pool está vazio ou o cupom expirou. Sem ele, eles recebem uma string vazia.

discount_labelstring | null

Descrição curta do desconto, como 10% off. Textos mais longos são cortados em 191 caracteres.

expires_atstring | null

Data e hora ISO 8601. Depois dela, os destinatários de um cupom unique recebem static_code no lugar de um código, também nos e-mails renderizados de novo. O Emailit não aplica a expiração na sua loja.

codesstring[] | string

Códigos a adicionar ao pool: um array, ou um texto com um código por linha. Em um texto CSV, a primeira coluna é lida e um cabeçalho como code ou coupon_code é ignorado. Um código tem de 2 a 64 letras, dígitos, -, _ ou ., começando com uma letra ou um dígito. Os códigos inválidos ficam de fora e os duplicados são adicionados uma vez. Até 10.000 códigos.

Retorno

201 Created com o objeto de cupom. Retorna 422 quando um campo é inválido ou outro cupom já tem a chave.

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

Obter um cupom

Obtém um cupom pelo ID ou pela chave, com as contagens dos códigos dele. Requer uma chave de API com escopo full.

GET/coupons/{id}

Parâmetros de caminho

idstringObrigatório

O ID do cupom (cpn_...) ou a key do cupom.

O objeto de cupom

objectstring

Sempre coupon.

idstring

ID do cupom (cpn_...).

keystring

O nome que você usa no conteúdo dos e-mails: {{coupon "welcome-10"}}. Consulte Produtos, cupons e o carrinho.

namestring

Nome do cupom mostrado no painel.

descriptionstring | null

Observação para a sua equipe.

kindstring

  • unique: um pool de códigos de uso único. Cada destinatário recebe o próprio código, um por campanha ou automação, e o mesmo código de novo quando o e-mail é renderizado de novo.

  • static: um único código, static_code, para todos.

static_codestring | null

O código compartilhado de um cupom static. Para um cupom unique, o texto que os destinatários recebem quando não sobra nenhum código ou o cupom expirou. Sem ele, eles recebem uma string vazia.

discount_labelstring | null

Descrição curta do desconto, como 10% off.

expires_atstring | null

Depois deste momento, os destinatários de um cupom unique recebem static_code no lugar de um código.

codes_totalinteger

Códigos no pool.

codes_availableinteger

Códigos que ainda podem ser distribuídos: não atribuídos a um contato e não usados em um pedido.

codes_assignedinteger

Códigos atribuídos a um contato, incluindo os que já foram resgatados.

codes_redeemedinteger

Códigos usados em um pedido (coupon_codes).

created_at, updated_atstring

Quando o cupom foi criado e quando mudou pela última vez, em 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"
}

Atualizar um cupom

Atualiza um cupom. Só mudam os campos que você enviar. Para adicionar códigos, use Adicionar códigos a um cupom: codes é ignorado nesta requisição. Requer uma chave de API com escopo full.

Se você mudar a key, atualize também as tags {{coupon "key"}} nos seus e-mails: o Emailit procura os cupons pela chave que está no conteúdo.

POST/coupons/{id}

Parâmetros de caminho

idstringObrigatório

O ID do cupom (cpn_...) ou a key atual do cupom.

Corpo da requisição

Qualquer um destes campos: key, name, description, kind, static_code, discount_label e expires_at, com as regras de Criar um cupom. Envie null em description, static_code, discount_label ou expires_at para limpar o valor. Um cupom que é ou passa a ser static precisa manter um static_code.

Retorno

200 OK com o objeto de cupom atualizado. Retorna 404 se nenhum cupom corresponder a id e 422 quando um campo é inválido ou a nova chave já está em 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"
}

Listar cupons

Lista os cupons do seu workspace, dos mais recentes para os mais antigos, com as contagens dos códigos deles. Requer uma chave de API com escopo full.

GET/coupons

Parâmetros de consulta

pageinteger

Número da página para a paginação (mínimo: 1, padrão: 1).

limitinteger

Número de cupons a retornar (mínimo: 1, máximo: 100, padrão: 25).

searchstring

Busca sem diferenciar maiúsculas de minúsculas no nome ou na chave do cupom.

matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Filtros e ordenação

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

ChaveTipoCondiçõesObservações
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_exactValores: unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Chaves de ordenação

Passe em order uma destas chaves e em direction o valor asc ou desc: key, name, kind, expires_at, created_at

Retorno

Uma página de objetos de cupom em data, com total_records, next_page_url e previous_page_url. As URLs de página levam só page e limit, então adicione a sua busca e os seus filtros de novo quando segui-las.

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
}

Excluir um cupom

Exclui um cupom junto com todos os códigos dele, incluindo os atribuídos e os resgatados. Os pedidos mantêm os códigos nos coupon_codes deles. Requer uma chave de API com escopo full.

DELETE/coupons/{id}

Parâmetros de caminho

idstringObrigatório

O ID do cupom (cpn_...) ou a key do cupom.

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
}

Listar os códigos de um cupom

Lista os códigos de um cupom, dos mais antigos para os mais recentes: a ordem em que eles são distribuídos. Use format=csv para exportá-los, por exemplo para importar os códigos gerados na sua loja. Requer uma chave de API com escopo full.

GET/coupons/{id}/codes

Parâmetros de caminho

idstringObrigatório

O ID do cupom (cpn_...) ou a key do cupom.

Parâmetros de consulta

pageinteger

Número da página para a paginação (mínimo: 1, padrão: 1).

limitinteger

Número de códigos a retornar (mínimo: 1, máximo: 100, padrão: 50).

statusstring

  • available: não atribuído a um contato e não usado em um pedido, então ainda pode ser distribuído.

  • assigned: atribuído a um contato e não resgatado.

  • redeemed: usado em um pedido.

formatstring

json (padrão) ou csv. O CSV retorna todos os códigos que correspondem a status em um único arquivo, sem paginação, com as colunas code, status, email, assigned_at e redeemed_at. Os filtros key.condition e a ordenação não se aplicam ao CSV.

matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Filtros e ordenação

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

ChaveTipoCondiçõesObservações
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

Chaves de ordenação

Passe em order uma destas chaves e em direction o valor asc ou desc: code, email, assigned_at, redeemed_at, created_at

Retorno

Uma página de códigos de cupom em data, com total_records, next_page_url e previous_page_url. Cada código tem:

objectstring

Sempre coupon_code.

idstring

ID do código (cpc_...).

codestring

O código.

contact_id, emailstring | null

O contato a quem o código está atribuído, ou null.

source_idstring | null

A campanha (cmp_...) ou a automação (aut_...) cujo e-mail recebeu o código.

assigned_atstring | null

Quando o código foi atribuído.

redeemed_at, redeemed_order_idstring | null

Quando o código foi resgatado e por qual pedido (ord_...).

created_atstring

Quando o código foi adicionado ao 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
}

Adicionar códigos a um cupom

Adiciona códigos ao pool de um cupom unique. Envie com codes os códigos que existem na sua loja, ou deixe o Emailit criar códigos aleatórios com generate e depois importe-os na sua loja com Listar os códigos de um cupom (format=csv). Os códigos que já estão no pool são ignorados. Os cupons static têm um único código e retornam 422. Requer uma chave de API com escopo full.

POST/coupons/{id}/codes

Parâmetros de caminho

idstringObrigatório

O ID do cupom (cpn_...) ou a key do cupom.

Corpo da requisição

Envie codes ou generate. Se você enviar os dois, generate é usado.

codesstring[] | string

Até 10.000 códigos: um array, ou um texto com um código por linha. Em um texto CSV, a primeira coluna é lida e um cabeçalho como code ou coupon_code é ignorado. Um código tem de 2 a 64 letras, dígitos, -, _ ou ., começando com uma letra ou um dígito. Os códigos que não correspondem a esse formato são retornados em invalid.

generateobject

Cria códigos aleatórios com letras maiúsculas e dígitos, sem 0, O, 1 e I, que são fáceis de confundir.

  • count (inteiro, obrigatório): de 1 a 10.000 códigos.

  • prefix (string): até 20 letras, dígitos, - ou _, colocados na frente de cada código. Por exemplo, WELCOME-.

  • length (inteiro): caracteres aleatórios depois do prefixo, de 4 a 32. O padrão é 8. Os valores fora do intervalo são ajustados ao limite mais próximo.

Retorno

addedinteger

Códigos adicionados ao pool.

skippedinteger

Códigos que já estavam no pool.

invalidstring[]

Valores enviados que não são códigos válidos e não foram adicionados.

couponobject

O objeto de cupom com as novas contagens.

Retorna 404 se nenhum cupom corresponder a id, e 422 para um cupom static, quando nenhum código válido foi enviado, quando mais de 10.000 códigos foram enviados ou quando generate.count ou generate.prefix está fora do intervalo.

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

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.

Esc

Populares

↑↓para navegar↵para abrirEscpara fechar