Separate provider-cost budgets from customer retail billing

Start with the question each total answers

A provider-cost budget asks whether new activity fits a verified maximum estimate of upstream cost. Customer retail metering asks how activity consumes included allowance and paid overages under the account’s catalog. Subscription invoices answer another question about amounts actually billed. Treating these as one interchangeable dollar total makes operational decisions unreliable.

Lupin exposes the usage ledger through /v0/usage/ledger and retail accounting through /v0/billing/usage. Their quantities can refer to the same underlying activity while their money represents different things. Keep the data source and cost basis visible in internal dashboards and exported reports.

Read provenance before adding money

The provider ledger separates configured estimates, provider-confirmed USD costs and unpriced activity. A verified upstream receipt can replace a supported estimate, but an unknown amount remains unknown. The provider ledger is partial and does not claim to include every subscription, recurring fee or adjustment.

The retail overview separates included, settled, reserved and overage quantities, together with retail estimates. Those estimates exclude subscription charges, taxes and provider adjustments. Do not sum a provider estimate and a retail estimate as if they were two additional charges; they can describe distinct views of the same action.

Understand two admission decisions

A matching provider-cost budget can block unpriced or unbounded paid activity. Customer retail admission can block exhausted allowance without paid-overage consent, a retail cap breach or an unresolved payment condition. Satisfying one gate does not establish that the other allows a request.

This explains apparently surprising incidents: the customer may have included allowance left, yet no verified bounded provider estimate exists for a capped action. Conversely, a small provider estimate does not authorize retail overages. A fallback workflow must respect both controls and the user’s actual authorization.

Preserve periods and ownership

Provider-cost limits reset by UTC calendar month, with outstanding reservations retained until resolved. Retail metering follows the billing account’s applicable cycle and catalog. Compare start and end timestamps, workspace scope and coverage before comparing totals. Historical activity before accounting activation is not reconstructed as an authoritative invoice counter.

Project and key attribution can also affect the view. Lupin conservatively applies unattributed activity to matching provider-cost limits. A report filtered to a known project can therefore differ from an account-wide retail overview without either system being arithmetically wrong. Explain the scope instead of forcing agreement through manual adjustments.

Reconcile through quantities and references

When investigating a difference, match the product, unit, event identity, period and reservation state first. Then compare provider-cost provenance and retail rate separately. Inspect the actual provider invoice for billed charges. A useful worksheet has separate columns for upstream estimate, confirmed upstream cost and customer retail treatment.

Keep discrepancies open until their category is understood: timing, coverage, attribution, unpriced activity, allowance or invoice adjustment. Changing a budget to make a dashboard total look consistent can disable a real control. Repair the source or interpretation that is wrong, and preserve the original ledger history.

Sources & verification

Reviewed against the checked-in Lupin implementation and official reference documentation on 2026-11-05. Operational examples are illustrative; no live paid action, provider mutation or external message was executed.

• Lupin usage ledger and spending limits ↗Checked 2026-11-05
• Lupin billing, metering and retained storage ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.