Criar um cupom

Cria um novo cupom de desconto, definindo o código que o cliente digita no checkout, o tipo e o valor do desconto, e as regras que controlam quando ele pode ser usado (validade, valor mínimo de carrinho, limites de uso e restrições por cliente ou produto). Use esta operação para montar campanhas promocionais que serão aplicadas em transações e assinaturas.

POST /v1/coupons

Como funciona

Um cupom é uma regra de desconto reutilizável. Você o cria uma vez e o cliente o aplica no checkout digitando o code. No momento da compra, a API valida o cupom contra o carrinho (valor, quantidade de itens, cliente, produtos permitidos e janela de validade) e, se tudo bater, abate o desconto do valor a cobrar.

Ao chamar POST /v1/coupons, o servidor:

1. Valida o corpo (campos obrigatórios, tipos, faixas e formato das datas).
2. Confere os IDs em allowedItemIds e allowedCustomerIds, se enviados — IDs inexistentes fazem a criação falhar.
3. Persiste o cupom e gera um id opaco com prefixo dis_ (ex.: dis_01hqzvabc).
4. Inicializa o contador de uso usageQuantity em 0.
5. Responde 201 Created com o objeto completo do cupom.

O cupom já nasce "ligado" se você enviar enabled: true, mas só passa a ser aceito no checkout dentro da janela initDate … endDate. Ou seja, enabled e a janela de datas são dois controles independentes: um cupom habilitado fora da janela de validade não é aplicado.

Quando usar

• Lançar uma campanha promocional (Black Friday, primeira compra, frete grátis simulado por desconto fixo).
• Oferecer um desconto fechado para um conjunto específico de clientes (allowedCustomerIds) ou produtos (allowedItemIds).
• Criar incentivos com teto de uso (usageLimit) ou uma utilização por cliente (limitOneUsePerCustomer).

Quando não usar:

• Para alterar um cupom existente (estender validade, mudar o valor, desligar), use Atualizar — não crie um novo.
• Para um desconto pontual e não reutilizável aplicado a uma única cobrança, considere ajustar o valor na própria transação em vez de criar um cupom.

Requisição

Headers

A autenticação é sempre pelo cabeçalho SelectKey — nunca Authorization: Bearer ou Basic.

Corpo

Exemplo — cupom percentual

curl -X POST https://api.selectwin.io/v1/coupons \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 7f3c1e8a-bf2d-4a9c-9b21-1d0e5f6a7c8b" \
  -d '{
    "name": "Black Friday 25%",
    "enabled": true,
    "code": "BLACKFRIDAY25",
    "type": "percentage",
    "value": 25,
    "minCartAmount": 10000,
    "usageLimit": 100,
    "limitOneUsePerCustomer": true,
    "initDate": "2026-04-01T00:00:00Z",
    "endDate": "2026-04-30T23:59:59Z"
  }'

Exemplo — cupom de valor fixo, restrito a produtos

{
  "name": "Summer Sale R$ 5,00",
  "enabled": true,
  "code": "SUMMER2026",
  "type": "flat",
  "value": 500,
  "minCartAmount": 10000,
  "usageLimit": 1000,
  "limitOneUsePerCustomer": true,
  "initDate": "2026-04-01T00:00:00Z",
  "endDate": "2026-12-31T23:59:59Z",
  "allowedItemIds": ["prd_a1b2c3", "prd_d4e5f6"],
  "isCumulative": true
}

Aqui value: 500 significa um abatimento fixo de R$ 5,00, e o cupom só vale para os produtos listados em allowedItemIds.

Resposta

201 Created — retorna o objeto completo do cupom, sem envelope. Coupons não trazem os blocos merchant nem _links (HATEOAS) que outros recursos expõem.

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

Note a normalização: datas enviadas como 2026-04-01T00:00:00Z voltam com milissegundos (...000Z). Trate as datas como o servidor as devolveu.

Erros

A API responde com um envelope padrão e um error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Confira o type antes de definir value. Use centavos para flat e o número do percentual para percentage. Um teste rápido em sandbox (sl_test_...) evita lançar um cupom com desconto errado.
• Envie X-Idempotency-Key em toda criação. Sem ela, uma retentativa por timeout pode gerar dois cupons com o mesmo code.
• Defina sempre initDate e endDate. Sem janela, o cupom fica ativo indefinidamente enquanto enabled for true — fácil de esquecer e abusar.
• Limite o uso com usageLimit (teto global) e limitOneUsePerCustomer para conter abuso de campanhas públicas.
• Valide os IDs de restrição antes de enviar. IDs inexistentes em allowedItemIds/allowedCustomerIds causam couponCreateItemIdIsInvalid / couponCreateCustomerIdIsInvalid e abortam a criação.
• Trate code como sensível a maiúsculas/duplicidade. A API não impede dois cupons com o mesmo code; padronize a geração (ex.: maiúsculas) e verifique colisões no seu sistema antes de criar.
• Guarde o id retornado, não o code, como referência interna estável — o code pode ser reaproveitado em campanhas distintas.

Veja também

• Visão geral de Cupons — modelo do objeto e ciclo de vida.
• Ler um cupom · Atualizar · Listar · Excluir
• Convenções da API — centavos, datas ISO 8601, IDs opacos.
• Idempotência · Autenticação · Catálogo de Códigos de Erro