Cupons - PlugToPay

Criar cupom

POST /api/v1/subscriptions/coupons — requer X-Client-ID + X-API-Key.

{
  "code": "VERAO30",
  "name": "30% de desconto — Verão",
  "description": "Promoção de verão, primeiros 3 meses",
  "discount_type": "percentage",
  "discount_value": 30,
  "max_redemptions": 200,
  "max_cycles": 3,
  "valid_from": "2026-12-01",
  "valid_until": "2027-02-28"
}

Campo	Tipo	Obrigatório	Descrição
`code`	string alfanumérico (max 50)	sim	Código único por empresa. Convertido automaticamente para maiúsculas
`name`	string (max 255)	sim	Nome interno do cupom
`description`	string (max 1000)	não	Descrição opcional
`discount_type`	`percentage\|fixed`	sim	Tipo de desconto
`discount_value`	inteiro	sim	Para `percentage`: 1–100. Para `fixed`: valor em centavos
`max_redemptions`	inteiro (min 1)	não	Limite total de resgates. `null` = ilimitado
`max_cycles`	inteiro (min 1)	não	Aplica o desconto apenas nos primeiros N ciclos. `null` = aplica para sempre
`valid_from`	date (`YYYY-MM-DD`)	sim	Data de início da validade
`valid_until`	date após `valid_from`	não	Data de fim da validade. `null` = sem expiração

Resposta 201:

{
  "id": "019a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "code": "VERAO30",
  "name": "30% de desconto — Verão",
  "description": "Promoção de verão, primeiros 3 meses",
  "discount_type": "percentage",
  "discount_value": 30,
  "max_redemptions": 200,
  "redemptions_count": 0,
  "max_cycles": 3,
  "valid_from": "2026-12-01T00:00:00+00:00",
  "valid_until": "2027-02-28T23:59:59+00:00",
  "is_active": true,
  "created_at": "2026-06-25T12:00:00+00:00"
}

Atualizar cupom

PUT /api/v1/subscriptions/coupons/{uuid} — requer X-Client-ID + X-API-Key. Campos editáveis: name, description, max_redemptions, max_cycles, valid_until, is_active. code, discount_type e discount_value são imutáveis após a criação.

Listar e deletar cupons

Método	Rota	Descrição
`GET`	`/api/v1/subscriptions/coupons`	Lista todos os cupons
`GET`	`/api/v1/subscriptions/coupons/{uuid}`	Detalha um cupom
`DELETE`	`/api/v1/subscriptions/coupons/{uuid}`	Soft-delete