Credits & billing

Credits are your organization's prepaid balance with Ingram Cloud — the money you pay us for platform usage. This is the opposite direction from Customers & metering, which is the money you bill your own customers; the two never share a page on purpose.

Credits are held at the organization level (one wallet pooled across all of your projects), not per project or per customer. Ingram Cloud is the merchant of record for these charges; your card is charged through Stripe.

Your wallet is held in your organization's billing currency — EUR by default, set from Stripe when you add a card. Every amount below (balance_cents, ledger entries, top-ups) is in that currency; format *_cents as minor units of it.

Start free: unlock €10

Running agents needs a verified card — the free trial is card-gated to keep fraud out, but adding a card costs nothing. Add one (Settings → Billing → Add a card) and €10 in credits unlocks immediately, no charge. Until a card is added, runs are refused with 402 card_required.

# Authorization: organization key (server-side only)
curl https://api.cloud.ingram.tech/v1/organization/billing/setup \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://your.app/billing?setup={CHECKOUT_SESSION_ID}" }'
# → 201 { "url": "https://checkout.stripe.com/c/pay/cs_…" }

This is a no-charge Stripe setup session: the card is saved (and reused for top-ups and auto-reload), and the €10 welcome credit is granted once per organization, when the card verifies.

Buying credits

The console is the way in: Settings → Billing → Buy credits. Pick a preset (€20 / €100 / €500) or enter another amount, then pay by card inline — Stripe collects the card and billing address and computes any tax. Your balance updates the moment Stripe confirms the charge.

A Stripe customer record for your organization is created only on the first successful payment, and reused (with any saved card) on later top-ups.

Checking your balance

The balance lives on the organization surface, so it takes an organization key:

# Authorization: organization key (server-side only)
curl https://api.cloud.ingram.tech/v1/organization/billing/balance \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01"
# → 200 { "currency": "eur", "balance_cents": 10000,
#         "stripe_customer": true }

GET /v1/organization/billing/ledger returns the recent append-only ledger, newest first — each entry carries a signed amount_cents and a kind. Top-ups are positive kind:"topup"; usage debits are negative kind:"debit".

How usage draws down credits

Every run your agents make is metered and debited from the org wallet when it finishes. The charge is the run's provider cost (priced from the model price book and converted into your billing currency) times your organization's margin (the platform markup; 20% by default, set per organization). The wallet is one pool across all your projects; which project drew how much is on each debit and summarized by the per-project endpoint below. Usage you've already started always finishes — the balance can dip slightly negative on an in-flight run; the gate below catches the next one.

Per-project spend

One wallet funds every project, so the org view is "which project is spending it":

# Authorization: organization key (server-side only)
curl "https://api.cloud.ingram.tech/v1/organization/billing/usage?period=2026-06" \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01"
# → 200 { "period": "2026-06", "currency": "eur", "total_drawn_cents": 4210,
#         "projects": [ { "project_id": "proj_…", "name": "Acme",
#           "drawn_cents": 4210, "budget_limit": 100, "budget_action": "block" } ] }

period defaults to the current calendar month (UTC). budget_limit is the project's funding cap — a tenant-scope cost budget set on that project — or null when the project draws freely from the org wallet. Without a budget a project is bounded only by the org's overall balance; with a block budget it stops at its own limit even while the wallet still has funds.

When runs are refused

Two prepaid gates, both at run creation:

402 card_required — no verified card yet. Add one to unlock €10 free (above).
402 insufficient_credits — the wallet is empty; a credit.exhausted event fires. If auto-reload (below) is on, it charges your saved card first and the run proceeds when the top-up clears.

A run already in flight is never interrupted.

Starting a top-up programmatically

The console uses an embedded Stripe Checkout Session under the hood. If you build your own top-up UI, mint the session and render it with Stripe's embedded checkout:

# Authorization: organization key (server-side only)
curl https://api.cloud.ingram.tech/v1/organization/billing/checkout \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 10000,
        "return_url": "https://your.app/billing?topup={CHECKOUT_SESSION_ID}" }'
# → 201 { "client_secret": "cs_…_secret_…" }

Pass client_secret to Stripe.js embedded checkout. Credits are applied when Stripe confirms the payment (via our webhook), not when the session is created — so a balance reflects a top-up a moment after the customer finishes paying.

An optional mode field ("live" by default, or "test") selects the Stripe account the session runs against. "test" is the Stripe sandbox and is reserved for Ingram staff — it returns 403 test_mode_forbidden otherwise. Load the embedded checkout with the publishable key for the same mode, or Stripe.js rejects the session's client_secret.

Auto-reload

Auto-reload keeps your balance from running dry without you watching it: when the balance falls below a threshold, your saved card is charged for a fixed reload amount. It's off by default; the threshold defaults to €10 (the console's low-balance line, so it fires before the wallet empties) and the amount is yours to set. The first top-up saves your card, so auto-reload only works once you've bought credits at least once.

# Authorization: organization key (server-side only)
curl -X PUT https://api.cloud.ingram.tech/v1/organization/billing/autoreload \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "threshold_cents": 1000, "amount_cents": 10000 }'
# → 200 { "enabled": true, "threshold_cents": 1000, "amount_cents": 10000 }

GET /v1/organization/billing/autoreload reads the current settings back. Once usage debits draw your balance down past the threshold, auto-reload tops it back up off-session. You can also top up from the saved card on demand — POST /v1/organization/billing/reload charges it now (amount_cents optional, defaults to your configured reload amount):

# Authorization: organization key (server-side only)
curl -X POST https://api.cloud.ingram.tech/v1/organization/billing/reload \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'
# → 200 { "credited": true, "payment_status": "succeeded" }

A reload returns 409 no_saved_card if no card has been saved yet.

Managing billing & invoices

GET /v1/organization/billing/portal mints a Stripe billing portal session — manage your billing address and VAT id, update the saved card, and download invoice history. Pass a return_url Stripe sends the user back to:

# Authorization: organization key (server-side only)
curl "https://api.cloud.ingram.tech/v1/organization/billing/portal?return_url=https://your.app/billing" \
  -H "Authorization: Bearer $IC_ORG_TOKEN" \
  -H "IC-Api-Version: 2026-05-01"
# → 200 { "url": "https://billing.stripe.com/p/session/…" }

The portal needs an existing Stripe customer, so it returns 404 no_customer until your first top-up has created one.

In the console

Settings → Billing shows your current balance with Add a card (unlock €10 free, shown until a card is on file), Buy credits, Auto-reload (with a Reload now button), Manage billing & invoices (the Stripe portal), and a per-project breakdown of this month's draw against each project's funding cap. It sits with the rest of account billing, separate from Observe → Usage & cost (the provider-cost view and per-project budgets) and Build → End users (what you bill others).

Customers & metering TypeScript wire SDK