> Documentation index: https://firebase.google.com/docs/llms.txt

> [!WARNING]
> **Preview:** Spend cap budgets are available in **Preview**, which means that it isn't subject to any SLA or deprecation policy and could change in backwards-incompatible ways.

<br />

This page describes how to set up and manage ***spend cap budgets*** when your
Firebase project is on the Blaze pricing plan.

Spend cap budgets are available for the following select Firebase services:
Firebase AI Logic, Firebase App Hosting, Cloud Functions for Firebase, and Firebase Extensions.

> [!IMPORTANT]
> **Important:** **Spend caps are *not* "hard caps".** Due to latency in usage reporting, spend cap enforcement is ***not instantaneous*** and can be delayed by several minutes. Any cost overages incurred during this delay will be billed as normal.   
> Given this, you should set your budget slightly below your absolute limit, as well as consider spend caps as just one tool that can help you manage your costs and reduce the impact of large unexpected bills. Learn more about [additional alerting and logic options](https://firebase.google.com/docs/projects/billing/advanced-billing-alerts-logic.md.txt).

[Jump to instructions for configuring a spend cap](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#set-up-and-manage-spend-caps)

## Understand budgets

You can control your costs and avoid surprises on your bill by creating budgets
for Google Cloud Billing. ***Budgets*** are general monetary amounts
that you plan on spending each month, and they can either be
***alerts-only budgets*** or ***spend cap budgets***.

#### Alerts-only budgets

- If spending reaches set thresholds for your budget,
  then Cloud Billing ***sends email notifications***.

- Note the following:

  - Budget alerts *do **not*** pause services. They're intended to help you
    monitor your costs and to alert you so that you can take action,
    if needed. For example, you might consider
    [using budget notifications to disable billing on the project](https://docs.cloud.google.com/billing/docs/how-to/disable-billing-with-notifications).

  - When you upgrade to the Blaze pricing plan in the
    Firebase console, you're automatically prompted to set up an
    alerts-only budget.
    You can also manually
    [set up alerts-only budgets](https://firebase.google.com/docs/projects/billing/budget-alerts.md.txt) in the
    Google Cloud console.

#### Spend cap budgets *(this page)*

- If spending reaches set thresholds for your budget *for a specific service* ,
  then Cloud Billing ***sends email notifications***.

- If spending reaches 100% of your budget for that service,
  then Cloud Billing ***pauses that service for the rest of the month***.

- Note the following:

  - Spend caps budgets are only available for the following Firebase services:
    Firebase AI Logic, Firebase App Hosting, Cloud Functions for Firebase, and Firebase Extensions.

  - You can manually set up spend cap budgets
    in the Firebase console (as described on this page) or in the
    Google Cloud console.

  <br />

  - Before setting up a spend cap budget, review the [important information about spend cap budgets](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#about-spend-caps) later on this page.

  <br />

> [!NOTE]
> [All Firebase
> projects are actually Google Cloud projects](https://firebase.google.com/docs/projects/learn-more#firebase-cloud-relationship) behind the scenes, which means billing is shared across Firebase and Google Cloud and you can view the same project in both the Firebase console and the Google Cloud console.

## Overview of spend cap budgets

Before setting up a spend cap budget, review the information in this section,
which includes the list of [eligible services](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#eligible-services) and
possible [spend cap states](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#spend-cap-states).
We also recommend reviewing [limitations of spend cap budgets](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#limitations)
later on this page.

You can also find a list of
[FAQ about spend cap budgets](https://docs.cloud.google.com/billing/docs/how-to/budgets-spend-caps#faq)
in the Google Cloud documentation.

### Eligible services

Spend caps budgets can be set up for the following Firebase services:

- **Firebase AI Logic** : Set caps on access to *Gemini Developer API* or *Agent Platform Gemini API (formerly Vertex AI)*.
- **Firebase App Hosting** : Set caps on the underlying *Cloud Run* service.
- **Cloud Functions for Firebase** : Set caps on the underlying *Cloud Run functions* service.
- **Firebase Extensions** : Set caps on the underlying *Cloud Run functions* service.

We're working to add to this list of eligible services for spend cap budgets,
so check back on this list periodically.

> [!NOTE]
> **Note:** When you set a spend cap budget for one of the *underlying services* above, then that budget applies at the project-level and to any of the ways that you might interact with the service in your project. For example, if you set a budget on the Agent Platform Gemini API (formerly Vertex AI), then it also applies to any usage of that API in the project via Firebase SQL Connect, ADK, Genkit, etc. (not just usage via Firebase AI Logic).

### Spend cap states

A spend cap can be in one of the following states:

- **Configured** : Cloud Billing is actively monitoring your project's
  spending for a specific service based on your spend cap budget.

- **Enforced** : Your project's spending reached 100% of your set monthly
  budget *for that service* , so Cloud Billing enforced the spend cap. Any
  new usage of the service for the rest of the month is paused unless the
  enforced spend cap is explicitly lifted.

- **Lifted** : Cloud Billing had enforced the spend cap (and paused any new
  usage of the applicable service), but the enforced spend cap was explicitly
  lifted to resume the service.

  While in the **Lifted** state, the service runs with no spend limit for the
  remainder of the month unless you reconfigure or increase the cap. At the
  start of the next month, the original spend cap budget automatically
  re-enables.

> [!NOTE]
> **Note:** Modifying any spend cap configuration (even renaming the budget in the Google Cloud console) transitions the spend cap back to the **Configured** state. If your monthly spending already meets or exceeds the budget threshold, the cap triggers and enforces immediately.

If you do *not* lift an enforced spend cap, the service will remain paused for
the current month *only*. Then, at the beginning of the next month, the enforced
spend cap will automatically reset and the service will resume.

## Set up and manage spend caps

> [!NOTE]
> **Note:** Before setting up a spend cap budget, review the [overview of spend cap budgets](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#about-spend-caps) earlier on this page.

1. [**Configure a spend cap budget.**](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#configure-spend-cap-budget)

   Configure a spend cap budget so that Cloud Billing can start actively
   monitoring your project's spending for a specific service.

2. [**Understand alerts and spend cap enforcement.**](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#alerts-and-enforcement)

   If your project's spending reaches certain thresholds of your monthly
   budget *for that service* , Cloud Billing sends alert emails and enforces
   the spend cap. *Enforcement* means any new usage of that service is paused
   for the rest of that month.

3. [**Optionally lift an enforced spend cap (or increase its budget).**](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#lift-spend-cap)

   If you want to resume usage for a paused service that month (either with
   no limit or under a higher budget), you need to explicitly lift the enforced
   spend cap.

#### Required permissions

To set up and manage a spend cap budget, you need admin-level access to the
project and its linked Cloud Billing account. Any of the following options
grant you the required permissions:

- **Option 1** :
  [*Billing Account Administrator* role](https://docs.cloud.google.com/billing/docs/how-to/billing-access#billing.admin)
  on the Cloud Billing account linked to the project

- **Option 2** :
  [*Project Owner* role](https://docs.cloud.google.com/resource-manager/docs/access-control-proj)
  on the project where you want to configure spend cap budgets

- **Option 3** : The following *combination* of Cloud Billing account and
  project-level IAM roles:

  - [*Billing Account Costs Manager* role](https://docs.cloud.google.com/billing/docs/how-to/billing-access#billing.costsManager)
    on the Cloud Billing account linked to the project

    and
  - [*Project Editor* role](https://docs.cloud.google.com/resource-manager/docs/access-control-proj)
    on the project where you want to configure spend cap budgets

### Configure a spend cap budget

For Cloud Billing to actively start monitoring your spending for a service,
you need to *configure* a spend cap budget for that service. If your project
reaches certain spending thresholds for that service, then Cloud Billing will
[send alert emails and enforce the spend cap](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#alerts-and-enforcement).

Here's how to configure spend cap budgets using the Firebase console:

1. Access your project in the Firebase console, then go to the
   **Settings** \>
   **Usage and billing** \>
   [**Details \& settings** page](https://console.firebase.google.com/project/_/usage/details?useAutoProject=true).

2. Go to the **Service-level spend caps** card.

3. Locate the service you want to cap, set your monthly budget amount, and then
   click **Configure**.

   - A spend cap budget is scoped to a *single* project and a *single* eligible
     service within that project.

   - The time range for a spend cap budget is *monthly*, starting on the
     first day of each month.

> [!CAUTION]
> **Caution:** **Spend caps budgets are *not* "hard caps".** Due to latency in usage reporting, spend cap enforcement is ***not* instantaneous**. Any cost overages incurred during this delay will be billed as normal. Consider setting your budget slightly below your absolute limit.

Note that you can also
[configure spend caps budgets using the Google Cloud console](https://docs.cloud.google.com/billing/docs/how-to/budgets-spend-caps#configure-spend-cap-budget).

### Alert emails and spend cap enforcement

After you configure a spend cap budget, Cloud Billing will actively monitor
your project's spending for that service. It will *send alert emails* and
*enforce the spend cap* based on the following spending thresholds for that
service's spend cap budget.

- **50% and 80%** of the set budget:

  - Cloud Billing ***sends warning alert emails*** to all billing administrators, project owners, and any applicable ["essential contact"](https://cloud.google.com/resource-manager/docs/managing-notification-contacts).
- **100%** of the set budget:

  - Cloud Billing ***enforces the spend cap*** , which means any new
    usage for the applicable service will be paused for the rest of the month
    unless you explicitly [lift the enforced spend cap](https://firebase.google.com/docs/projects/billing/spend-caps.md.txt#lift-spend-cap).

  - Cloud Billing ***sends another alert email*** . Also, the
    Firebase console and the Google Cloud console displays banner
    notifications about the spend cap enforcement and paused service.

#### Client-side impact and error handling

When a service is paused due to an enforced spend cap, your client-side app will
start throwing errors for that service. You should handle these exceptions
gracefully in your app code (for example, using `try-catch` blocks).

### Lift an enforced spend cap

If a spend cap is triggered and enforced,
*all **new** usage* for the applicable service is paused for the rest of the
month unless you explicitly *lift* the enforced spend cap.

Here's how to lift an enforced spend cap using the Firebase console:

1. Access your project in the Firebase console, then go to the
   **Settings** \>
   **Usage and billing** \>
   [**Details \& settings** page](https://console.firebase.google.com/project/_/usage/details?useAutoProject=true).

2. Go to the **Service-level spend caps** card.

3. Locate the service with an enforced spend cap, and then click **Lift**.

> [!CAUTION]
> **Be aware of the following for lifting a spend cap:**
>
> - **Possible delay to resume service:** Some services might take up to one hour to fully resume after you lift the enforced spend cap.
> - **No limit for the rest of the month:** If you lift an enforced spend cap and make no other changes, the service runs without a spend limit for the remainder of that month. At the beginning of the next month, the spend cap automatically resets to the **Configured** state with the original budget, and the service resumes.
> - **If you do *not* lift an enforced spend cap:** The service remains paused for the current month *only* . At the beginning of the next month, the spend cap automatically resets to the **Configured** state with the original budget, and the service resumes.

Note that you can also
[lift enforced spend caps using the Google Cloud console](https://docs.cloud.google.com/billing/docs/how-to/budgets-spend-caps#lift-spend-cap).

#### Increase a spend cap after enforcement

If your spend cap is enforced and you want to resume the service under a higher
budget for the remainder of the month (for example, increasing your limit from
$10 to $20), you *cannot edit the budget amount while the cap is in the
**Enforced** state*. You must lift the cap first before setting a higher limit.

Here's how to resume a service and increase its spend cap:

1. **Lift the spend cap:** In the Firebase console or Google Cloud console,
   locate the enforced service, and then click **Lift**.

   The spend cap will enter a pending state while enforcement is removed.
2. **Wait for the lift to complete:** Wait a few minutes and refresh the page
   until the spend cap status displays **Lifted**.

   The service will resume. Depending on the service, this can take up to
   one hour.
3. **Update the budget amount:** Edit the spend cap budget by entering your
   new, higher monthly budget amount. Save your changes.

**Important considerations when raising a cap:**

- **Tied to current month's total spend:** The new budget amount is still tied
  to your total accumulated spend for the current month, including any cost
  overages incurred during reporting delays before the cap was enforced.

- **Set a budget higher than current month's spend:** Make sure your new
  budget is higher than what you've already spent this month (including
  overages). Otherwise, the cap will trigger and pause the service again
  immediately.

- **Remaining budget calculation:** Your remaining budget for the month is the
  new threshold amount minus your total spend so far. For example:

  1. You set a $10 spend cap on Cloud Functions for Firebase.

  2. Your spend hits $10 (plus a $1 overage during the reporting delay,
     totaling $11). The cap is enforced, pausing your functions.

  3. You confirm the traffic is legitimate, so you lift the cap and wait for
     the state to show **Lifted**.

  4. You update the spend cap to $20. When you save this modification, the
     spend cap resets back to the **Configured** state.

  5. Your functions continue running under the new $20 cap, with
     approximately $9 of budget remaining for the month ($20 limit minus
     $11 already accrued).

  6. The next month, the spend cap budget will maintain the $20 threshold.

## Limitations of spend cap budgets

The following are important limitations to understand about spend cap budgets:

- **Spend caps budgets are *not* "hard caps".** Due to latency in usage
  reporting, spend cap enforcement is ***not* instantaneous** and can be delayed
  by several minutes. Any cost overages incurred during this delay will be
  billed as normal. Consider setting your budget slightly below your absolute
  limit.

- **Project and service scoped.** A spend cap budget is scoped to a *single*
  project and a *single* eligible service within that project.

  - You cannot set a spend cap budget at the entire Cloud Billing account
    level or at the Folder, Organization, or Label level.

  - You cannot set a single spend cap budget that will cover multiple projects
    or multiple services.

  - When you set a spend cap budget for a service, then it applies to any of the
    ways that you might interact with the service in the project. For example,
    if you set a budget on the Agent Platform Gemini API (formerly Vertex AI), then it also
    applies to any usage of that API in the project via
    Firebase SQL Connect, ADK, Genkit, etc. (not just usage via
    Firebase AI Logic).

- **Monthly time range.** A spend cap budget's time range is monthly, starting
  on the first day of each month.

- **Service resumes each month automatically.**

  - If you do ***not*** lift an enforced spend cap, the service will remain
    paused for the current month *only* . At the beginning of the next month, the
    enforced spend cap automatically resets to the **Configured** state with the
    original budget, and the service resumes.

  - If you lift an enforced spend cap during the month and do ***not*** change
    the budget, the service runs without a spend limit for the rest of that
    month, and the spend cap automatically resets to the **Configured** state
    with the original budget, and the service resumes.

- **Does not include savings and credits.** The cost calculations for a spend
  cap budget is based on gross costs and do *not* include savings and credits.

If you have more advanced billing setup, you can find more details about
[limitations of spend cap budgets](https://docs.cloud.google.com/billing/docs/how-to/budgets-spend-caps#limitations)
in the Google Cloud documentation.