Cria um cupom

POST/v1/coupons

Autentique com o header SelectKey: a chave sk_test_ opera no sandbox, a sk_live_ em produção. Como autenticar.

Corpo da requisição

codestringobrigatório
O código que o comprador digita.
namestringobrigatório
Nome do cupom, para a sua referência.
typestringobrigatório
flat (um valor fixo) ou percentage.
Valores:flatpercentage
scopestring
Numa assinatura: firstCharge desconta só a primeira cobrança (padrão); recurring é reaplicado a cada ciclo, até recurringCycles.
Valores:firstChargerecurring
valuenumberobrigatório
Em percentage, o percentual (0–100); em flat, o valor em reais (decimal, ex.: 12.30).
enabledbooleanobrigatório
Se o cupom pode ser usado.
endDatestring (date-time)
Até quando o cupom vale.
initDatestring (date-time)
A partir de quando o cupom vale.
usageLimitinteger
Número total de usos permitidos (0 = ilimitado).
isCumulativeboolean
Se pode ser combinado com outros cupons.
maxCartItemsinteger
Número máximo de itens no carrinho.
minCartItemsinteger
Número mínimo de itens no carrinho.
maxCartAmountinteger
Valor máximo do carrinho para o cupom valer (centavos).
minCartAmountinteger
Valor mínimo do carrinho para o cupom valer (centavos).
usageQuantityinteger
Usos permitidos por cliente (0 = ilimitado).
allowedItemIdsstring[]
Só estas variantes ganham o desconto (ids de variante).
recurringCyclesintegerpode ser nulo
Com scope=recurring: quantos ciclos ganham o desconto; null = todos os ciclos.
allowedCustomerIdsstring[]
Só estes clientes podem usar o cupom.
limitOneUsePerCustomerboolean
Cada cliente pode usar o cupom uma vez.

Respostas

201Criado

idstringobrigatório
Identificador público (dis_/coup_…)
codestringobrigatóriopode ser nulo
O código que o comprador digita.
namestringobrigatóriopode ser nulo
Nome do cupom.
typestringobrigatório
flat (um valor fixo) ou percentage.
Valores:flatpercentage
scopestringobrigatório
Numa assinatura: firstCharge (só a primeira cobrança) ou recurring (todo ciclo, até recurringCycles).
Valores:firstChargerecurring
valuenumberobrigatório
Em percentage, o percentual (0–100); em flat, o valor em reais (decimal).
enabledbooleanobrigatório
Se o cupom pode ser usado.
endDatestringobrigatóriopode ser nulo
Até quando o cupom vale; null = sem fim.
initDatestringobrigatóriopode ser nulo
A partir de quando o cupom vale; null = sem início.
createdAtstringobrigatório
Quando o recurso foi criado (ISO 8601, UTC).
updatedAtstringobrigatório
Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
usageLimitintegerobrigatóriopode ser nulo
Número total de usos permitidos; null ou 0 = ilimitado.
isCumulativebooleanobrigatório
Se pode ser combinado com outros cupons.
maxCartItemsintegerobrigatóriopode ser nulo
Número máximo de itens; null = sem limite.
minCartItemsintegerobrigatóriopode ser nulo
Número mínimo de itens; null = sem mínimo.
maxCartAmountintegerobrigatóriopode ser nulo
Valor máximo do carrinho (centavos); null = sem limite.
minCartAmountintegerobrigatóriopode ser nulo
Valor mínimo do carrinho (centavos); null = sem mínimo.
usageQuantityintegerobrigatóriopode ser nulo
Usos permitidos por cliente; null ou 0 = ilimitado.
allowedItemIdsany[]obrigatóriopode ser nulo
Ids das variantes a que o cupom se restringe; null = qualquer item.
recurringCyclesintegerobrigatóriopode ser nulo
Com scope=recurring: quantos ciclos ganham o desconto; null = todos os ciclos.
redemptionsCountintegerobrigatório
Quantas vezes o cupom foi usado (reservas e confirmados). Esgota quando usageLimit > 0 e isto chega lá.
allowedCustomerIdsany[]obrigatóriopode ser nulo
Ids dos clientes a que o cupom se restringe; null = qualquer cliente.
limitOneUsePerCustomerbooleanobrigatório
Cada cliente pode usar o cupom uma vez.

400Requisição inválida (validação)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

401Não autenticado (credencial ausente ou inválida)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

403Sem permissão

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

409Conflito (idempotência ou estado)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

422Regra de negócio impede o processamento

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

500Erro interno do servidor

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

AnteriorLista os cupons PróximaValida um cupom contra um carrinho (prévia do desconto)

curl -X POST "https://api.selectwin.io/v1/coupons" \ -H "SelectKey: $SELECTWIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "string", "name": "Acme Ltda", "type": "flat", "scope": "firstCharge", "value": 5000, "enabled": true, "endDate": "2026-01-15T12:00:00.000Z", "initDate": "2026-01-15T12:00:00.000Z", "usageLimit": 0, "isCumulative": true, "maxCartItems": 0, "minCartItems": 0, "maxCartAmount": 5000, "minCartAmount": 5000, "usageQuantity": 0, "allowedItemIds": [ "var_0a1b2c3d4e5f60718293" ], "recurringCycles": 1, "allowedCustomerIds": [ "cus_0a1b2c3d4e5f60718293" ], "limitOneUsePerCustomer": true }'

{ "id": "dis_0a1b2c3d4e5f60718293", "code": "string", "name": "Acme Ltda", "type": "flat", "scope": "firstCharge", "value": 5000, "enabled": true, "endDate": "string", "initDate": "string", "createdAt": "string", "updatedAt": "string", "usageLimit": 0, "isCumulative": true, "maxCartItems": 0, "minCartItems": 0, "maxCartAmount": 5000, "minCartAmount": 5000, "usageQuantity": 0, "allowedItemIds": [], "recurringCycles": 0, "redemptionsCount": 0, "allowedCustomerIds": [], "limitOneUsePerCustomer": true }