<!-- source: https://docs.dreamlake.ai/billing/usage @ 0.1.192 b2f973b1 -->
# Billing & usage

Use **Settings → Billing & usage** to inspect your workspace's sandbox usage
and spending limit. Sign in as the personal namespace owner or an active
organization **OWNER**. Owning a machine or being an organization member does
not by itself grant access to workspace billing.

Open `https://dreamlake.ai/<namespace>/settings/billing`, replacing
`<namespace>` with your workspace slug. For example, the owner of `geyang`
opens [Billing & usage](https://dreamlake.ai/geyang/settings/billing).

The current page is labeled **Sandbox only**. It does not purchase credits,
charge a card, activate a plan, or automatically top up a balance. Prepaid
purchases and automatic usage deduction are not available in this release.

## First use

1. Open your namespace's **Settings**, then **Billing & usage**.
2. If you see **Sandbox billing is not configured**, ask your workspace
   operator to configure a verified sandbox paying account and reviewed rate
   catalog. There is no self-service setup button or default rate.
3. For a configured account, review **Workspace usage**, **Available budget**,
   and **Plan & credits**. Usage is the lifetime sandbox total, not a monthly
   invoice. “Credit balance not connected” means the balance is unknown.
4. Review **Attributed usage** for recorded resource quantities, costs, rate
   versions, and machine/job/agent identifiers. An empty table does not prove
   a job was free: the trusted producer may not be connected.

Only an authenticated, integrated producer can record measurements. Opening
this page or running an arbitrary job does not generate a billing receipt.
The browser cannot submit usage quantities, choose prices, or switch the
paying account. The full model/compute usage-to-provider flow is still pending.

## Set a sandbox spending limit

Enter a nonnegative amount in **Limit · USD**, with at most six decimal places,
then select **Save limit**. Refresh the page to confirm the saved value.

The limit must cover recorded spending plus held reservations. Available
budget equals the limit minus those two amounts. For example, a $10 limit
with $2 recorded and $1 reserved leaves $7 available. Reservations hold budget
for admitted work; final measured usage can exceed a reservation and is still
recorded. These rules apply to producers using the billing reservation API.

If usage or the budget changed while you were editing, refresh and review the
new values before saving again. Increasing the limit does not buy credits or
authorize a payment. This limit applies to the workspace's lifetime sandbox
usage; it is not a monthly allowance or an individual agent's budget.

## Inspect a machine, job, or agent

A Compute page can link to the matching usage view. You can also add stable
identifiers to the billing URL:

```text
https://dreamlake.ai/<namespace>/settings/billing?machineId=<machine-id>&jobId=<job-id>&agentId=<agent-id>
```

Use identifiers from the matching product records, not a display name or an
infrastructure provider's instance ID. Any of the three filters can be omitted.
Filters narrow the receipt table; the workspace totals above it stay unchanged.
Select **Load more usage** when more receipts are available.

An identical producer receipt replay must leave the event count and cost
unchanged. Parent-agent attribution does not create an additional charge.
Receipt replay is an operator/integration check, not a browser action.

## View test invoices

**Stripe sandbox invoices** lists existing invoices for the workspace's
operator-mapped test customer. **Verified test mode** means the customer and
returned invoices passed the backend's test-mode and ownership checks.

The page does not create or finalize invoices. A listed invoice is not proof
that local usage was delivered to Stripe or Metronome, nor that a purchase
created spendable credits. Provider delivery and reconciliation remain pending.
Provider credentials belong on the backend, never in browser configuration.

## Read provider balances and usage statements

The read-only provider extension adds **Metronome balances** and **Metronome usage
statements** to the same Billing page. Availability depends on your deployment
and the operator's sandbox configuration. These read-only views do not enable
purchases or usage delivery.

The operator must map this namespace to its intended sandbox customer and set
`METRONOME_SANDBOX_API_KEY` with `METRONOME_ENVIRONMENT=sandbox` on the backend.
A sample customer is not an approved workspace mapping. Missing configuration
shows an explicit unavailable state, never an invented zero balance.

Balances retain their provider denominations and credit/commitment types. They
are not combined into spendable DreamLake credits. Statements show up to five
existing usage invoices, each with up to 50 visible line items, provider totals,
and Draft/Finalized/Void status. Drafts may change; additional details and
truncation are labeled. Stripe invoices remain a separate read-only list.

Select **Refresh** to read current data. Repeating this action does not create,
finalize or pay an invoice. Provider statements do not prove that a local receipt
was delivered or reconciled. Owner or paying-account changes detected during a
read discard the response; sign in again or refresh the corrected mapping.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| Billing is available only to the signed-in namespace owner | Sign in with the active personal owner or organization OWNER account and check the namespace in the URL. |
| Sandbox billing is not configured | Ask the operator to verify the namespace-to-paying-account mapping and rate catalog. |
| No usage rows | Check the selected filters and whether the trusted producer persisted a receipt. Do not infer zero cost from missing measurements. |
| Credit balance not connected | Credit reconciliation is unavailable; changing a spending limit will not create a credit balance. |
| Usage or budget changed | Refresh, review current usage and reservations, then retry the edit. |
| Stripe customer or API access is not configured | The operator must configure a verified test customer and a test-only credential. No invoice is generated by this page. |
| Billing could not be loaded | Retry; if it persists, report the namespace and operation to the operator without sharing credentials or raw provider responses. |

Signing out or changing the authenticated account clears previously displayed
balances, invoices, and unsaved limit edits. Owner access revoked during a save
also clears the billing view.

## Operator reference

Account mapping, rate setup, receipt identity, test commands, and release
limitations are maintained in the
[backend runbook](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/dreamlake-server/docs/billing-product.md)
and the
[UI runbook](https://github.com/dreamlake-ai/dreamlake-ai/blob/main/docs/dev-notes/billing-product.md).
These repositories may require organization access. There is no Billing CLI
command or public account-configuration API in this release.

## Upcoming provider balance inspection

This addition is implemented for review and is **not yet deployed**. When the
companion UI/API are released, **Metronome balances** will read the mapped
sandbox customer's current credit and commitment balances. Refresh will recheck
the provider and show the read time. An empty verified response means Metronome
returned no credits or commitments; a setup or connection error is not a zero
balance.

Each row keeps the provider's denomination and distinguishes a credit grant,
prepaid commitment, and postpaid commitment. Missing values remain unknown.
Grant and contract restrictions still apply; the page does not combine these
rows into spendable DreamLake credits or convert unknown units to dollars. The
first 25 balances are shown with a notice if further provider pages exist.

This read-only view neither purchases credits nor implements prepaid admission
or usage reconciliation. It leaves existing usage and invoice reads available
when Metronome is unavailable. Losing namespace-owner access clears the billing
view. Credentials and customer mapping remain server-side operator settings.

## Upcoming prepaid accounting

This dependent addition is **not yet deployed**. For an account explicitly
enabled for prepaid accounting, the settings page shows **Prepaid usage credit**:
available, held, consumed, expired unused, scheduled credit, and uncovered usage.
These amounts are USD usage value from the local grant ledger. They are separate
from the provider balance inspection above.

Only a trusted fulfillment service's reconciled funding proof can create a local
grant. Reading Metronome balances, increasing a budget, or returning from a
checkout page does not grant credit. The dependent funding verifier below checks payment and matching grant evidence;
self-service purchase creation and ongoing reconciliation remain unconnected.
There is no browser grant or purchase control in this addition.

A producer using prepaid reservations must satisfy both budget and credit limits
before starting work. Held credit remains attached to its admitted run across
expiry. Settlement consumes that hold; releasing expired unused credit does not
make it available again. Uncovered measured usage remains visible and blocks new
prepaid reservations until an operator reconciles it. No automatic charge occurs.
Each receipt can show credit used and uncovered usage; exact replay must change
neither value. These controls do not apply to an unintegrated job launcher.

The accounting policy supports unrestricted account-wide grants. The dependent
exact-pricing addition carries fractions through usage and credit accounting, so
many tiny receipts cost the same as their combined quantity. Rounded displays
are labeled approximate; they do not change the debit. The updated page shows
exact receipt fractions and rate versions. This addition is also not deployed.
Restricted grants, approved commercial rates, payment-backed fulfillment, refunds
and provider reconciliation remain required before complete prepaid acceptance.

## Upcoming credit funding history

This addition is **not deployed**. Credit funding history will show recorded
sandbox purchase checks: awaiting payment, awaiting a matching grant, review
required, verification unavailable, or credit added. Each row identifies the
purchase invoice, approved usage value and checked time. The usage value may
differ from the price paid for a plan or pack.

A funding worker must verify both the Stripe payment and matching unused
Metronome credit before adding local credit. Failed, incomplete or ambiguous
checks add nothing. Refresh only reads recorded status and cannot purchase or
grant credit. Credited status records historical verification; later refunds,
disputes and provider usage still need reconciliation. Self-service checkout and
automatic verification scheduling remain unconnected in this addition.

## Upcoming usage delivery status

This addition is **not deployed**. Each usage row distinguishes recorded local
usage from delivery to Metronome. **Queued** awaits delivery; **Accepted by
Metronome** records ingestion acknowledgement only. It does not prove an invoice
or provider credit balance reconciles. **Review required** preserves usage when
configuration or safe retry limits prevent delivery. Historical **Pending** rows
have no verified delivery record. Refreshing the page cannot submit usage or
charge a payment method. Local credit used and provider acceptance are separate.

## Upcoming scoped spending limits

This addition is **not deployed**. Billing settings will show registered period,
project and job admission budgets separately from credit balance. Owners can edit
a limit after reviewing used and held value. Removing one limit leaves the account,
other applicable budgets and credit checks in force.

A scope counts work admitted from its displayed start. It does not retroactively
count earlier reservations. Reservations retain their original scope across a
window boundary; a continuing job must reserve its next bounded segment before
starting it. Measured overruns remain visible and prevent further admission under
an exhausted limit. Overlapping scopes describe the same usage and must not be
added together. These limits require the trusted producer to participate; they do
not stop a launcher that has not integrated reservation checks.

## Response-time access checks (unreleased)

The implementation in review checks workspace ownership again before returning
billing data or an edit acknowledgement. If access was revoked during a request,
the private result is withheld. If the paying-account mapping changed while a
read was in flight, refresh after your operator reconciles the configuration.
A withheld acknowledgement does not undo an already saved edit: check the current
value before retrying, and preserve the original Checkout retry identity.
This source change is not a claim of deployment or signed-in acceptance.

## Usage statements (unreleased)

The implementation in review adds **Metronome usage statements** to Billing.
It reads existing sandbox usage invoices separately from Stripe purchase invoices.
Each statement shows its period, status, provider total and line quantities,
including applied credits. Values retain their provider denominations.

Draft statements can change as usage arrives. A provider statement does not by
itself prove every local receipt was reconciled, nor does a zero total guarantee
that no later charge can occur. Refresh reads current evidence without creating
or finalizing an invoice. Missing access and incomplete lists remain explicit.
This addition is not yet deployed or accepted with a signed-in funded account.

## Saved sandbox credit reconciliation (unreleased)

Owners can check funded prepaid grants against Metronome's credit ledger and
referenced usage invoices from Settings → Billing & usage. The backend saves an
immutable local audit with the account revision, exact consumption and held value.
Matching grant totals is aggregate evidence, not proof for each receipt. Pending
delivery, missing purchase terms, unsupported adjustments and differences remain
explicit. Reservations are not provider deductions. No credit, usage or provider
configuration is changed by this check.

The first supported comparison covers active, unrestricted, single-segment paid
grants with approved denomination conversion. Expired, future, promotional or
adjusted grants require review. Provider errors never become zero balances.
Checks are bounded to 20 grants and 20 invoices per grant; capacity or truncated
evidence fails closed. Account changes during the check require retry; saved
results become stale after local accounting changes. This source feature requires
a matching API/UI release and approved sandbox mappings; it is not deployed
acceptance.

## Confirm a returned sandbox purchase (implementation candidate)

The full Billing implementation adds an explicit **Check payment** action after
returning from Stripe Checkout. It stays in the existing **Plans & credit packs**
report section. Returning to the page never confirms payment automatically.

Select **Check payment** to verify that one stored purchase. The server reads
current Stripe test payment evidence and, if paid, creates or recovers its
Metronome credit grant and verifies it before adding spendable credit. Awaiting
payment, awaiting grant, provider unavailable and review-required states stay
visible. A verified credit result refreshes the existing balance and funding
history. Repeating the action retains the same purchase and grant identity.

This requires the matching API/UI release, configured sandbox customers and
reviewed catalog, both sandbox feature flags and an explicit namespace allowlist.
The return URL supplies only the stored purchase ID; it cannot select provider
customers, prices or grant amounts. This section describes source behavior until
that release and actual sandbox payment acceptance are recorded. It does not
authorize a live charge or imply a trusted compute-measurement producer exists.
