Consultar um cupom
Recupera os dados completos de um cupom de desconto pelo seu ID. Use esta operação sempre que precisar exibir, auditar ou conferir o estado atual de um cupom — por exemplo, ver quantas vezes ele já fo
Recupera os dados completos de um cupom de desconto pelo seu ID. Use esta operação sempre que precisar exibir, auditar ou conferir o estado atual de um cupom — por exemplo, ver quantas vezes ele já foi usado antes de divulgar a campanha, ou carregar os valores atuais antes de editá-lo.
GET /v1/coupons/{couponId}
Como funciona
Um cupom é o objeto que define um desconto (prefixo de ID dis_, ex.: dis_01hqzvabc). A leitura é uma operação somente leitura, síncrona e sem efeitos colaterais: o servidor localiza o cupom da sua conta pelo ID e devolve o objeto completo. Não altera nada e pode ser repetida à vontade.
A leitura retorna o objeto em sua forma completa (todos os campos), diferente da listagem, que devolve apenas uma projeção leve (poucos campos por item). Sempre que precisar de campos como minCartAmount, usageQuantity ou isCumulative, consulte o cupom individual por aqui.
O endpoint identifica o cupom duas vezes: pelo segmento de caminho {couponId} e por um parâmetro de query id — ambos obrigatórios e devendo apontar para o mesmo cupom. Veja Requisição.
Importante
Os IDs são opacos: armazene a string inteira (dis_...) e nunca tente interpretá-la ou reconstruí-la. O prefixo dis_ é só uma conveniência de leitura. Veja Convenções.
Quando usar
- Exibir um cupom em um painel administrativo ou tela de detalhe.
- Conferir o consumo (
usageQuantityvs.usageLimit) antes de promover ou encerrar uma campanha. - Carregar o estado atual antes de uma atualização (PATCH), para saber o que já está configurado.
- Auditar janelas de validade (
initDate/endDate) e restrições (allowedItemIds,allowedCustomerIds).
Quando não usar:
- Para listar vários cupons ou aplicar filtros (nome, código, status, tipo), use Listar cupons — não faça N leituras individuais.
- Para descobrir se um código é válido no checkout, a validação acontece no fluxo de pagamento; esta leitura serve para inspecionar a configuração, não para aplicar o desconto.
Requisição
Headers
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
SelectKey | Sim | Sua chave de API. Em produção começa com sl_live_; em sandbox, com sl_test_. Nunca use Authorization: Bearer/Basic. Veja Autenticação. |
Como é uma leitura (sem corpo), não há Content-Type nem X-Idempotency-Key.
Parâmetros
| Parâmetro | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
couponId | caminho | string | Sim | ID público do cupom (ex.: dis_01hqzvabc). |
id | query | string | Sim | ID público do cupom a recuperar. Deve casar com o padrão ^[a-z]+_[A-Za-z0-9]+$ e apontar para o mesmo cupom do caminho (ex.: dis_01hqzvabc). |
Atenção
Envie o mesmo ID nos dois lugares. Um ID fora do padrão ^[a-z]+_[A-Za-z0-9]+$ retorna couponIdIsInvalid (400); um ID bem formado que não existe na sua conta retorna couponIdNotFound (404).
Exemplo curl
curl "https://api.selectwin.io/v1/coupons/dis_01hqzvabc?id=dis_01hqzvabc" \
-H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"Resposta
200 OK — o corpo é o objeto completo do cupom.
{
"id": "dis_01hqzvabc",
"name": "Black Friday 25%",
"enabled": true,
"code": "BLACKFRIDAY25",
"type": "percentage",
"value": 25,
"minCartAmount": 10000,
"maxCartAmount": null,
"usageLimit": 100,
"limitOneUsePerCustomer": true,
"initDate": "2026-04-01T00:00:00.000Z",
"endDate": "2026-04-30T23: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 da resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID público do cupom (dis_...). |
name | string | Nome de exibição do cupom. |
enabled | boolean | Se o cupom está ativo. false desliga o cupom sem excluí-lo. |
code | string | Código digitado no checkout (ex.: BLACKFRIDAY25). |
type | string | Tipo de desconto: flat (valor fixo) ou percentage (percentual). |
value | integer | Para flat, o desconto em centavos (ex.: 500 = R$ 5,00). Para percentage, o percentual (ex.: 25 = 25%). |
minCartAmount | integer | Valor mínimo do carrinho (em centavos) para o cupom valer. |
maxCartAmount | integer | null | Teto opcional do valor do carrinho (em centavos). null quando não há limite. |
usageLimit | integer | Número máximo de resgates no total. |
limitOneUsePerCustomer | boolean | Restringe a um uso por cliente. |
initDate | string (ISO 8601 UTC) | Início da validade do cupom. |
endDate | string (ISO 8601 UTC) | Fim da validade do cupom. |
allowedItemIds | array | null | Restringe o cupom a IDs de itens/produtos específicos. null = sem restrição. |
allowedCustomerIds | array | null | Restringe o cupom a IDs de clientes específicos. null = sem restrição. |
usageQuantity | integer | Quantidade de usos já registrados (consumo atual). |
minCartItems | integer | Número mínimo de itens no carrinho para o cupom valer. |
maxCartItems | integer | Número máximo de itens no carrinho para elegibilidade. |
isCumulative | boolean | Se o cupom acumula com outros descontos. |
updatedAt | string (ISO 8601 UTC) | Data/hora da última atualização. |
createdAt | string (ISO 8601 UTC) | Data/hora de criação. |
Nota
Lembre das convenções: dinheiro é sempre inteiro em centavos, datas são ISO 8601 em UTC (sufixo Z) e campos usam camelCase. Um campo presente com null (ex.: maxCartAmount: null) significa "sem valor" — diferente de o campo estar ausente. Este objeto completo traz campos que não aparecem na listagem (que omite, por exemplo, minCartAmount, usageQuantity e isCumulative).
Erros
O corpo de erro segue o envelope padrão com um error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.
error.code | HTTP | Quando ocorre |
|---|---|---|
couponIdIsInvalid | 400 | ID do cupom malformado (fora do padrão ^[a-z]+_[A-Za-z0-9]+$). |
invalidParameters | 400 | Falha de validação genérica nos parâmetros (veja error.params). |
unauthorized | 401 | SelectKey ausente, inválida ou revogada. |
forbidden | 403 | Autenticado, mas sem permissão para acessar este cupom. |
couponIdNotFound | 404 | Nenhum cupom com esse ID existe na sua conta. |
unprocessableEntity | 422 | Requisição compreendida, mas não processável por regra de negócio. |
tooManyRequests | 429 | Limite de requisições excedido — respeite error.retryAfterMinutes e repita com backoff. |
serverError | 500 | Erro interno inesperado — tente novamente; se persistir, contate o suporte. |
Boas práticas
- Guarde o
idque você recebeu na criação (dis_...) e use-o aqui; não tente reconstruir nem deduzir IDs. - Antes de encerrar ou prorrogar uma campanha, leia o cupom e compare
usageQuantitycomusageLimitpara saber quanto do orçamento de resgates já foi consumido. - Prefira ler antes de atualizar: carregue o cupom, ajuste só o necessário e envie o PATCH — assim você não sobrescreve campos por engano. Veja Atualizar cupom.
- Não faça leituras individuais em massa para montar telas de listagem; use Listar cupons com filtros e paginação. Só leia o cupom individual quando precisar dos campos completos.
- Trate
couponIdNotFound(404) como cenário esperado (cupom excluído ou ID trocado) e não como falha do servidor; reserve novas tentativas para429e5xx. - Converta valores na exibição: divida
value/minCartAmountpor 100 só na hora de mostrar; mantenha-os em centavos no seu sistema.
Veja também
- Visão geral de Cupons — o modelo do objeto e o ciclo de vida.
- Criar cupom — como nasce um cupom e o significado de cada campo.
- Atualizar cupom — alterar campos com PATCH.
- Listar cupons — busca com filtros e paginação.
- Excluir cupom — remoção permanente.
- Convenções · Autenticação · Catálogo de Códigos de Erro
How is this guide?