> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing & Usage
> Manage your pay-per-event plan and payment method, and monitor request volume across your agency's clients.
## Overview
Billing and Usage are two related, admin-only settings pages:
Your Stripe-backed subscription — payment method, event plan tier, and billing history. Only visible if your agency is on pay-per-event billing.
A request-volume dashboard broken down by day, client, and origin. Visible to every admin, regardless of billing setup.
Both pages count the same underlying thing — requests against your agency — but they pull from different data sources and can show different totals for the same period. See [Usage vs. Plan: why the numbers can differ](#usage-vs-plan-why-the-numbers-can-differ).
***
## Plan
Go to **Settings → Plan**. This page only appears if your agency has pay-per-event billing enabled; otherwise it redirects to the main Settings page.
### Payment method
The top card shows the card on file (brand, last four digits, expiration) or, if none is on file, a prompt to add one. **Add/Update Payment Method** starts a Stripe Checkout session in `setup` mode — you're redirected to Stripe to enter card details, then back to this page with a confirmation.
### Plan overview
Two cards summarize your current billing period:
* **Monthly Event Limit** — your plan's event cap, this month's usage against it, percentage used, and projected overage cost. If you're at least 3 days into the billing period and your daily usage rate projects past your cap by month end, a warning banner appears showing your projected total and daily rate.
* **Pay-Per-Event Billing Rate** — your current overage rate (dollars per 25,000 events), current overage event count, and an expandable **How overages work** explainer (see below).
Usage resets on the first day of each calendar month.
Each of the following counts as one event: sending an email, receiving a reply, an API request, and a data enrichment request. For example, sending 10,000 emails and receiving 200 replies is 10,200 events.
### Changing plans
Click **Update Plan** to open the plan tier selector. The dialog shows your last month's usage with a recommended tier, your projected usage for the current month (once enough data exists), and the full tier list:
| Plan | Events / month | Price |
| ---- | -------------- | ---------- |
| 1M | 1,000,000 | Included |
| 1.5M | 1,500,000 | \$90/mo |
| 2M | 2,000,000 | \$180/mo |
| 2.5M | 2,500,000 | \$270/mo |
| 3M | 3,000,000 | \$360/mo |
| 3.5M | 3,500,000 | \$450/mo |
| 4M | 4,000,000 | \$540/mo |
| 5M | 5,000,000 | \$720/mo |
| 7.5M | 7,500,000 | \$1,170/mo |
| 10M | 10,000,000 | \$1,620/mo |
| 15M | 15,000,000 | \$2,520/mo |
| 20M | 20,000,000 | \$3,420/mo |
| 25M | 25,000,000 | \$4,320/mo |
| 30M | 30,000,000 | \$5,220/mo |
| 40M | 40,000,000 | \$7,020/mo |
| 50M | 50,000,000 | \$8,820/mo |
Each tier step above 1M adds 500,000 events for \$90/month.
Moving to a higher tier applies immediately: your Stripe subscription is modified with proration, so you're charged (or credited) for the partial month right away.
Moving to a lower tier doesn't take effect immediately. It's scheduled for the end of your current Stripe billing period (or the 1st of next month, if you have no active subscription — e.g. you're currently on the free 1M tier). Your current plan and cap stay in effect until then. A notice banner at the top of the page shows the pending downgrade and its effective date.
A daily job applies scheduled downgrades once their effective date arrives — see [How overage billing works](#how-overage-billing-works).
### How overage billing works
Overage billing begins once you exceed your monthly plan limit, and is billed in **blocks of 25,000 events** at your agency's configured per-block rate (shown as "Pay-Per-Event Billing Rate" on this page; the UI's example figures below use \$5/block, but your actual rate depends on your agreement with RevyOps).
* A daily job (03:00 UTC) counts your agency's total requests for the current calendar month directly from the request log warehouse, and compares that count against your monthly cap.
* If the overage has crossed into a new 25,000-event block since the last run, an invoice is created and finalized in Stripe for just the new block(s) — not the whole month's overage again. This is tracked per-agency, per-billing-period, so re-running the job doesn't double-bill.
* If a block isn't fully used in one day, the remaining events roll over to the next day within the same billing period. Unused overage events do not carry into the next billing cycle.
**Example:** you exceed your plan by 60,000 events in a month, at \$5/block:
```
25,000 events → $5
50,000 events → $10
60,000 events → $15 total (3 blocks of 25,000, rounded up)
```
If only 10,000 events are used from a block on a given day, the remaining 15,000 roll over to the next day before another block is charged.
The same daily job also applies any pending scheduled downgrade whose effective date has arrived, updating your monthly cap and Stripe subscription without proration.
### Billing history
The table at the bottom of the page lists your last 12 billing periods:
| Column | Meaning |
| ---------------------- | --------------------------------------------------- |
| Period | The billing period month |
| Event Plan | The plan tier active during that period |
| Plan Price | Monthly subscription cost for that tier |
| Events Used | Total events consumed |
| Included Events | Events included in the plan at no extra cost |
| Overage Events | Events used beyond the plan limit |
| Overage Charges | Overage charges for the period, at the per-25k rate |
| Effective Cost / Event | (Plan price + overage charges) ÷ events used |
| Total Charges | Plan price + overage charges |
| Status | Invoiced, Paid, or Failed |
***
## Usage
Go to **Settings → Usage**. Unlike Plan, this page is visible to every admin regardless of billing configuration.
### Event sources
A legend at the top explains the three request origins tracked throughout the page:
| Origin | Meaning |
| -------------- | ------------------------------ |
| **Dashboard** | RevyOps dashboard interactions |
| **Public API** | External API and webhook calls |
| **Internal** | System / internal API calls |
### Summary and chart
Three tiles show request totals for **Today**, **This Month**, and **Last Month**. Below them, a time-series chart plots total requests per day across the currently selected date range.
### Table and filters
The table lists one row per day/client/origin combination, with columns for Date, Client, Origin, and Requests. It's paginated 25 rows at a time. Filter it with:
* **Day range** — 7 / 15 / 30 / 60 days. A range is disabled if you don't have that much usage history yet; the page auto-selects the largest available range on load.
* **Client search** — filters by client name (case-insensitive, substring match).
* **Origin** — filter to a single origin (Dashboard, Public API, or Internal).
### Data freshness
Usage data is synced from the request log warehouse into a Firestore cache once per day (a 24-hour cache TTL) rather than queried live on every page load. A **Last updated** timestamp under the summary tiles shows when that sync last ran.
***
## Usage vs. Plan: why the numbers can differ
Both pages ultimately count requests against your agency, but they're built on different pipelines and can diverge:
* **Plan's overage billing** counts **every** request logged for your agency in the current calendar month, queried directly from the request log warehouse at billing time.
* **Usage (and Plan's own usage tiles)** read from the Firestore `daily_usage` cache, which is built by a daily sync that **drops any request with no `client_id`, or a `client_id` that isn't one of the agency's currently active clients.**
In practice this means the Usage dashboard and Plan's usage figures can under-count relative to what you're actually billed for — most commonly for requests that aren't tied to an active client (e.g. agency-level or system calls), or for very recent activity that hasn't synced into the cache yet. If your Plan overage looks higher than what Usage shows for the same period, this is the most likely reason.
***
## Access & Permissions
Both pages are restricted to users with the `admin` role. Plan is additionally gated by an agency-level pay-per-event billing entitlement — agencies not on that billing model are redirected away from `/dashboard/billing` and don't see **Plan** in the Settings sidebar. Usage has no such gate; any admin can see it.