Cupons - Visão Geral

#Introdução

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), datas de validade, limites de uso e escopo para assinaturas recorrentes.

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,
  "redemptionsCount": 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

#Cupom restrito a itens (allowedItemIds)

Com allowedItemIds preenchido (ids de variante, var_… — para liberar um produto inteiro, liste as variantes dele), o cupom só vale se o carrinho tiver pelo menos um dos itens — e o desconto é calculado só sobre esses itens, não sobre o carrinho inteiro. Um cupom de 50% restrito a uma caneca de R$ 10,00, num carrinho que também tem um notebook de R$ 5.000,00, desconta R$ 5,00. Um cupom flat restrito fica limitado ao valor dos itens permitidos.

#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

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

#Boas Práticas

1. Use code único e descritivo para fácil aplicação pelo cliente.
2. Defina initDate/endDate para controlar a validade.
3. Limite via usageLimit e limitOneUsePerCustomer para evitar abuso.
4. Acompanhe redemptionsCount nas leituras — é o que o usageLimit conta. usageQuantity é o limite por cliente, não um contador.
5. 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.