Customers & metering

Bill your customers for what their smiths consume. A customer here is your billable party, never Ingram Cloud's. The platform meters quantities and your cost; what you charge (flat fee, usage, credits, any mix) stays in your own billing stack.

The customer object

# Authorization: tenant-admin token (server-side only)
curl https://api.cloud.ingram.tech/v1/customers \
  -H "Authorization: Bearer $IC_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Globex Corp",
        "external_ids": { "stripe_customer_id": "cus_…" } }'
# → 201 { "id": "cus_…", "smith_count": 0, … }

external_ids is a free-form map: store your Stripe customer id (or any billing-system key) so pushing usage into your meters is a field lookup.

Assigning smiths

Many smiths roll up to one customer. Assignment lives on the smith:

# Authorization: tenant-admin token (server-side only)
curl -X PATCH https://api.cloud.ingram.tech/v1/smiths/smt_… \
  -H "Authorization: Bearer $IC_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_…" }'        # "" clears the assignment

Attribution is stamped onto usage at ingestion and is forward-only: reassigning a smith changes where future usage lands; history never moves, so any past invoice stays reproducible forever. Unassigned smiths still bill cleanly: they appear as synthetic principal:<smith id> groups in customer-grouped usage until you assign them.

Per-customer rollups

The same usage API, grouped by customer, invoice-shaped:

# Authorization: tenant-admin token (server-side only)
curl "https://api.cloud.ingram.tech/v1/usage?group_by=customer&period=2026-06"
# → groups: [ { "customer": "cus_…", "tokens": …, "cost": …, "run_count": … }, … ]
#   meters: [ { "meter": "report_generated", "customer": "cus_…",
#               "quantity": 42, "events": 42 } ]
# format=csv for an export your finance team can open

How `cost` is computed

cost is the sum of each token bucket priced at its own per-model tier: uncached input and output at the standard rates, cache reads at the provider's discounted cache rate, and cache writes at the cache-creation rate where the provider charges one. Prompt caching therefore shows up as a lower cost than a flat input-rate estimate would: the figure tracks the shape of your provider bill rather than charging every prompt token at the input rate. Each model-call's cost is frozen at ingestion using the price in effect then, so editing the price book never rewrites historical cost. Prices are a built-in default book, editable per model.

Custom metering events

Token cost is rarely the whole invoice. Record domain-specific billable units ("report generated", "ticket resolved") as metering events:

# Authorization: tenant-admin token (server-side only), or a smith token with usage:write
curl https://api.cloud.ingram.tech/v1/usage/events \
  -H "Authorization: Bearer $IC_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "smith_id": "smt_…", "meter": "report_generated",
        "quantity": 1, "idempotency_key": "report-8841" }'

Meter names: lowercase, namespaced with ._:- (≤100 chars). Quantity must be positive.
idempotency_key makes retries safe: a replay returns the original event. (A body field rather than the usual header, so the ledger itself stores the key you can reconcile against.)
The event inherits the smith's customer assignment at write time.
GET /v1/usage/events is the raw, exportable ledger; auditability is the point: any invoice line can be reconciled against these rows.

Feeding your billing stack

Monthly close, the short version:

GET /v1/usage?group_by=customer&period=2026-06: cost + meter quantities per customer.
Map each group to your billing system via external_ids (e.g. stripe_customer_id).
Push quantities into your meters/invoice lines at your prices.

Per-customer budgets (scope: "customer") can cap a single customer's spend, useful for free tiers and trials.

In the console

Build → End users lists your end-users one row per person, each expanding to the smiths they run (one per agent) and showing their optional billing account (the billable party). A billing account's own page has the per-account usage rollup, meters, and exports — what you bill others, kept distinct from Observe → Usage & cost, what you pay.

Usage, cost & budgets Credits & billing