Billing API
Manage the creator's own Subscriby tier. Webhook-observable today; REST deferred.
Dedicated REST endpoints for a creator's own Subscriby tier are deferred.
Mis-using them could brick production billing, so they intentionally ship
after the rest of the API stabilises. The billing.* webhook family is
already available for ops dashboards that watch for lockdown and payment
failures.
Ability
billing:read and billing:manage exist in the ability catalog today and are reserved for when the REST endpoints ship. Neither ability is enforced on any live route at the moment.
Planned endpoints
Not implemented yet — listed here so integrations can plan the migration:
GET /v1/billingPOST /v1/billing/upgradePOST /v1/billing/downgradePOST /v1/billing/cancelGET /v1/billing/payment-method
Today
Upgrade, downgrade, and cancel flow through the dashboard under Settings → Billing. The checkout experience is hosted by Stripe, so a REST shim would mostly be a passthrough — that's why it's low priority.
Observable via webhooks today
The billing.* family covers every state change a creator's Subscriby tier goes through. Subscribe a webhook endpoint with webhook-endpoint:manage and pick any of:
| Event | When |
|---|---|
billing.invoice_created | A new Subscriby invoice is raised for the creator's tier. |
billing.invoice_paid | A tier invoice settled successfully. |
billing.invoice_overdue | A tier invoice remains unpaid past its due date. |
billing.payment_failed | A tier charge attempt failed on the provider. |
billing.trial_ending | The platform trial is about to convert. Carries amount and hours_remaining. |
billing.grace_period_warning | The creator is approaching lockdown. Carries days_until_lockdown. |
billing.account_locked | Grace period elapsed and the account is locked out of paid features. |
billing.tier_upgraded | The creator upgraded their tier. |
billing.tier_downgraded | The creator downgraded. |
billing.tier_cancelled | The creator cancelled their paid tier. |
Each event requires billing:read on the subscribing endpoint's owning token.
Related
- Webhook events — polling view of recent
billing.*deliveries. - Ability catalog
How is this guide?