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

# Subscriptions - Pause and Coupons

## Pause and resume

Pausing a subscription stops it from generating invoices until you resume it. Existing invoices stay as they are.

```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 } }'
```

To resume, send the same body to `PUT /subscription/unpause`. The subscription goes back to `active` and, if the next charge fell due during the pause, it becomes due now: the invoice is issued in the next billing run.

Both respond with `201` and `{ "subscription": { ... } }`, and trigger the `subscription.updated` webhook.

Only `active`, `overdue` or `trial` subscriptions can be paused, and only `paused` ones can be resumed. In any other status, the API responds with **400** `INVALID_STATE_ERROR`. To end a subscription, cancel it with `POST /subscription/cancel`.

## Coupons

A coupon gives a discount on a subscription's invoices (`type: "subscription"`) or on a payment link (`type: "payment_link"`).

### Creating a coupon

```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"
  }'
```

| Field | What it does |
| --- | --- |
| `code` | The code the customer types, up to 50 characters |
| `percentage` | The discount as a percentage of the invoice amount |
| `value` | A fixed discount, in cents, added to the percentage discount (`0` for percentage only) |
| `duration` | How many of the subscription's invoices get the discount (optional; without it, all of them) |
| `max_usages` | How many times, in total, the coupon can be used (optional) |
| `expiration_date` | Until when the coupon can be applied (optional) |

The discount never exceeds the invoice amount. To deactivate a coupon, send `PUT /coupons/{id}` with `"status": "canceled"`.

### Applying it to a subscription

When creating the subscription, send the codes in `coupon_codes`:

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

On an existing subscription, apply it by the coupon id; the discount applies to the next invoices:

```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` lists the subscription's coupons, with the `status` of each: `unused` (not used yet), `using` (already gave a discount and invoices remain), `used` (duration finished) or `canceled`.
- `PUT /subscription/coupons/{id}/cancel` removes the coupon from the subscription (the `id` is the coupon's id on the subscription, from the list above). Invoices that already got the discount do not change.

Each discount appears as a negative item on the invoice, `Cupom <code>`.