Criar um cupom

POST /v1/coupons

Cria um novo cupom de desconto com regras de aplicação, validade e limites.

Requisição

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

Campos do corpo

Campo	Tipo	Obrig.	Descrição
`name`	string (1–80)	sim	Nome descritivo do cupom.
`code`	string (1–50)	sim	Código aplicado pelo cliente (único por empresa).
`type`	enum	sim	`flat` (valor fixo em reais) ou `percentage` (taxa 0–100).
`value`	number	sim	Desconto. Se `percentage`: 0–100. Se `flat`: valor em reais (decimal, ex.: `12.30`).
`enabled`	boolean	sim	Cupom ativo.
`minCartAmount` / `maxCartAmount`	number (centavos)	não	Faixa de valor do carrinho em centavos.
`minCartItems` / `maxCartItems`	number (int)	não	Faixa de quantidade de itens.
`usageLimit`	number (int)	não	Limite total de usos.
`usageQuantity`	number (int)	não	Usos já contabilizados (normalmente gerenciado pela API).
`limitOneUsePerCustomer`	boolean	não	Restringe a 1 uso por cliente.
`isCumulative`	boolean	não	Permite acumular com outros descontos. Default `false`.
`initDate` / `endDate`	datetime ISO 8601	não	Janela de validade.
`allowedItemIds`	array de publicIds (≤ 1000)	não	Restringe a produtos/variantes específicos.
`allowedCustomerIds`	array de `cus_*` (≤ 1000)	não	Restringe a clientes específicos.
`scope`	enum	não	`firstCharge` (default) ou `recurring`.
`recurringCycles`	number (1–999) \| null	não	Quando `scope=recurring`: máximo de ciclos (`null` = todos).

Campos opcionais enviados como null/"" são tratados como ausentes (empty-to-absent). Para type=percentage, value acima de 100 é rejeitado (422).

Resposta - 201 Created

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

Nota: Root level, sem merchant ou _links.

Atributos da Resposta

Atributo	Tipo	Descrição
`id`	string	publicId `dis_` (ou `coup_` para legados).
`name`	string \| null	Nome descritivo.
`code`	string \| null	Código para aplicação.
`type`	string	`flat` ou `percentage`.
`value`	number	Desconto: 0–100 se `percentage`; reais (decimal) se `flat`.
`enabled`	boolean	Ativo.
`minCartAmount` / `maxCartAmount`	number \| null	Faixa de valor do carrinho (centavos).
`minCartItems` / `maxCartItems`	number \| null	Faixa de quantidade de itens.
`usageLimit`	number \| null	Limite total de usos.
`usageQuantity`	number \| null	Usos atuais.
`limitOneUsePerCustomer`	boolean	Uma vez por cliente.
`isCumulative`	boolean	Acumulável.
`initDate` / `endDate`	string \| null	Validade (ISO 8601).
`allowedItemIds` / `allowedCustomerIds`	array \| null	Restrições.
`scope`	string	`firstCharge` ou `recurring`.
`recurringCycles`	number \| null	Máx. de ciclos quando `scope=recurring`.
`createdAt` / `updatedAt`	string	Timestamps ISO 8601.

Respostas de Erro

`error.code`	HTTP	Quando
`couponCodeConflict`	409	Já existe um cupom com este `code`.

Erros de validação do corpo retornam 400 (campos inválidos) ou 422 (ex.: percentage > 100).

Melhores Práticas

Use codes únicos e memoráveis.
Defina datas de validade (initDate/endDate).
Monitore usageQuantity via reads para evitar overuse.