Excluir um cupom

Remove permanentemente um cupom da sua conta. Depois de excluído, o código deixa de existir e não pode mais ser aplicado em nenhum checkout. Use quando uma campanha terminou de vez e você quer remover o cupom do catálogo; se for apenas suspender o uso temporariamente, prefira desativá-lo.

DELETE /v1/coupons/{couponId}

Como funciona

A exclusão é permanente (hard delete): o cupom é apagado do catálogo da sua conta. Não há lixeira nem etapa de confirmação — a chamada já efetiva a remoção. A partir daí, qualquer tentativa de ler (GET), atualizar (PATCH) ou excluir novamente esse id retorna 404 com couponIdNotFound.

Excluir um cupom não desfaz descontos já aplicados em transações passadas: pedidos que usaram o cupom permanecem como estão. A operação remove apenas a regra de desconto para usos futuros.

Atenção

A exclusão é irreversível. Não existe endpoint para restaurar um cupom apagado. Se você só quer impedir novas aplicações sem perder o histórico de configuração, não exclua — desative o cupom enviando enabled: false via PATCH. Assim o código fica preservado e pode ser reativado depois.

Quando usar (e quando não usar)

Situação	Ação recomendada
Campanha encerrada de vez, sem reaproveitar o código	Excluir (este endpoint)
Pausar o cupom mas poder reativá-lo depois	Desativar via `PATCH` com `enabled: false`
Corrigir valor, datas ou regras do cupom	Atualizar via `PATCH`
Conferir antes de remover se o cupom ainda existe ou está em uso	Ler via `GET` ou listar

Importante

Verifique se não há checkouts ativos ou campanhas ainda vinculados ao cupom antes de removê-lo. Como a exclusão é permanente, links de checkout que dependam desse código deixarão de conceder o desconto imediatamente.

Requisição

Headers

Cabeçalho	Obrigatório	Descrição
`SelectKey`	Sim	Sua chave de API (`sl_live_...` em produção, `sl_test_...` em sandbox). Veja Autenticação.
`X-Idempotency-Key`	Recomendado	Torna a chamada segura para repetição em caso de timeout/retry. Veja Idempotência.

Não envie Content-Type nem corpo: esta requisição não tem body.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
`couponId`	path	string	Sim	ID público do cupom a excluir (ex.: `dis_01hqzvabc`).
`id`	query	string	Sim	ID público do cupom (mesmo valor de `couponId`). Deve casar com o padrão `^[a-z]+_[A-Za-z0-9]+$`.

Trate o id como uma string opaca: use exatamente o valor retornado quando o cupom foi criado ou listado, sem fazer parsing nem montá-lo à mão. Veja as Convenções.

Exemplo curl

curl -X DELETE "https://api.selectwin.io/v1/coupons/dis_01hqzvabc?id=dis_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "X-Idempotency-Key: del-coupon-dis_01hqzvabc-2026-06-10"

Resposta 200 OK

A API confirma a exclusão com um objeto curto:

{
  "id": "dis_01hqzvabc",
  "resource": "coupon",
  "deleted": true
}

Campo	Tipo	Descrição
`id`	string	ID do cupom que foi excluído.
`resource`	string	Tipo do recurso removido — sempre `coupon`.
`deleted`	boolean	`true` quando a exclusão foi efetivada.

Confirme o sucesso pelo status 200 (ou pelo campo deleted: true), não pelo conteúdo da mensagem.

Erros

`error.code`	HTTP	Quando ocorre
`couponIdIsInvalid`	400	O `couponId`/`id` não está no formato esperado (`prefixo_valor`).
`couponDeleteFailed`	400	A exclusão não pôde ser concluída (ex.: cupom ainda vinculado a recursos ativos).
`couponIdNotFound`	404	Não existe cupom com esse ID — ou ele já foi excluído.
`unauthorized`	401	`SelectKey` ausente, inválida ou revogada.
`forbidden`	403	A chave não tem permissão para excluir cupons.
`tooManyRequests`	429	Limite de requisições excedido — repita com backoff.
`serverError`	500	Erro interno — tente novamente; se persistir, contate o suporte.

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

Dica

Um couponIdNotFound ao reexecutar a mesma exclusão geralmente significa que a primeira chamada já funcionou. Trate esse caso como sucesso idempotente, não como falha.

Boas práticas

Desative em vez de excluir quando houver chance de reuso: PATCH com enabled: false preserva o histórico de configuração e permite reativar depois.
Confirme o estado antes de apagar com um GET ou uma listagem, sobretudo se a operação for disparada por uma automação.
Envie X-Idempotency-Key para que retries de rede não causem comportamento inesperado e o resultado seja consistente.
Verifique vínculos ativos (links de checkout, campanhas) antes de remover, já que o desconto deixa de valer imediatamente.
Não reexiba o código ao usuário após excluir: o cupom não existe mais e novas aplicações falharão.
Registre o id excluído no seu sistema para auditoria, pois a API não mantém o cupom apagado.

Veja também

Visão geral de Cupons — o objeto, seus campos e o ciclo de vida.
Atualizar um cupom — desative com enabled: false em vez de excluir.
Ler um cupom — confirme o estado antes de remover.
Listar cupons — encontre o id correto.
Convenções da API e Idempotência.

Excluir um cupom

On this page