Skip to main content
This article is for API providers. For the consumer view of per-object pricing and usage, see Credit & Usage.
Billing on JoJ API is built around billable objects: the resources your API charges for. Every API starts with a default Credits object, and you can define more — AI tokens, compute time, bandwidth, storage, or anything else you meter. Each endpoint declares how much of each object a request consumes, and each plan declares how much of each object a subscriber gets (or what they pay per unit).

​
Objects

Manage your objects in Studio → your API → Objects.
  • Name, slug and dimension are set once at creation and cannot be changed. The slug appears in the per-object response headers (X-Jojapi-<slug>-Used), so treat it as part of your API’s contract.
  • The Credits object is created automatically for every API and cannot be deleted. Additional objects can be deleted while no endpoint or plan references them.
  • Slugs use lowercase letters, numbers and hyphens. A few platform names are reserved (credits, user-balance, spent-balance, gateway-response, key).

​
Default usage formula

Each object can carry a default usage formula — the metering rule that endpoints inherit when they don’t define their own. Set it once on the object instead of repeating it on every endpoint. A plain number works as a constant (for example 1 bills one unit per request); a template computes the amount from the response:
If neither the endpoint nor the object defines a formula, nothing is charged for that object — the gateway never invents an amount you didn’t specify.

​
Endpoint billing

Each endpoint’s Details page has a Billing section listing the objects the endpoint consumes. Add or remove objects, and give each one a single cost input: The optional Description is shown to consumers under the cost on your API’s documentation page — use it to explain how the metering works in plain words. The first object in the list is the one that receives the in-band SSE value if you send one (see Reporting usage from your server). Consumers see the effective cost for every endpoint — the fixed amount, or the exact formula that applies (their own or the inherited default) — plus a last-month average for metered objects. Transparent pricing is a platform principle: if you meter it, consumers can see how.

​
Formulas

Formulas are template expressions evaluated against the finished request/response. Useful building blocks:
  • response.json.…, response.headers["…"], request.json.… — read the exchange. Your upstream’s own x-jojapi-* headers are visible to formulas even though the gateway strips them from the client response.
  • default(x, fallback) — fallback when x is missing or empty; a real 0 passes through.
  • isNumber(x) ? x : 2 — a stricter fallback: 2 whenever x isn’t a valid number.
  • min(x, cap) / max(x, floor) — bound a computed amount, e.g. {{min(response.json.tokens, 10)}} never bills more than 10.
  • Also available: round, floor, ceil, abs, toInt, len, contains, split, first, last and more.
Billing rules the platform always enforces:
  • Responses with a 5xx status, and gateway-generated errors, bill 0 on every object — no formula, header or SSE value can charge for a failed response.
  • A formula that fails to evaluate or produces a non-numeric result bills 0 for that object (“charge nothing you can’t compute”). Negative results are clamped to 0.
  • On fixed costs, any computed or reported value is capped at the declared amount.

​
Plans

Plan pricing is per object. When creating a plan in Studio → your API → Plans:
  • Fixed price plans — set an included quota for each object the plan covers (“5,000 Credits and 100,000 AI Tokens per month”). Quotas reset each period and do not carry over.
  • Pay as you go plans — define a graduated tier ladder per object. Each unit is billed at the rate of the tier it falls in.
A subscriber’s plan must cover every object an endpoint consumes — requests to an endpoint whose objects the plan doesn’t include are rejected (402 Plan Does Not Include {Object}). The plan form warns you when your API’s endpoints consume an object the plan leaves out.

​
Changing what a plan covers

Plan pricing is immutable per object: a quota or tier ladder can never be edited or removed once it is on the plan. What you can do is add a new object to an existing plan (Edit plan → Billable Objects → Add an object):
  • The addition applies to all current subscribers immediately and, like the rest of the plan, can never be changed afterwards — pick the quota or tiers carefully.
  • Every subscriber of the plan is automatically notified by email, with the new object and its quota or pricing spelled out. This notice is mandatory and cannot be turned off: subscribers must know when what their plan bills for changes.
  • On a pay as you go plan, a tier priced at 0 covers the object free of charge — the explicit way to grandfather existing subscribers when you start billing a new object on newer plans.
When you introduce a new object to an endpoint that already has subscribers, do it in this order: create the object, add it to every plan that has active subscribers (quota, tiers, or a 0-price tier), and only then attach it to the endpoint. Attaching it first would 402 every subscriber whose plan doesn’t cover it yet.