Subscriptions

Overview

Subscriptions connect customers to plans and drive the billing lifecycle. BoxBilling supports trials, pay-in-advance/arrear billing, calendar and anniversary billing, plan upgrades/downgrades, pause/resume, bulk operations, and flexible termination options.

Subscription states

              ┌──────────┐
              │ PENDING   │
              └────┬──────┘
                   │ activate
              ┌────▼──────┐
         ┌────│  ACTIVE   │◄───┐
         │    └──┬────────┘    │
         │       │             │ resume
    cancel│      │ pause       │
         │    ┌──▼─────┐      │
         │    │ PAUSED  │──────┘
         │    └─────────┘
         │
   ┌─────▼────┐       ┌────────────┐
   │ CANCELED  │       │ TERMINATED │
   └───────────┘       └────────────┘

Any state except terminated can transition to terminated via the terminate (DELETE) endpoint.

Status	Description
pending	Created but not yet activated
active	Currently billing
paused	Billing suspended; can be resumed
canceled	Soft-canceled, will terminate at period end
terminated	Fully ended

Create a subscription

curl -X POST /v1/subscriptions/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "sub_001",
    "customer_id": "cust-uuid",
    "plan_id": "plan-uuid",
    "billing_time": "calendar",
    "pay_in_advance": true,
    "trial_period_days": 14,
    "on_termination_action": "generate_invoice"
  }'

Billing time modes

Mode	Description
calendar	Billing periods align to calendar boundaries (1st of month, start of week, etc.)
anniversary	Billing periods align to the subscription start date

Pay-in-advance vs pay-in-arrear

Mode	When invoiced	Use case
Pay-in-advance (pay_in_advance: true)	At the start of each billing period	SaaS subscriptions
Pay-in-arrear (pay_in_advance: false)	At the end of each billing period	Usage-heavy products

Activate a subscription

Pending subscriptions must be explicitly activated:

POST /v1/subscriptions/{subscription_id}/activate

Once activated, the subscription moves to active status and started_at is recorded.

Trials

When trial_period_days > 0, the subscription enters a trial period. During the trial:

• No invoices are generated
• The subscription is marked as active
• When the trial ends, the system processes the transition via the process_trial_expirations background task (runs hourly)

If pay_in_advance is enabled, the first invoice is generated when the trial ends.

Plan changes

Preview a plan change

Before executing a plan change, preview the financial impact:

POST /v1/subscriptions/{subscription_id}/change_plan_preview
{
  "plan_id": "new-plan-uuid"
}

Returns a price comparison and proration details so the customer can review before confirming.

Upgrades (immediate)

PUT /v1/subscriptions/{subscription_id}
{
  "plan_id": "new-plan-uuid"
}

When upgrading with pay_in_advance:

1. A credit note is generated for the remaining period on the old plan
2. A prorated invoice is generated for the new plan

Downgrades (end of period)

Downgrades are scheduled to take effect at the next billing period boundary:

1. The previous_plan_id is set to the new plan
2. downgraded_at timestamp is recorded
3. The process_pending_downgrades task (runs daily) executes the switch

Pause and resume

Pause

POST /v1/subscriptions/{subscription_id}/pause

Pausing a subscription suspends billing. The subscription moves to paused status and paused_at is recorded. No invoices are generated while paused.

Resume

POST /v1/subscriptions/{subscription_id}/resume

Resuming moves the subscription back to active and records resumed_at.

Cancellation vs termination

Cancel

POST /v1/subscriptions/{subscription_id}/cancel

Soft cancellation — the subscription remains active until the end of the current billing period, then transitions to canceled status.

Terminate

DELETE /v1/subscriptions/{subscription_id}?on_termination_action=generate_invoice

Immediate termination. The subscription is ended right away.

Termination actions

The on_termination_action parameter controls what happens financially when a subscription ends:

Action	Description
generate_invoice	Generate a final invoice for the period
generate_credit_note	Issue a credit note for the remaining period
skip	No financial action taken

This can be set at creation time (as a default) or passed at cancellation/termination.

Bulk operations

Perform operations on multiple subscriptions at once:

Endpoint	Description
POST /v1/subscriptions/bulk_pause	Pause multiple subscriptions
POST /v1/subscriptions/bulk_resume	Resume multiple subscriptions
POST /v1/subscriptions/bulk_terminate	Terminate multiple subscriptions

Each returns a BulkSubscriptionResponse with per-subscription results.

Usage and entitlements

Current usage

GET /v1/subscriptions/{subscription_id}/current_usage

Returns the current billing-period usage for all metered charges on the subscription.

Usage trend

GET /v1/subscriptions/{subscription_id}/usage_trend

Returns daily usage trend data for the subscription.

Usage thresholds

# Create a threshold
POST /v1/subscriptions/{subscription_id}/usage_thresholds

# List thresholds
GET /v1/subscriptions/{subscription_id}/usage_thresholds

Usage thresholds trigger alerts or actions (e.g., progressive billing) when usage reaches defined amounts.

Entitlements

GET /v1/subscriptions/{external_id}/entitlements

Returns the feature entitlements granted by the subscription’s plan.

Next billing date

GET /v1/subscriptions/{subscription_id}/next_billing_date

Returns the next billing date for the subscription, useful for displaying to customers.

Lifecycle timeline

GET /v1/subscriptions/{subscription_id}/lifecycle

Returns the full lifecycle timeline — a chronological list of events (creation, activation, pauses, plan changes, cancellation, etc.) for audit and debugging.

Charge models

Each charge on a plan uses one of the following charge models:

Model	Description
standard	Fixed price per unit
graduated	Tiered pricing — different rates for different quantity ranges
volume	Volume pricing — the tier reached applies to all units
package	Price per package of units
percentage	Percentage of a base amount
graduated_percentage	Tiered percentage rates
dynamic	Dynamically calculated pricing
custom	Custom pricing logic

Webhooks

The following webhook events are sent during the subscription lifecycle:

Event	Trigger
subscription.created	New subscription created
subscription.started	Subscription activated
subscription.plan_changed	Plan upgrade or downgrade executed
subscription.trial_ended	Trial period expired
subscription.canceled	Subscription canceled
subscription.terminated	Subscription terminated

API endpoints

Method	Path	Description
GET	/v1/subscriptions/	List subscriptions
POST	/v1/subscriptions/	Create a subscription
GET	/v1/subscriptions/{subscription_id}	Get subscription details
PUT	/v1/subscriptions/{subscription_id}	Update a subscription
DELETE	/v1/subscriptions/{subscription_id}	Terminate a subscription
POST	/v1/subscriptions/{subscription_id}/activate	Activate a pending subscription
POST	/v1/subscriptions/{subscription_id}/pause	Pause a subscription
POST	/v1/subscriptions/{subscription_id}/resume	Resume a paused subscription
POST	/v1/subscriptions/{subscription_id}/cancel	Cancel a subscription
GET	/v1/subscriptions/{subscription_id}/lifecycle	Get lifecycle timeline
GET	/v1/subscriptions/{subscription_id}/next_billing_date	Get next billing date
POST	/v1/subscriptions/{subscription_id}/change_plan_preview	Preview plan change
GET	/v1/subscriptions/{subscription_id}/current_usage	Get current usage
GET	/v1/subscriptions/{subscription_id}/usage_trend	Get usage trend
POST	/v1/subscriptions/{subscription_id}/usage_thresholds	Create usage threshold
GET	/v1/subscriptions/{subscription_id}/usage_thresholds	List usage thresholds
GET	/v1/subscriptions/{external_id}/entitlements	Get entitlements
POST	/v1/subscriptions/bulk_pause	Bulk pause subscriptions
POST	/v1/subscriptions/bulk_resume	Bulk resume subscriptions
POST	/v1/subscriptions/bulk_terminate	Bulk terminate subscriptions