Cupons - Criar

POST /v1/coupons

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

Requisição

Shell

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	Quantas vezes cada cliente pode usar o cupom (`0` = sem limite por cliente). Com `limitOneUsePerCustomer: true`, vale 1. Não é contador — quantas vezes o cupom já foi usado vem em `redemptionsCount`, na leitura.
`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 ids de variante (`var_…`, ≤ 1000)	não	Restringe a variantes específicas — o cupom só vale com uma delas no carrinho, e só desconta esses itens. Cada id precisa ser uma variante da sua conta, no mesmo ambiente do cupom; um id de produto (`prd_…`) ou de outra conta volta 400 `invalidParameters` no campo `allowedItemIds[i]` (ver Visão Geral).
`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).

Resposta - 201 Created

JSON

{
  "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,
  "redemptionsCount": 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	Limite de usos por cliente (`0` = sem limite). Não é contador.
`redemptionsCount`	number	Quantas vezes o cupom já foi usado (resgates em andamento e confirmados) — a mesma contagem que o `usageLimit` barra. Esgotado quando `usageLimit > 0` e `redemptionsCount >= usageLimit`.
`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).
Acompanhe redemptionsCount nas leituras para saber quando o cupom vai esgotar.

AnteriorVisão geral PróximaListar

Atualizado em 21 de outubro de 2026

Cupons - Criar

#Requisição

#Campos do corpo

#Resposta - 201 Created

#Atributos da Resposta

#Respostas de Erro