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.

Shell

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

Shell

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:

Shell

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>.