billing.* events
The creator's own Subscriby subscription tier: trial conversion, invoices, payment failures, grace periods, lockdowns.
The creator's own Subscriby subscription tier: trial conversion, invoices, payment failures, grace periods, lockdowns. These events describe the creator's billing relationship with Subscriby itself, not their subscribers' billing. Useful for building ops dashboards that watch for accounts heading into lockdown.
| Event | Fires when |
|---|---|
billing.invoice_created | A new invoice is generated for the creator's Subscriby tier. |
billing.invoice_paid | An invoice is paid in full. |
billing.invoice_overdue | Stripe marks the creator's invoice uncollectible. Nothing fires merely because a due date passed. |
billing.payment_failed | A recurring charge against the creator's payment method fails. |
billing.trial_ending | The creator's platform trial is about to convert. Fires at each milestone on the reminder ladder. |
billing.grace_period_warning | The creator is approaching lockdown. Read days_until_lockdown; it varies by plan tier. |
billing.account_locked | The account reaches its tier's past-due lockdown: day 30 on a paid tier, day 7 on Free or an unconverted trial. New signups are blocked on the project's portal pages. |
billing.tier_upgraded | Creator upgrades to a higher Subscriby tier. |
billing.tier_downgraded | Creator downgrades to a lower tier. |
billing.tier_cancelled | Creator cancels their Subscriby subscription. |
Example envelope
{
"id": "evt_01HX...",
"type": "billing.account_locked",
"created_at": "2026-05-18T10:05:00Z",
"api_version": "2026-05-01",
"project_id": null,
"data": {
"creator_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
"past_due_since": "2026-04-18T00:00:00Z",
"locked_at": "2026-05-18T00:00:00Z"
}
}project_id is always null for billing.* events; these are account-level.
When you'd subscribe
The typical consumer is an internal ops dashboard or Slack room, not a subscriber-facing system. Subscriby also emails the creator via the existing notification channels for every one of these events.
Required ability
Tokens subscribing to billing.* events must carry billing:read at mint time. Writes (upgrade, downgrade, cancel) additionally need billing:manage.
Events
billing.invoice_created
A new invoice is generated for the creator's Subscriby tier.
billing.invoice_paid
An invoice is paid in full.
billing.invoice_overdue
A creator invoice is marked overdue.
billing.payment_failed
A recurring charge against the creator's payment method fails.
billing.trial_ending
The creator's platform trial is about to convert and take its first payment.
billing.grace_period_warning
The creator is approaching automatic lockdown for an unpaid invoice.
billing.account_locked
The account hits its past-due lockdown.
billing.tier_upgraded
The creator upgrades to a higher Subscriby tier.
billing.tier_downgraded
The creator downgrades to a lower Subscriby tier.
billing.tier_cancelled
The creator cancels their Subscriby subscription.
Compare with the current pages
How is this guide?