Customers, invoices and the customer portal
Resell model access to your own customers with their own keys, prices, limits, budgets, invoices, SLAs and a branded usage page.
The Customers area is for an organisation that sells access to models to its own end customers, for example a SaaS built on Venom Cloud. Each customer gets ordinary vck_ API keys, your price for each model, its own rate limits and model allowlist, an optional monthly budget in its own currency, monthly invoices and a private usage page under your brand. Venom never contacts your customers and calls no outside service until you connect your own Stripe account.
Reading anything here needs billing:read; every change needs billing:manage, which owners and the billing role have (admins do not). Another organisation's customer id answers 404.
Add a customer and give them a key
Open
/customers/new. Enter a name (unique in the organisation, case-insensitive), a billing email, your own reference, the key group its keys live in (default: the organisation's first key group), the currency and its fixed rate, and a price rule. The currency cannot change later.On the customer's page,
/customers/{id}, create a key. The key is shown once. Give it to the customer; they use it like any Venom Cloud key:curl https://cloud.usevenom.dev/v1/chat/completions \ -H "Authorization: Bearer vck_…" \ -H "Content-Type: application/json" \ -d '{"model":"venom-auto","messages":[{"role":"user","content":"hello"}]}'Under "Usage page", create the portal link (
/portal/vcp_…) and send it to the customer. It is shown once.
Every request on the customer's keys is booked twice: at your cost and at the customer's price under the rule in force at that moment. A later price change applies from then on and never rewrites past bookings.
Pages
| Page | What it shows and does |
|---|---|
/customers |
Every customer for a month: charges per currency, your cost, margin at the fixed rates, requests. A month picker. |
/customers/new |
The create form (fields below). At most 1,000 customers per organisation (409 too_many_customers). |
/customers/{id} |
One customer: the month's figures, usage by model and by day, live keys (create, revoke; a new key is shown once), the usage page link (create, replace, revoke), the monthly budget, the pricing and limits form, Suspend and Archive. |
/customers/settings |
Branding for the usage page and invoices: display name, logo, accent colour, support email, with a preview. Also the invoice settings and the Stripe connection. |
/customers/invoices |
Invoices by month: generate drafts, approve, send, mark paid, void, export the month as CSV. |
/customers/invoices/{id} |
One invoice: lines, tax, total, state, the cost behind it (console only), the Stripe steps done so far. |
/customers/invoices/{id}/print |
The printable invoice (A4 print styles). Use the browser's "Save as PDF". Works without Stripe. |
/customers/simulator |
The pricing simulator: what each customer would have paid under another plan. |
/customers/sla |
SLA targets per customer or per route, this month's verdicts and drafted service credits. |
/customers/sla/{id} |
One SLA target with six months of reports, edit and delete. |
/portal/{token} |
The customer's own usage page (public, see below). |
/portal/{token}/invoices/{id} |
One of the customer's open or paid invoices, printable, under your brand. |
Customer fields
| Field | Type | Default | Notes |
|---|---|---|---|
name |
text | required | Unique per organisation, case-insensitive. |
email |
none | Billing email. Needed to send invoices through Stripe. | |
external_ref |
text | none | Your own id for the customer. |
team_id |
key group | first key group | The key group whose keys the customer's keys are (the API calls it team). |
currency |
code | USD |
USD, EUR, GBP, JPY and 18 more. Fixed at creation. |
fx_rate |
number | 1 | Units of the currency per US dollar. Fixed by you; nothing is fetched. |
| price rule | see below | markup, 20 % |
markup, price_list or flat. |
rpm, tpm |
integer | none | Requests and tokens per minute. Replace each key's own limits (rate windows stay per key). |
allowed_models |
list | all | Model allowlist. Replaces the key's own. |
monthly_budget |
number | none | In the customer's currency, counted at the customer's price. |
notes |
text | none | Internal. |
| status | active, suspended, archived |
active |
Suspended and archived customers' keys answer 403 customer_inactive. |
A customer has at most 25 live keys (409 too_many_keys). Rotating a key keeps its customer.
Price rules
| Rule | Charge |
|---|---|
markup |
Your cost, converted at the fixed rate, plus a percentage. |
price_list |
Per model, a price per 1M input, cached input and output tokens in the customer's currency. A model not on the list, or a booking without token counts, is charged at other_percent over cost. |
flat |
A monthly fee that includes included worth of usage at the customer's price; usage is priced at overage_percent over cost and only what exceeds included is charged. |
Budget
monthly_budget creates a spend budget with scope customer. It counts the customer's price in its currency. At the limit, requests answer 429 spend_limit_reached with a message that names the account's limit and says nothing about your console. The Budgets page lists it with its currency.
The customer's usage page
/portal/{token} (the token starts vcp_) needs no sign-in. It is not indexed and sends no Referer. Only the token's SHA-256 is stored, so a lost link cannot be shown again: create a new one, which replaces the old. Archiving the customer removes the link.
The page shows your display name, logo, colour and support email; the plan in plain words; the month's charges as lines (per model, or the plan fee and the usage beyond what it includes); requests and tokens; charges per day; the budget; live keys by prefix; and the customer's open and paid invoices with the pay link. It never shows your cost, margin, markup or exchange rate. /portal/{token}/invoices/{id} is the printable invoice; drafts are never shown.
The logo is a PNG, JPEG or WebP of at most 100 KB, checked by its bytes.
Invoices
- Settings (
/customers/settings): tax percentage and its label (VAT, GST), payment terms in days (due_days), the number prefix and next number, a footer. - Generate drafts for a month: one per customer from the ledger. Monthly-plan customers get an invoice even without usage; usage-based customers only with usage; a customer created after the month is skipped. Generating again rebuilds drafts and leaves approved invoices alone. Tax is rounded once on the subtotal; amounts are in minor units of the currency.
- Approve: only once the month is over (UTC). The invoice gets the next gapless number (
<prefix>-0001), its issue and due dates, and becomes final. States:draft,open,paid,void; an open invoice past its due date readsoverdue. - Send through your own Stripe account, or print it and mark it paid by hand.
Connecting your Stripe account
Paste a restricted key (rk_…) or secret key and the webhook signing secret. The key is checked with one call to Stripe and both are sealed in the vault; only the last four characters, the mode and the account name are shown. Point a Stripe webhook at /api/integrations/stripe/{tenant}/webhook so payments mark invoices paid. Disconnecting forgets both secrets.
Sending is resumable: each Stripe step (customer, tax rate, invoice, items, finalize, send) is recorded with an idempotency key from Venom's ids, so a failure answers 502 stripe_error, keeps what was done, and Send again continues from there without duplicates. Stripe computes its own tax per invoice; a one-cent rounding difference is possible.
The month's CSV export has a row per line, then tax and total; cells are defused against spreadsheet formulas.
Pricing simulator
/customers/simulator replays real usage from the customer ledger under another plan: a markup, a price list, a monthly plan, or a tiered markup (graduated by the month's cost; simulation only). Pick a period (from, to; default the last three completed months, at most 12) and optionally some customers. Per customer it shows revenue now and under the plan, margin, and the change in its currency and in USD; the totals say how many would pay more or less and how many would pay less than their usage costs.
Save a run as a draft (billing:manage), open it later (it runs again on today's ledger), discard it, or apply it: each selected customer's price rule becomes the plan, from then on. Archived customers are skipped. A tiered draft cannot be applied (409 not_applicable).
SLA targets and service credits
On /customers/sla, add a target for a customer (the requests of its keys) or for a route (a model alias; empty means the whole organisation). Targets: availability %, p95 time to first token, error rate %, or any of them, with a minimum request count below which a month has no verdict.
| Measure | Counts against the target |
|---|---|
| Availability | Requests refused or lost: 502, 503, 504, a failed dispatch, a cut stream |
| Error rate | Any 5xx or lost stream |
| p95 TTFT | Over requests that returned a first token |
A caller's own 4xx and your own filters never count. A request the router refused before a job existed leaves no log row, so it is not counted.
Reports are per target and month, month-to-date until six hours after the month ends, then final. Editing a target re-judges only the current month. A breach raises one bell notification and one sla.breach webhook event per target and month.
For a customer target, a finished breached month drafts a service credit: credit_pct of the month's charges, or deep_credit_pct when availability fell below deep_below_pct. Approve puts it on the first open draft invoice after the breach as a negative line (never below zero); Dismiss drops it. Nothing is sent to the customer until a person approves the invoice.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
Customer gets 403 customer_inactive |
The customer is suspended or archived. Resume it on /customers/{id}. |
Customer gets 429 spend_limit_reached |
Its monthly budget is used up. Raise monthly_budget or wait for the month to reset. |
| Approve is disabled | The month is not over yet (UTC). |
Send fails with 502 stripe_error |
Stripe refused a step; the message says which. Fix it in Stripe and Send again: finished steps are not repeated. |
Connecting Stripe answers 409 vault_not_configured |
The deployment has no VENOM_VAULT_KEYS (see Self-hosting Venom Cloud). |
| The portal link shows "not found" | The link was replaced, revoked or the customer archived. Make a new one. |
Related
- MSP mode: manage other organisations rather than resell to customers.
- Settings: webhooks for
sla.breachandsla.credit_drafted. - The admin API routes behind these pages (
/api/admin/v1/customers,/api/admin/v1/customer-invoices,/api/admin/v1/sla,/api/admin/v1/pricing-simulator) are in the cloud API pages of this section, listed on the Venom Cloud overview.