Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

fix(billing): clarify averaged usage messaging (#47181)

Pamela Chiad549e1f16b29
diff --git a/apps/docs/content/guides/platform/billing-faq.mdx b/apps/docs/content/guides/platform/billing-faq.mdx
index 032103c704c..83906fe29cd 100644
--- a/apps/docs/content/guides/platform/billing-faq.mdx
+++ b/apps/docs/content/guides/platform/billing-faq.mdx
@@ -96,11 +96,11 @@ We currently do not support annual plans officially. However, you can do a [cred
#### What will happen when I exceed the Free Plan quota?
-You will be notified when you exceed the Free Plan quota. It is important to take action at this point. If you continue to exceed the limits without reducing your usage, service restrictions will apply. To avoid service restrictions, you have two options: reduce your usage or upgrade to a paid plan. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.
+You will be notified when you exceed the Free Plan quota. It is important to take action at this point. If you continue to exceed the limits, service restrictions will apply. To avoid service restrictions, you can [manage your usage](/docs/guides/platform/manage-your-usage) or upgrade to a paid plan. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.
#### What will happen when I exceed the Pro Plan quota and have the spend cap on?
-You will be notified when you exceed your Pro Plan quota. To unblock yourself, you can toggle off your spend cap in your [organization's billing settings](/dashboard/org/_/billing) to pay for over-usage beyond the Pro plans limits. If you continue to exceed the limits without reducing your usage or turning off the spend cap, restrictions will apply. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.
+You will be notified when you exceed your Pro Plan quota. To unblock yourself, you can toggle off your spend cap in your [organization's billing settings](/dashboard/org/_/billing) to pay for over-usage beyond the Pro plans limits. If you continue to exceed the limits without managing your usage or turning off the spend cap, restrictions will apply. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.
#### How do I scale beyond the limits of my Pro Plan?
diff --git a/apps/docs/content/guides/platform/database-size.mdx b/apps/docs/content/guides/platform/database-size.mdx
index f2e63601fb7..bf241988418 100644
--- a/apps/docs/content/guides/platform/database-size.mdx
+++ b/apps/docs/content/guides/platform/database-size.mdx
@@ -114,6 +114,14 @@ Free Plan projects enter [read-only](#read-only-mode) mode when your **database
- [Upgrade to the Pro Plan](/dashboard/org/_/billing) to increase the database size quota. [Disable the Spend Cap](https://app.supabase.com/org/_/billing?panel=costControl) if you want your Pro instance to auto-scale beyond the 8 GB disk size limit.
- [Disable read-only mode](#disabling-read-only-mode) and reduce your database size.
+### Fair use database size restriction
+
+Separate from the per-project read-only mode above, your organization can be placed under a [Fair Use](/docs/guides/platform/billing-faq#fair-use-policy) service restriction (requests return a `402` status code) when its database size exceeds the plan quota. This quota is evaluated **per organization**, summing the database size across all of your projects.
+
+Importantly, it is based on the **average daily database size over the billing period**, not the live size. Reducing your database size does not immediately lift the restriction: the average stays elevated until enough lower-usage days accumulate, and it effectively resets when your billing cycle rolls over. This is why a project that is well under the limit today can still be restricted, as its average across the period is still over.
+
+To resolve it, upgrade your plan or disable your Spend Cap to lift the restriction immediately. Otherwise, reduce your database size and wait for the new billing cycle, at which point the average restarts from your current size.
+
### Read-only mode
In some cases Supabase may put your database into read-only mode to prevent your database from exceeding the billing or disk limitations.
diff --git a/apps/docs/content/guides/platform/manage-your-usage/egress.mdx b/apps/docs/content/guides/platform/manage-your-usage/egress.mdx
index 4469a946e73..b05dbb00359 100644
--- a/apps/docs/content/guides/platform/manage-your-usage/egress.mdx
+++ b/apps/docs/content/guides/platform/manage-your-usage/egress.mdx
@@ -63,6 +63,12 @@ Cached and uncached egress have independent quotas and independent pricing. Cach
Egress is charged by gigabyte. Charges apply only for usage exceeding your subscription plan's quota. This quota is called the Unified Egress Quota because it can be used across all services (Database, Auth, Storage etc.).
+<Admonition type="note">
+
+Egress accumulates over the billing cycle and resets at the start of the next cycle. Usage that has already been served cannot be reduced retroactively, so the optimizations below lower future egress only. If your organization is restricted for egress, the restriction clears at the start of the next billing cycle, or immediately if you upgrade your plan or disable your Spend Cap.
+
+</Admonition>
+
### Usage on your invoice
Usage is shown as "Egress GB" and "Cached Egress GB" on your invoice.
diff --git a/apps/docs/content/guides/platform/manage-your-usage/storage-size.mdx b/apps/docs/content/guides/platform/manage-your-usage/storage-size.mdx
index eca3dd5544c..b2dfc468eff 100644
--- a/apps/docs/content/guides/platform/manage-your-usage/storage-size.mdx
+++ b/apps/docs/content/guides/platform/manage-your-usage/storage-size.mdx
@@ -12,6 +12,8 @@ You are charged for the total size of all assets in your buckets.
Storage size is charged by Gigabyte-Hours (GB-Hrs). 1 GB-Hr represents the use of 1 GB of storage for 1 hour.
For example, storing 10 GB of data for 5 hours results in 50 GB-Hrs (10 GB × 5 hours).
+Because usage is measured in GB-Hrs, your Storage size for quota and billing is effectively the average across the billing period, not the live size. For example, storing 20 GB for the first half of the month and 0 GB for the second half averages to 10 GB. This means reducing storage late in the cycle lowers the average only gradually, so it may not immediately clear a restriction until the next billing cycle begins.
+
### Usage on your invoice
Usage is shown as "Storage Size GB-Hrs" on your invoice.
diff --git a/apps/studio/components/interfaces/Organization/BillingSettings/Restriction.tsx b/apps/studio/components/interfaces/Organization/BillingSettings/Restriction.tsx
index dc9ddcb8c46..11b2bf2fb27 100644
--- a/apps/studio/components/interfaces/Organization/BillingSettings/Restriction.tsx
+++ b/apps/studio/components/interfaces/Organization/BillingSettings/Restriction.tsx
@@ -147,9 +147,10 @@ export const Restriction = () => {
<span className="text-foreground">
{dayjs(org.restriction_data['grace_period_end']).format('DD MMM, YYYY')}
</span>
- . Fair Use Policy applies now. Stay below your plan's quota or{' '}
- {org.plan.id === 'free' ? 'upgrade your plan' : 'disable spend cap'} if you expect to
- exceed it. If you exceed your quota, requests will respond with a 402 status code.
+ . Fair Use Policy applies now. If your organization is over its quota, your projects
+ can be restricted and requests will respond with a 402 status code.{' '}
+ {org.plan.id === 'free' ? 'Upgrade your plan' : 'Disable spend cap'} if you expect to
+ exceed your plan's quota.
</p>
<div className="flex items-center gap-x-2 mt-3">
<Button key="upgrade-button" asChild variant="default">
@@ -187,9 +188,9 @@ export const Restriction = () => {
serve requests and will respond with a 402 status code. You have exceeded your plan's
quota{violationLabels && ` ${violationLabels}`}.{' '}
{org.plan.id === 'free' ? 'Upgrade your plan' : 'Disable spend cap'} to lift
- restrictions immediately, or wait until your quota refills at the start of your next
- billing period. Note that there may be a short delay after your billing period resets
- before restrictions are fully lifted.
+ restrictions immediately, or wait until the start of your next billing period. Note
+ that there may be a short delay after your billing period resets before restrictions
+ are fully lifted.
</p>
<div className="flex items-center gap-x-2 mt-3">
<Button key="upgrade-button" asChild variant="default">
diff --git a/apps/studio/components/interfaces/Organization/restriction.constants.tsx b/apps/studio/components/interfaces/Organization/restriction.constants.tsx
index 3e917be7874..26a440ffabd 100644
--- a/apps/studio/components/interfaces/Organization/restriction.constants.tsx
+++ b/apps/studio/components/interfaces/Organization/restriction.constants.tsx
@@ -12,8 +12,11 @@ export const RESTRICTION_MESSAGES = {
return (
<>
You have a grace period until{' '}
- <TimestampInfo className="text-sm" utcTimestamp={date} label={label} /> to bring usage
- back under quota. <InlineLink href={`/org/${slug}/usage`}>Review usage</InlineLink>
+ <TimestampInfo className="text-sm" utcTimestamp={date} label={label} />. After that, your
+ projects will be restricted while your organization is over quota.{' '}
+ <InlineLink href={`/org/${slug}/usage`}>Review usage</InlineLink> or{' '}
+ <InlineLink href={`/org/${slug}/billing`}>manage your plan</InlineLink> to avoid
+ restrictions.
</>
)
},