Handle Plan Upgrades and Downgrades

Plan changes in Brilo are handled through a single endpoint — Switch Plan. Brilo automatically calculates proration and applies any credits or charges for the unused portion of the current period.

What Happens When a Plan Changes

Upgrade

When a customer moves to a more expensive plan:

1. The current plan is ended at the changeover point
2. A new subscription on the new plan begins immediately
3. A prorated charge is added to the customer's next invoice for the difference in plan cost

Current plan:  Starter ($29/month)
New plan:      Professional ($99/month)

Billing period: May 1 – Jun 1 (31 days)
Change date:    May 12 (day 11 of 31)
Days remaining: 20

Prorated difference = ($99 - $29) × (20/31) = $45.16 charged

Downgrade

When a customer moves to a cheaper plan:

1. The current plan ends at the changeover point
2. A new subscription on the cheaper plan begins
3. A prorated credit is issued for the overpaid portion of the current period

Current plan:  Professional ($99/month)
New plan:      Starter ($29/month)

Billing period: May 1 – Jun 1 (31 days)
Change date:    May 12 (day 11 of 31)
Days remaining: 20

Credit = ($99 - $29) × (20/31) = $45.16 credited to account

The credit is automatically applied to the next invoice.

Switching a Plan

curl -X POST https://api.brilo.tech/api/subscriptions/sub_123/switch_plan/ \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "new_plan_id": "plan_professional",
    "invoicing_behavior": "add_to_next_invoice",
    "usage_behavior": "transfer_to_new_subscription"
  }'

See Switch Plan for the full parameter reference.

Key Parameters

Choosing Invoicing Behavior

add_to_next_invoice (recommended for upgrades)

The prorated charge or credit is applied to the next scheduled invoice. Less disruptive — the customer sees a single adjusted invoice at the end of the month.

invoice_now

A new invoice is generated immediately with just the proration charge. Useful if you want the customer to pay the difference right away when upgrading.

Choosing Usage Behavior

transfer_to_new_subscription (recommended)

Usage accumulated so far in the period carries forward into the new subscription. The customer doesn't lose their free tier or accrue duplicate charges.

reset_usage

Usage resets to zero on the new subscription. Use this only when the new plan has completely different metrics or the old usage shouldn't apply.

Implementation Pattern

A typical upgrade flow from your application:

def upgrade_customer(customer_id, new_plan_id):
    # 1. Get the customer's current subscription
    customer = brilo.get_customer(customer_id)
    subscription = customer["subscriptions"][0]
    subscription_id = subscription["subscription_id"]

    # 2. Switch to the new plan
    response = requests.post(
        f"{BRILO_BASE_URL}/api/subscriptions/{subscription_id}/switch_plan/",
        headers={"X-API-KEY": BRILO_API_KEY},
        json={
            "new_plan_id": new_plan_id,
            "invoicing_behavior": "add_to_next_invoice",
            "usage_behavior": "transfer_to_new_subscription"
        }
    )
    response.raise_for_status()

    # 3. Update your database
    db.users.update(
        {"customer_id": customer_id},
        {"$set": {"plan": new_plan_id}}
    )

    return response.json()

Handling Entitlements After a Change

Entitlements update immediately when the plan changes. As soon as switch_plan returns successfully, subsequent calls to Check Feature Access will reflect the new plan.

If you cache entitlement responses in your application, invalidate the cache for this customer on a successful plan change.

Immediate vs. End-of-Period Changes

By default, plan changes take effect immediately. If you want to schedule a change for the end of the current billing period (so the customer finishes out what they've paid for), set effective_date to the subscription's end date:

{
  "new_plan_id": "plan_starter",
  "effective_date": "2024-06-01",
  "invoicing_behavior": "add_to_next_invoice"
}

This is common for downgrades — let the customer keep their current plan until the end of the period they paid for.

Next Steps