Subscriptions and billing
Each customer workspace can have one subscription to a tier you sell. Your reseller card pays every workspace’s invoices. A workspace’s current subscription is in the subscription field of workspaces.list, together with has_payment_issue.
Assign a plan
Subscribe a workspace that has no plan yet. billing_period is monthly_period (the default) or annual_period.
Send an idempotency_key you generate on every assignment or change. If a request times out, retrying it with the same key cannot subscribe or charge the workspace twice.
Assigning or changing a plan is refused while has_payment_issue is true. Show the unpaid invoice to your customer, or pay it through its pay_url, before you retry.
Change a plan
subscriptions.change takes the same body as assign.
- An upgrade applies immediately.
- A downgrade or a move to a tier at the same level takes effect at the end of the billing period. Until then, the subscription shows the new tier in
pending_downgrade_tierand the date inpending_downgrade_at_unix.
To keep the workspace on its current tier, drop the scheduled downgrade with subscriptions.cancel_pending_downgrade.
When a downgrade takes effect, receptionists and phone numbers beyond the new plan’s limits are deactivated, and team members beyond its team size are suspended.
End a plan
subscriptions.unassign ends the subscription at the end of the current billing period. Until then, cancel_at_unix shows when it ends, and subscriptions.restore undoes the cancellation so the plan renews normally.
Invoices
Each charge to your card pays one workspace’s invoice. billing.list_invoices returns them newest first, one page at a time. An invoice’s status is one of:
billing.get_invoice adds the invoice’s lines. A line with a negative amount_cents is a proration credit, and the lines always add up to the charge.
Upcoming payments
billing.list_upcoming_payments estimates each workspace’s next renewal, soonest first. plan_usd is the plan the renewal charges up front, which is the downgraded tier’s price when a downgrade is scheduled. overage_so_far_usd is this period’s usage beyond the included minutes so far. It is charged at the renewal and keeps growing until then.