Visão geral

Cupons são descontos promocionais (percentuais ou de valor fixo) que você cria na sua conta e aplica em checkouts e campanhas. Cada cupom tem um código que o cliente digita e regras de elegibilidade (valor mínimo do carrinho, datas de validade, limites de uso). Esta página explica o modelo do objeto, seu ciclo de vida e todas as operações disponíveis.

O que é um cupom

Um cupom representa uma regra de desconto reutilizável. Você o configura uma vez (tipo, valor, condições) e ele fica disponível para ser aplicado durante a compra. Pense nele como uma "campanha de desconto" persistente: enquanto estiver ativo (enabled: true) e dentro da janela de validade, clientes que informarem o code recebem o abatimento — desde que o carrinho atenda às restrições.

Dois conceitos definem o desconto:

• type — como o desconto é calculado. Os únicos valores válidos são "flat" (valor fixo) e "percentage" (percentual). Não existe "percent".
• value — o tamanho do desconto, e sua unidade depende do type:
  • Para type: "flat", value é um valor em centavos (500 = R$ 5,00 de desconto).
  • Para type: "percentage", value é o percentual (25 = 25% de desconto).

O prefixo do ID de cupom é dis_ (de discount). Como todo ID na API, trate-o como uma string opaca — não faça parsing. Veja Convenções.

Modelo do objeto

O objeto completo é retornado por Create, Read e Update. Listagens retornam uma projeção mais leve (veja Projeção em listas).

{
  "id": "dis_01hqzvabc",
  "name": "Black Friday 25%",
  "enabled": true,
  "code": "BLACKFRIDAY25",
  "type": "percentage",
  "value": 25,
  "minCartAmount": 10000,
  "maxCartAmount": null,
  "usageLimit": 100,
  "limitOneUsePerCustomer": true,
  "initDate": "2026-04-01T00:00:00.000Z",
  "endDate": "2026-04-30T23:59:59.000Z",
  "allowedItemIds": null,
  "allowedCustomerIds": null,
  "usageQuantity": 0,
  "minCartItems": 0,
  "maxCartItems": 0,
  "isCumulative": false,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Como as restrições se combinam

Para que um cupom seja aplicado a um carrinho, todas as condições configuradas precisam ser satisfeitas ao mesmo tempo:

• enabled é true e o momento atual está entre initDate e endDate;
• o subtotal do carrinho é >= minCartAmount e (se houver teto) <= maxCartAmount;
• a quantidade de itens respeita minCartItems/maxCartItems (quando diferentes de 0);
• se allowedItemIds/allowedCustomerIds estiverem definidos, o item/cliente precisa constar na lista;
• o usageLimit global ainda não foi atingido e, se limitOneUsePerCustomer for true, aquele cliente ainda não usou.

Quando o cupom passa por todas as checagens, o desconto é calculado a partir de type/value e abatido do valor cobrado.

Ciclo de vida

Um cupom não tem máquina de estados rica como uma transação; seu "estado" efetivo deriva de três coisas: a flag enabled, a janela initDate–endDate e o teto de resgates usageLimit.

• Ativo vs. Inativo é controlado por você via enabled (use o PATCH para ligar/desligar sem perder o histórico).
• Expirado é automático: depois de endDate, o cupom deixa de ser aplicável mesmo com enabled: true.
• Esgotado é automático: quando o total de resgates atinge usageLimit, novos resgates são recusados.
• Excluído (DELETE) é permanente e remove o cupom do escopo da conta. Prefira enabled: false quando quiser apenas pausar.

Operações

Todas as requisições usam a base URL https://api.selectwin.io/v1 e o header de autenticação SelectKey (chaves de produção começam com sl_live_; em sandbox, com sl_test_). Veja Autenticação.

curl https://api.selectwin.io/v1/coupons/dis_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Projeção em listas

As listagens não devolvem o objeto inteiro — devolvem uma projeção leve com apenas os campos mais usados em telas de catálogo:

id, name, code, type, value, enabled, initDate, endDate, createdAt, updatedAt.

Campos como minCartAmount, usageLimit, usageQuantity, allowedItemIds, allowedCustomerIds, isCumulative não aparecem na lista. Para o objeto completo, faça um Read pelo id.

Há duas formas de listar:

• GET /v1/coupons — paginado. Retorna um envelope { offset, limit, total, page, data, hasMore } e aceita filtros (name, code, type, status, faixas de data) e ordenação. Use no dia a dia. Veja Paginação.
• GET /v1/coupons/listall — retorna um array direto com todos os cupons da conta (sem envelope de paginação). Útil para exportar/sincronizar o catálogo inteiro; use com parcimônia em contas com muitos cupons.

Erros

Os códigos a seguir são específicos do recurso Cupons (veja o Catálogo de Códigos de Erro). Trate sempre pelo error.code, nunca pela message.

Além desses, valem os erros transversais a toda a API:

Boas práticas

1. Use code único, curto e legível. É o que o cliente digita; evite ambiguidade (O vs. 0).
2. Confira a unidade de value. Centavos para flat, percentual para percentage — esse é o erro mais comum ao criar cupons.
3. Pause em vez de excluir. Para encerrar uma campanha sem perder o cupom e suas regras, faça PATCH { enabled: false }. Reserve o DELETE para limpeza definitiva — ele é irreversível.
4. Defina sempre initDate e endDate. Janelas explícitas evitam que um cupom de campanha continue válido por engano.
5. Limite o abuso com usageLimit e limitOneUsePerCustomer. Combine os dois para campanhas de aquisição (um resgate por cliente, com teto global).
6. Defina o teto de resgates com usageLimit para encerrar a campanha automaticamente quando o orçamento de descontos for atingido.
7. Valide IDs de restrição antes de enviar. IDs inválidos em allowedItemIds/allowedCustomerIds retornam couponCreateItemIdIsInvalid/couponCreateCustomerIdIsInvalid.
8. Decida isCumulative com cuidado. Permitir empilhamento com outros descontos pode reduzir margens de forma inesperada; o padrão é não acumular (false).

Veja também

• Create — criar um cupom (corpo completo, campos obrigatórios).
• Read — recuperar um cupom pelo ID.
• Update — atualização parcial (PATCH), inclusive ativar/desativar.
• List — listar com filtros, paginação e a variante listall.
• Delete — exclusão permanente.
• Convenções — camelCase, centavos, datas UTC, IDs opacos.
• Catálogo de Códigos de Erro — todos os error.code.
• Paginação — envelope offset/limit/page/hasMore.
• Autenticação — header SelectKey.