Atualizar um cupom

Atualiza parcialmente um cupom existente: você envia apenas os campos que quer mudar, e tudo o que ficar de fora permanece exatamente como estava. Use esta operação para ligar/desligar uma campanha, corrigir o desconto, estender a janela de validade ou apertar as regras de elegibilidade — sem precisar recriar o cupom (o id continua o mesmo).

PATCH /v1/coupons/{couponId}

Como funciona

O PATCH é uma atualização parcial (em contraste com PUT, que substituiria o objeto inteiro). Na prática:

• Campos enviados são sobrescritos pelo novo valor.
• Campos omitidos ficam intactos — não viram null nem voltam ao padrão.
• Para limpar uma restrição opcional (ex.: remover o teto de carrinho), envie o campo explicitamente como null quando o cupom o aceitar.

O servidor valida o corpo, aplica as mudanças de forma atômica (ou tudo ou nada) e responde com 200 OK trazendo o objeto completo e já atualizado — incluindo o novo updatedAt. Não há estado intermediário nem processamento assíncrono: quando a resposta chega, a mudança já está valendo para os próximos checkouts.

Cupons usam o prefixo de ID dis_ (de discount). Trate o id como uma string opaca — não faça parsing. Veja Convenções.

Quando usar (e quando não)

• Pausar/retomar uma campanha: alterne enabled em vez de excluir e recriar o cupom — você preserva o id, o histórico e o código.
• Estender ou encurtar a validade: ajuste initDate / endDate.
• Endurecer regras: suba o minCartAmount, reduza o usageLimit, ative limitOneUsePerCustomer.

Quando não usar:

• Para desativar temporariamente, prefira enabled: false a excluir — a exclusão é permanente: o código deixa de existir e não pode mais ser aplicado.
• Para criar um cupom novo, use Criar. O PATCH exige um cupom já existente.

Requisição

Headers

Parâmetro de caminho

Corpo

Todos os campos de configuração são opcionais — envie só o que quer alterar. A única exceção é o id, que identifica o cupom no corpo e acompanha o couponId do caminho.

Exemplo — pausar uma campanha

curl -X PATCH "https://api.selectwin.io/v1/coupons/dis_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 2f1c9b7e-coupon-pause-01" \
  -d '{
    "id": "dis_01hqzvabc",
    "enabled": false
  }'

Exemplo — ajustar desconto e estender validade

curl -X PATCH "https://api.selectwin.io/v1/coupons/dis_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dis_01hqzvabc",
    "name": "Black Friday 30%",
    "type": "percentage",
    "value": 30,
    "enabled": true,
    "endDate": "2026-12-31T23:59:59Z"
  }'

Resposta

200 OK — o corpo é o objeto completo do cupom já com as alterações aplicadas e o updatedAt renovado.

{
  "id": "dis_01hqzvabc",
  "name": "Black Friday 30%",
  "enabled": true,
  "code": "BLACKFRIDAY25",
  "type": "percentage",
  "value": 30,
  "minCartAmount": 10000,
  "maxCartAmount": null,
  "usageLimit": 100,
  "limitOneUsePerCustomer": true,
  "initDate": "2026-04-01T00:00:00.000Z",
  "endDate": "2026-12-31T23: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"
}

Campos-chave da resposta:

A resposta de cupom traz o objeto completo (diferente das listagens, que são projeções leves). Cupons não incluem merchant nem _links.

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja o Catálogo de Códigos de Erro e Tratamento de Erros.

Boas práticas

• Envie só o que muda. Como o PATCH é parcial, um corpo enxuto reduz o risco de sobrescrever sem querer um campo que outra pessoa já ajustou.
• Combine id do corpo com couponId do caminho. Eles devem apontar para o mesmo cupom; divergência leva a couponIdIsInvalid/couponIdNotFound.
• Prefira enabled: false a excluir para pausas temporárias — você preserva código, histórico e id, e pode religar depois.
• Não troque type sem rever value. Mudar de flat para percentage (ou vice-versa) sem ajustar value cria descontos absurdos (ex.: 3000% ou R$ 0,30).
• Use X-Idempotency-Key em escritas automatizadas, para que um retry após timeout não aplique a mudança duas vezes.
• Confirme pelo updatedAt da resposta (ou faça um Read) em vez de assumir sucesso pelo status — assim você lê o estado final real do cupom.
• Datas em ISO 8601 UTC (sufixo Z) e dinheiro em centavos — converta na sua aplicação antes de enviar.

Veja também

• Visão geral de Cupons — modelo do objeto, ciclo de vida e regras.
• Criar cupom — campos obrigatórios na criação.
• Ler cupom — recuperar o estado atual antes de editar.
• Listar cupons — encontrar o id por nome/código/status.
• Excluir cupom — quando remover de vez em vez de desativar.
• Convenções · Idempotência · Autenticação