Visão geral

O recurso de Cupons permite gerenciar descontos promocionais que podem ser aplicados em transações e assinaturas. Suporta descontos percentuais ou de valor fixo, restrições de carrinho (valor e itens)

Introdução

Cupons são aplicados em uma cobrança informando o código no array discounts da transação/assinatura ("discounts": [{ "code": "BLACKFRIDAY25" }]). O valor do desconto nunca vem do request — é resolvido a partir do cupom cadastrado no catálogo.

Base URL: https://api.selectwin.io/v1. Autenticação via header SelectKey (sk_test_ / sk_live_).

Estrutura do Objeto Cupom

Respostas de create/read/update retornam o objeto completo no root level (sem merchant nem _links, conforme o mount-object de coupons):

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

Tipo e unidade de value

`type`	Significado de `value`
`percentage`	Taxa percentual de 0 a 100 (ex.: `25` = 25%).
`flat`	Valor fixo em REAIS (decimal, ex.: `12.30`). O motor converte reais → centavos no momento da cobrança.

Atenção: para flat o value é em reais (não centavos). Já os campos de carrinho minCartAmount / maxCartAmount são em centavos (BRL).

Escopo recorrente

scope: "firstCharge" (padrão) — o desconto se aplica apenas à 1ª cobrança/ciclo.
scope: "recurring" — o desconto é fixado na assinatura e reaplicado a cada ciclo, até recurringCycles ciclos (null = todos os ciclos enquanto a assinatura existir).

Regras de respostas (fidelidade ao código):

Create/read/update: objeto completo (acima), sem merchant ou _links.
Delete: { "id", "resource": "coupon", "deleted": true } (sem merchant/_links).
List: paginado { offset, limit, total, page, data: [...], hasMore } — itens completos (objeto CouponResource), sem merchant/_links no envelope.
Listall: array direto de itens leves (root = array, sem paginação/mount).

Itens de listall (projeção leve): id, name, code, type, value, enabled, initDate, endDate, createdAt, updatedAt.

Operações

Método	Path	Descrição
POST	`/v1/coupons/validate`	Validar/prever desconto de um código contra um carrinho (sem cobrar)
POST	`/v1/coupons`	Criar (201, objeto completo)
GET	`/v1/coupons`	Listar (paginado)
GET	`/v1/coupons/listall`	Listar todos (array, sem paginação)
GET	`/v1/coupons/{couponId}`	Ler (objeto completo)
PUT \| PATCH	`/v1/coupons/{couponId}`	Atualizar (200, objeto completo)
DELETE	`/v1/coupons/{couponId}`	Excluir (confirmação mínima)

O couponId aceita os prefixos dis_ (cupons criados pela API node) e coup_ (cupons legados).

Consulte os arquivos específicos para exemplos de requisição/resposta e atributos.

Boas Práticas

Use code único e descritivo para fácil aplicação pelo cliente.
Defina initDate/endDate para controlar a validade.
Limite via usageLimit e limitOneUsePerCustomer para evitar abuso.
Monitore usageQuantity via reads.
Use POST /v1/coupons/validate para pré-visualizar o desconto no checkout antes de cobrar.

Integração

Cupons são aplicados em transações/assinaturas via o array discounts: [{ code }]. Use POST /v1/coupons/validate para prever o resultado antes da cobrança.