Cupons - Atualizar
PUT /v1/coupons/{couponId} ou PATCH /v1/coupons/{couponId}
Atualiza um cupom existente. Ambos os métodos têm o mesmo comportamento (envie apenas os campos que deseja alterar — todos são opcionais).
Requisição
Shell
curl -X PUT "https://api.selectwin.io/v1/coupons/dis_01hqzvabc" \
-H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
-H "Content-Type: application/json" \
-d '{
"name": "Black Friday 30%",
"value": 30,
"enabled": true,
"endDate": "2026-12-31T23:59:59Z"
}'Campos (todos opcionais no update)
| Campo | Tipo | Descrição |
|---|---|---|
name | string (1–80) | Nome do cupom. |
code | string (1–50) | Código aplicado pelo cliente. |
type | enum | flat (valor fixo em reais) ou percentage (taxa 0–100). |
value | number | Desconto: 0–100 se percentage; reais (decimal) se flat. |
enabled | boolean | Ativa/desativa o cupom. |
minCartAmount / maxCartAmount | number (centavos) | Faixa de valor do carrinho. |
minCartItems / maxCartItems | number (int) | Faixa de quantidade de itens. |
usageLimit | number (int) | Limite total de usos. |
usageQuantity | number (int) | 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 | Restringe a 1 uso por cliente. |
isCumulative | boolean | Permite acumular com outros descontos. |
initDate / endDate | datetime ISO 8601 | null | Janela de validade. null remove o limite (sem início / sem término); campo ausente mantém o valor atual. Mande a hora com fuso (2026-12-31T23:59:59-03:00 ou em UTC): uma hora sem fuso é lida como UTC. |
allowedItemIds | array de publicIds (≤ 1000) | Restringe a produtos/variantes específicos. |
allowedCustomerIds | array de cus_* (≤ 1000) | Restringe a clientes específicos. |
scope | enum | firstCharge ou recurring. |
recurringCycles | number (1–999) | null | Máx. de ciclos quando scope=recurring. |
Resposta - 200 OK
JSON
{
"id": "dis_01hqzvabc",
"name": "Black Friday 30%",
"code": "BLACKFRIDAY25",
"type": "percentage",
"value": 30,
"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-12-31T23: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"
}Erros
error.code | HTTP | Quando |
|---|---|---|
couponNotFound | 404 | Nenhum cupom com o couponId informado. |
couponCodeConflict | 409 | O novo code já é usado por outro cupom. |
Erros de validação do corpo retornam 400 (campos inválidos) ou 422 (ex.: percentage > 100).
O estado FINAL é validado, não só o corpo. Um update que muda um campo só é conferido junto com o que
já está gravado: {"value": 5000} num cupom percentage responde 422 invalidParameters
(params[0].value), mesmo sem type no corpo — antes era gravado como 5000%. O mesmo vale para
minCartAmount acima de maxCartAmount e minCartItems acima de maxCartItems (0 = sem limite, nunca
conflita).
Atualizado em 21 de outubro de 2026