Project budgets

Overview

A project budget caps one project's usage spend each billing period, beneath your organization budget. Use one to keep a single client, team or integration from using up the budget your whole organization shares.

Project budgets cap usage of Delivr's metered APIs and exports. They are separate from DelivrDSP campaign budgets, which cap a campaign's media spend.

How a project budget works

It is an amount only. Whether budgets are enforced, the warning level and the billing period all come from your organization budget, and every project budget uses them.
It applies only while your organization budget is set and enforced. With the organization budget off or not set, project budgets are kept but stop nothing.
A project's spend is its share of your organization's estimated usage cost for the billing period: the cost of each meter is split across projects by each project's share of that meter's volume. It is measured the same way as your organization budget.
The organization budget still caps every project together. Project budgets can add up to more than it.
Reaching a budget exactly counts as reaching it.
Budgets are available to organizations on card billing.

Spend is refreshed every few minutes, so a request can still be served for a few minutes after a budget is reached. A raised or removed budget takes effect within about a minute.

Set a project budget

Organization owners and admins set project budgets in the dashboard:

Open Billing > Plan and Usage.
In the Billing period budget card, under Project budgets, click Add project budget.
Choose a project, enter the budget per billing period in US dollars, and click Save project budget.

Use Change and Remove on a project's row to edit it later. A project budget can be set on an active project of your organization, and the amount must be greater than zero.

Billing viewers see the list of project budgets without the controls. A project's owners and admins see their own project's budget, read-only, under Billing > Plan and Usage inside the project.

When a budget is reached

What stops depends on what the request is, and for API requests on the key that makes it.

What	With an organization key	With a project-scoped key
Events API: the routes that return records, identity lookup (`/api/v1/lookup`, `/api/v1/lookup/batch`) and the resolution export	Stopped by the organization budget only	Stopped by the organization budget or the key's project budget
Intent API: the billed `/api/v1/intent/*` routes	Stopped by the organization budget only	Stopped by the organization budget or the key's project budget
Contact query (`POST /api/v1/contact/query`)	Stopped by the organization budget only	Stopped by the organization budget or the key's project budget
Audience downloads and predictive signals	Stopped by the organization budget or the audience's project budget	Stopped by the organization budget or the audience's project budget
Scheduled exports, Run now and the contacts CSV export	Stopped by the organization budget or the export's project budget	Stopped by the organization budget or the export's project budget

A request made with an organization key on the events API or the intent API is stopped only by the organization budget, even when it reads a single project's data.

Audience downloads, predictive signals and exports are always judged against the project they belong to, whoever asks, including in the dashboard.

Routes that bill nothing, such as schema and count routes and the intent previews, are never stopped.

The refusal

A refused request answers 402 with error set to budget_exceeded:

{
  "error": "budget_exceeded",
  "message": "This project's monthly budget is reached. An organization admin can raise or remove it in billing to resume API access for this project.",
  "limits": {
    "mtd_cents": 6000,
    "budget_cents": 5000,
    "project_id": "YOUR_PROJECT_ID"
  }
}

limits reports the spend so far this billing period and the budget, in cents.
limits.project_id is present when a project's budget was reached, and absent when it was the organization's.
When the organization's budget refuses a project-scoped key, the body has no limits: the organization's figures cover every project, so a project key is not told them.
The message wording differs between APIs. Branch on error, not on the message.

To resume, an organization owner or admin raises or removes the budget, or the next billing period begins.

Who is told

Email, when the project's spend crosses the warning level and when it reaches the budget: your organization's owners, and the project's owners and admins.
In-app notification, at the same two points: your organization's members, and the project's owners and admins.
A banner inside the project, while the budget is near or reached, for the project's owners and admins and for your organization's billing viewers.

Next steps

Authentication: create a project-scoped API key