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.
Background
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_createdA new invoice is generated for the creator's Subscriby tier.billing.invoice_paidAn invoice is paid in full.billing.invoice_overdueA creator invoice is marked overdue.billing.payment_failedA recurring charge against the creator's payment method fails.billing.trial_endingThe creator's platform trial is about to convert and take its first payment.billing.grace_period_warningThe creator is approaching automatic lockdown for an unpaid invoice.billing.account_lockedThe account hits its past-due lockdown.billing.tier_upgradedThe creator upgrades to a higher Subscriby tier.billing.tier_downgradedThe creator downgrades to a lower Subscriby tier.billing.tier_cancelledThe creator cancels their Subscriby subscription.How is this guide?
Last updated on