Subscriptions

A subscription links a customer to a plan and drives the billing cycle. It controls when invoices are generated, what the customer is billed for, and what they're entitled to access.

Subscription Lifecycle

Created → Active → [Paused] → Active → Canceled
                                ↓
                             Invoiced each period

Creating a Subscription

Via Dashboard

1. Go to Customers → select a customer
2. Click + Add Subscription
3. Choose a plan, start date, billing frequency, and add-ons
4. Click Create

Via API

curl -X POST https://api.brilo.app/subscriptions \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "plan_id": "plan_starter",
    "start_date": "2024-05-01",
    "auto_renew": true
  }'

See Create a Subscription for the full parameter list.

Billing Frequency

How often a customer is invoiced:

The billing period starts on start_date and renews at the same day each period.

Payment Timing

In Arrears (Default)

The customer is charged at the end of the billing period for the usage that occurred during it. This is the fairest model for usage-based pricing — you only charge for what was actually consumed.

May 1 – Jun 1: Usage period
Jun 1: Invoice generated and charged

In Advance

The customer is charged at the start of the billing period. Common for flat-fee or prepaid plans.

May 1: Invoice generated and charged
May 1 – Jun 1: Subscription period

Plan Changes

Upgrading

When a customer moves to a more expensive plan, they're charged a prorated amount for the remainder of the current billing period.

Old plan: Starter ($29/month)
New plan: Professional ($99/month)
Upgrade date: May 15 (day 15 of a 31-day period)
Days remaining: 16

Charge = $99 × (16/31) - $29 × (16/31) = $36.13

Downgrading

When a customer moves to a cheaper plan, a prorated credit is applied to their account.

Old plan: Professional ($99/month)
New plan: Starter ($29/month)
Downgrade date: May 15 (day 15 of a 31-day period)
Days remaining: 16

Credit = ($99 - $29) × (16/31) = $36.13

Use the Switch Plan endpoint to handle upgrades and downgrades.

Cancellations

Cancellation Timing Options

curl -X POST https://api.brilo.app/subscriptions/sub_123/cancel \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "flat_fee_behavior": "charge_prorated",
    "bill_usage": true,
    "invoicing_behavior": "add_to_next_invoice"
  }'

See Cancel a Subscription for all options.

Add-Ons

Add-ons attach to an existing subscription to add charges on top of the base plan.

Attaching an Add-On

curl -X POST https://api.brilo.app/subscriptions/sub_123/addons/attach \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "addon_id": "addon_premium_support",
    "quantity": 1
  }'

Canceling an Add-On

curl -X POST https://api.brilo.app/subscriptions/sub_123/addons/cancel \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "addon_id": "addon_premium_support"
  }'

See Attach an Add-on and Cancel an Add-on.

Prepaid Units

Some plans include prepaid credits for a specific metric — for example, 100,000 tokens bought upfront. You can adjust the prepaid balance mid-cycle using the Change Prepaid Units endpoint.

curl -X POST https://api.brilo.app/subscriptions/sub_123/components/change-prepaid-units \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_id": "metric_tokens",
    "units": 50000
  }'

Auto-Renewal

When auto_renew is true (the default), the subscription automatically renews at the end of each billing period. When set to false, the subscription expires at the end of the current period.

Common use cases for auto_renew: false:

• Free trials with a defined end date
• Time-limited promotional access
• Annual subscriptions with manual renewal

Subscription Events (Webhooks)

Brilo emits events you can listen to via webhooks at each stage of the subscription lifecycle:

Querying Subscriptions

List all subscriptions

curl "https://api.brilo.app/subscriptions" \
  -H "X-API-KEY: your-api-key"

List subscriptions for a customer

curl "https://api.brilo.app/subscriptions?customer_id=cust_123" \
  -H "X-API-KEY: your-api-key"

Retrieve a specific subscription

curl "https://api.brilo.app/subscriptions/sub_123" \
  -H "X-API-KEY: your-api-key"

See List Subscriptions and Retrieve a Subscription.

Next Steps