---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# Assinaturas - Pausa e Cupons

## Pausar e reativar

Pausar uma assinatura para de gerar faturas para ela até você reativar. As faturas que já existem continuam como estão.

```bash
curl -X PUT https://payments.cefis.com.br/api/v1/subscription/pause \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "subscription": { "id": 205465 } }'
```

Para reativar, o mesmo corpo em `PUT /subscription/unpause`. A assinatura volta a `active` e, se a próxima cobrança venceu durante a pausa, ela passa a ser agora: a fatura sai na próxima rotina de cobrança.

As duas respostas são `201` com `{ "subscription": { ... } }` e disparam o webhook `subscription.updated`.

Só pausa a assinatura `active`, `overdue` ou `trial`, e só reativa a `paused`. Nos outros status, a API responde **400** `INVALID_STATE_ERROR`. Para encerrar uma assinatura, cancele com `POST /subscription/cancel`.

## Cupons

Um cupom dá desconto nas faturas de uma assinatura (`type: "subscription"`) ou num link de pagamento (`type: "payment_link"`).

### Criando um cupom

```bash
curl -X POST https://payments.cefis.com.br/api/v1/coupons \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "subscription",
    "name": "Black Friday",
    "code": "BLACK20",
    "percentage": 20,
    "value": 0,
    "duration": 3,
    "max_usages": 100,
    "expiration_date": "2026-11-30"
  }'
```

| Campo | O que faz |
| --- | --- |
| `code` | O código que o cliente digita, até 50 caracteres |
| `percentage` | O desconto em porcentagem do valor da fatura |
| `value` | Um desconto fixo, em centavos, somado ao da porcentagem (`0` para só a porcentagem) |
| `duration` | Em quantas faturas da assinatura o desconto vale (opcional; sem ele, em todas) |
| `max_usages` | Quantas vezes, no total, o cupom pode ser usado (opcional) |
| `expiration_date` | Até quando o cupom pode ser aplicado (opcional) |

O desconto nunca passa do valor da fatura. Para desativar um cupom, `PUT /coupons/{id}` com `"status": "canceled"`.

### Aplicando numa assinatura

Na criação da assinatura, mande os códigos em `coupon_codes`:

```json
{
  "customer": { "id": 315968 },
  "plan": { "id": 413 },
  "method": "credit",
  "coupon_codes": ["BLACK20"]
}
```

Numa assinatura que já existe, aplique pelo id do cupom; o desconto entra nas próximas faturas:

```bash
curl -X POST https://payments.cefis.com.br/api/v1/subscriptions/205465/coupons \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "coupon_id": 77 }'
```

- `GET /subscriptions/{id}/coupons` lista os cupons da assinatura, com o `status` de cada um: `unused` (ainda não usado), `using` (já deu desconto e ainda restam faturas), `used` (acabou a duração) ou `canceled`.
- `PUT /subscription/coupons/{id}/cancel` tira o cupom da assinatura (o `id` é o do cupom na assinatura, da listagem acima). As faturas que já tiveram desconto não mudam.

Cada desconto aparece como um item negativo na fatura, `Cupom <código>`.