Billing and suspension
What happens when a payment fails, the timeline from a missed payment to an offline workspace, how to restore access, and why your data is never deleted automatically.
Billing is per organization (workspace). When a payment fails, CapyDB does not delete anything and does not cut you off at once: access narrows in steps, each one announced in advance, and paying restores everything immediately.
When a payment fails
Your billing provider (Polar, or Vercel for Marketplace installations) retries the charge and emails you about it. During that time the subscription is past due:
- Your databases, previews and K/V stores keep running and serving your applications.
- New databases, previews and K/V stores cannot be created until the payment succeeds, and an ephemeral database cannot be claimed into the workspace.
- The dashboard shows a banner with the date the grace period ends.
The grace period is 30 days from the day the subscription became past due.
When the subscription lapses
The subscription counts as lapsed when any of these happens:
- the payment is still outstanding when the grace period ends,
- your billing provider gives up collecting (the subscription is revoked or unpaid; for Vercel, the invoice becomes overdue),
- a canceled subscription reaches the end of the period you paid for,
- the Vercel integration is uninstalled.
A lapsed workspace that still has databases or K/V stores is suspended, and access then narrows on a fixed timeline. You get an email at each step, sent to the workspace's billing email (or to its admins when none is set) and to any extra billing recipients in the workspace's email preferences. These notices cannot be switched off.
| When | What changes | What still works |
|---|---|---|
| Day 0 - suspended | Creating databases, previews and K/V stores, and changing projects (imports, restores, credential rotation, extensions, upgrades, integrations) are refused. | Your databases and K/V stores keep serving your applications. Studio (read-only), exports, backups, deleting projects, and every read through the API and dashboard. |
| Day 7 - read-only | Every database becomes read-only: queries that read data work, writes are refused. | Everything above except writes. |
| Day 14 - offline | Databases and K/V stores go offline. Connections are refused with an error naming the billing page (SQLSTATE 08004), K/V requests are refused on both the REST and Redis ports, and Studio is unavailable. K/V stores are stopped with their data kept and report state: stopped, stopped_reason: org_suspended. | Exports, backups, deleting projects, and API reads. |
A client connecting to an offline database sees:
FATAL: this CapyDB organization is suspended for non-payment and its databases are offline - update billing at https://capydb.dev/dashboard/settings/billingThe dashboard's billing banner always shows which step the workspace is at and the date of the next one.
Your data is never deleted automatically
No step of the timeline deletes data, and an offline workspace stays offline rather than being removed. You can take a backup or an export at every step, including while offline, so you can always get your data out. Deleting a project is always your decision.
Restoring access
Pay the outstanding invoice or start a subscription from Settings → Billing in the dashboard (it works while the workspace is suspended). As soon as the payment is recorded:
- the suspension is lifted and provisioning and project changes work again,
- read-only databases accept writes again within a few minutes,
- offline databases accept connections again within a minute and start on the first connection, and stopped K/V stores start again on their own,
- you get an email confirming the workspace is active.
Your databases keep the size of the plan you last paid for throughout; a lapse never shrinks them. When you come back on a different plan, the new plan's limits apply.
Reading it from the API
GET /v1/organizations/{orgID} carries the same state the banner shows:
| Field | Meaning |
|---|---|
billing_status | The subscription status as the billing provider reports it (active, trialing, past_due, canceled, revoked, unpaid, inactive) |
billing_status_since | When billing_status last changed - the 30-day past-due grace period is measured from here |
billing_standing | good, grace (past due, within the grace period), lapsed or none (no paid plan) |
billing_grace_ends_at | While in grace: when the workspace lapses unless a payment succeeds |
suspended_at, suspended_reason | When and why the current suspension began; billing_lapsed is lifted by a successful payment |
suspension_rung | 0 suspended (day 0), 1 read-only (day 7), 2 offline (day 14); 0 when not suspended |
suspension_rung_since, suspension_next_rung_at | When the current step began, and when the next one is due if nothing changes |
Storage above the plan
Usage-based storage billing is being prepared and is not live: nothing is billed for storage today, and storage_overage_billing below is null for every organization.
When it is switched on, storage above what the plan includes - summed across the organization's projects - is billed per billing period on that period's peak, in whole gigabytes rounded up (1 byte over is 1 GB). Because the peak is billed, deleting data late in a period lowers the next period's figure, not this one's. Only subscriptions paid through CapyDB's own checkout are metered: trials, past-due subscriptions and Vercel Marketplace billing are not.
GET /v1/organizations/{orgID}/usage then carries storage_overage_billing for the current period:
| Field | Meaning |
|---|---|
period_end | When the period ends and its overage is invoiced |
reported_gigabytes | The peak already reported for billing this period |
projected_gigabytes | What the period bills if storage stays where it is |
Changing to a smaller plan
A move to a plan with a smaller storage limit is refused while any project stores more than the new limit, because the database would be left with a full disk. The error names each project and how much to free; delete data or projects, then change the plan again.