#Budgets

A budget is a monthly EUR figure you set for your own organization, so that we email you when your spend reaches 50%, 80% and 100% of it.

A budget never enforces anything. No job is refused, no video stops playing, no limit changes. Crossing 100% of a budget sends an email and nothing else. If you want a number that actually stops work, that is a spend limit, which is a different feature.

Budgets are off by default. Set one from the Billing page in the dashboard.

#Budgets notify, limits block

Three things in Transcodely look like “a monthly EUR ceiling”. They are not interchangeable, and it is worth knowing which one you are looking at:

You can use any combination of the three. Setting a budget does not create a spend limit, and setting a spend limit does not create a budget.

#What counts as spend

spent_eur is everything billed to your organization inside the current billing period: transcoding and hosting, across every app. It is the same figure, over the same window, that your upcoming invoice is built from — so a budget alert saying you have spent €50 and a bill for €74 arriving days later cannot happen.

Two consequences worth stating outright:

• It is not the same number as an app’s spend limit. AppService.GetSpend is scoped to one app, is computed from jobs (including estimates for jobs still running), and knows nothing about hosting. It is the right input for a spend limit and the wrong one for a budget.
• Usage that has already been invoiced still counts. Spend does not un-happen when it is billed. If a statement is raised mid-period, the budget bar does not drop.

Usage that will never be billed to you — anything comped or exempt — is excluded, because it would be strange to consume a budget with charges that never arrive.

The billing period is the same one your invoices use: your payment provider’s subscription window where you have one, and otherwise calendar months.

#Alert steps

Fixed at 50%, 80% and 100%, and not configurable today.

Each step emails at most once per organization per billing period, per budget amount — changing the amount starts the ladder over, see below. Emails go to your organization’s billing email. A single large settlement that jumps past several steps sends all of them, not just the highest — the ladder is the story.

Alerts are email only. There is no budget webhook event; the webhook catalog is unchanged by this feature. If your organization has no billing email set, the alert is not sent and not consumed — it arrives once you set one.

Alerts are evaluated on a schedule rather than at the instant a charge lands, so an email follows a crossing by a short delay rather than arriving in the same second.

#Changing a budget mid-period

Changing the amount re-arms the ladder against the new number. The old number’s alerts are finished business: they were true when they were sent, and they are not re-sent, un-sent, or replayed. What the new number gets is a clean ladder — with the steps you are already past treated as already acknowledged, by the act of changing it.

Two consequences worth stating outright:

• Every change is confirmed by email, to the same billing contact — set, changed, or removed. The confirmation says what the budget is now and where this period’s spend already stands against it.
• An alert that had not been sent yet when you changed the amount is canceled, not delayed. Alerts are evaluated on a schedule, so one can be queued at the instant you edit the number; it is dropped rather than arriving moments later with a figure you have just replaced.

The confirmation and the alerts are both optional email: you can turn budget email off entirely under Settings → Notifications (see Email notifications), or from the unsubscribe link in the email itself. Turning it off changes nothing about the budget — the bar in the dashboard keeps tracking it.

Spend limits deliberately behave the other way: their threshold events are not re-armed by a mid-period limit change. A spend limit blocks work, so re-firing its warnings on every edit would be noise on a number that already enforces itself; a budget only tells you, so a new number deserves a fresh ladder.

#Reading and setting a budget

Budgets live on BillingService, which is organization-scoped and owner-only: the organization comes from the X-Organization-ID header, and API keys are refused — a key is scoped to one app, and a budget is not. In practice this means the dashboard’s Billing page, signed in as an organization owner.

transcodely.v1.BillingService/GetBudget returns everything a budget card needs in one call:

{
  "object": "budget",
  "org_id": "org_f6g7h8i9j0",
  "amount_eur": 50,
  "spent_eur": 40,
  "used_percent": 80,
  "period_start": "2026-08-01T00:00:00Z",
  "period_end": "2026-09-01T00:00:00Z",
  "alert_steps": [50, 80, 100],
  "notified_steps": [50],
  "currency": "EUR"
}

transcodely.v1.BillingService/UpdateBudget sets the number, and omitting amount_eur clears the budget and turns the alerts off — it is the one place where sending nothing is a complete instruction. The value must be greater than zero. The response carries the budget with spend recomputed, so a page that just moved the number can redraw the bar without a second request.

#Who can set a budget

Anyone with a billing page. A budget is telemetry you asked for about your own spending, so nothing about your plan or payment standing gates it, and no payment provider is involved: it is your number, measured against your own usage.