Skip to navigation

Subscriptions and billing

Sell, change and end your customers' plans, and follow what your card is charged.

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.

from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.reception.subscriptions.assign(
"8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7",
tier_id="smbtier_4401k8r2c6hxe9tq3vz7m5wd1nb0",
billing_period="annual_period",
idempotency_key="assign-8f1c2a7e-2026-11-03",
)

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_tier and the date in pending_downgrade_at_unix.

To keep the workspace on its current tier, drop the scheduled downgrade with subscriptions.cancel_pending_downgrade.

elevenlabs.reception.subscriptions.change(
"8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7",
tier_id="smbtier_4401k8r2d3pfw8ys6bq2n9ja7kc5",
)
elevenlabs.reception.subscriptions.cancel_pending_downgrade("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")

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.

elevenlabs.reception.subscriptions.unassign("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")
elevenlabs.reception.subscriptions.restore("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")

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:

StatusMeaning
paidThe card was charged.
openThe card is still being retried. pay_url links to a payment page.
voidRetries ran out and the workspace’s plan was ended.

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.

page = elevenlabs.reception.billing.list_invoices(page_size=25)
for invoice in page.invoices:
print(invoice.workspace_name, invoice.status, invoice.amount_cents / 100, invoice.currency)
detail = elevenlabs.reception.billing.get_invoice(page.invoices[0].invoice_id)
for line in detail.lines:
print(line.kind, line.description, line.amount_cents)

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.

upcoming = elevenlabs.reception.billing.list_upcoming_payments()
for payment in upcoming.payments:
print(
payment.workspace_name,
payment.subscription.billing_period_end_unix,
payment.plan_usd + payment.overage_so_far_usd,
)