#Outstanding Balance

Your outstanding balance is usage you have accrued that has not been captured onto a statement yet — transcoding and hosting, across every app in your organization. It is the amount Transcodely is carrying for you until the next invoice.

It is measured against a threshold, and the governing idea is worth stating before anything else:

The threshold is a payment prompt, not a wall.

Signing up on Monday and running €50 of transcoding by Wednesday is not doing anything wrong, and refusing the next job would be an outage we caused. So service continues past the threshold. Only at twice it does new-job admission stop — and paying lifts that on the very next request.

See your balance, your threshold and your position on the ladder on the Billing page in the dashboard.

#What the number is, and is not

Paying resets it to zero by construction: capturing usage onto a statement is exactly what this figure excludes. Nothing else clears it — no calendar, no period roll.

Amounts that will never be billed to you are excluded, as is anything written off or held while a payment dispute is open.

If your organization has no payment method on file, its usage is recorded but not invoiceable, so its outstanding balance is always zero and this ladder never applies to it. Accounts in that state are bounded by the free tier’s in-flight job cap instead.

#Trust tiers set the threshold

The threshold comes from how many statements your organization has paid.

A statement counts once it is actually paid, not when it is issued. Paying an outstanding balance mid-cycle produces a real statement, so it counts like any other once settled.

At proven the tier stops having an opinion and your organization falls through to whatever ceiling its plan sets — which for most accounts is none at all. An account with no ceiling has no threshold, no reminders and no hard stop. That is where the ladder is meant to end up, and it reports its threshold source as unbounded.

A plan ceiling can only ever tighten the threshold, never raise it: carrying more unbilled usage than an account may spend in a month would be extending credit past the amount it can run up at all.

#The steps

Comparisons are exact and in whole cents, and landing exactly on a step counts as crossed — exactly twice the threshold is blocked.

A jump that crosses several steps at once sends all of them. Nobody’s first email from this system should be the hard stop.

Each step emails at most once per balance, to your organization’s billing email; the steps re-arm once the balance is settled or the billing period rolls. Like budgets, a threshold change does not re-send a step you have already been emailed about. These reminders are email only — there is no webhook event for them.

#What “blocked” does and does not touch

At twice the threshold, only new job creation stops. Everything else continues:

• work already queued or running finishes, and its outputs are delivered;
• playback and CDN delivery keep serving;
• uploads and the dashboard are unaffected;
• canceling stays available — you must always be able to stop the meter;
• reads are never blocked.

The refusal is Connect code failed_precondition with the error code outstanding_balance_exceeded, and the message names the balance, the ceiling and where to clear it:

CodeFailedPrecondition
  error-code: outstanding_balance_exceeded
  message: new jobs are paused: this organization has run up €101.40 of usage
           that has not been billed yet, which has reached the €100.00 we carry
           before asking to be paid (threshold €50.00, set by trust_tier); pay
           the outstanding balance on your billing page and jobs resume
           immediately — work already queued or running is unaffected

Switch on the outstanding_balance_exceeded discriminator, not the message text. It is deliberately distinct from limit_exceeded and queue_limit_exceeded, which clear on their own so retrying with backoff is correct; this one clears when the balance is paid.

If your organization has an unpaid invoice as well, that is reported first, with billing_past_due — the statement is the more concrete thing to act on. You hear about the balance on the very next create once the invoice is settled.

#Paying the balance now

You do not have to wait for the period to end. Where the option is available on your account, the Billing page offers a pay-now action that closes your current period at that instant and produces a real statement for everything owed, which your payment provider then charges.

• It takes no amount. The figure is whatever your usage says at the moment it runs — a stale page cannot pay less than is owed and leave the difference looking settled.
• On success the balance is zero, and any block is lifted on the very next request. There is no sweep to wait for.
• Your trust tier re-evaluates once that statement is paid, not when it is issued.
• The statement is an ordinary invoice: it appears in your invoice list and is paid through the same flow as any other.
• Usage between the settlement and the end of the calendar period lands on your next statement. Every charge is billed exactly once.

This rail is not enabled on every deployment. The settlement_available flag on the balance says whether it is live for you, and the dashboard only offers the action when it is — a button that can only fail is worse than no button. Calling it while it is switched off returns failed_precondition with the error code settlement_unavailable; calling it when there is nothing to pay returns nothing_outstanding, which is simply what pressing Pay twice does.

Until then, balances settle the ordinary way: at the end of the billing period.

#Reading the balance

The balance lives on BillingService, which is organization-scoped and owner-only — the organization comes from the X-Organization-ID header, and API keys are refused, because spend across every app is the organization’s business rather than one integration credential’s. transcodely.v1.BillingService/GetOutstandingBalance returns everything a balance card needs in one call:

{
  "object": "outstanding_balance",
  "org_id": "org_f6g7h8i9j0",
  "outstanding_cents": "6250",
  "tier": "new",
  "settled_payments": "0",
  "threshold_cents": "5000",
  "threshold_source": "trust_tier",
  "hard_stop_cents": "10000",
  "blocked": false,
  "used_percent": 125,
  "alert_steps": [80, 100, 125, 150, 175, 200],
  "notified_steps": [80, 100, 125],
  "currency": "EUR",
  "settlement_available": false
}

This is a different number from your upcoming invoice, which shows what the current period has accrued. The balance shows what is unsettled, which also carries anything an earlier period left uncaptured — and it is the number that decides whether new jobs are admitted.