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 source

Every object has a default usage source — 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 fixed amount (for example 1 bills one unit per request) or one of the usage sources that read the amount from the response, such as the response header x-jojapi-credits-used with default 1. The default is required when you create an object (Studio suggests a fixed amount of 1 for the Requests dimension). To bill nothing unless an endpoint sets its own source, say so explicitly with a fixed amount of 0 — the gateway never invents an amount you didn’t specify, so an object created before this rule that still has no default bills 0 for those endpoints until you set one.

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: 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. To bill many endpoints the same way at once, select them on the Endpoints page and choose Set billing: pick the object, enter the cost and description, and every selected endpoint gets that element — endpoints already billing the object are updated in place, and their other objects are left unchanged. 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 usage source that applies (the endpoint’s 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.

Usage sources on the edge gateway

Every cost is one of these structured usage sources; metered ones read the amount from the finished response. The cost input offers: Header, header key and JSON field sources take an optional default, billed when the value is missing, not a number or negative; without one, 0 is billed. The gateway strips x-jojapi-* headers from the client response, so a header such as x-jojapi-credits-used can carry the amount without consumers seeing it. An object no source covers bills what the response reports in the gateway’s usage headers (x-jojapi-usage, x-jojapi-<slug>-used), and otherwise its fixed amount, or 0 when metered; see Adjusting usage. A formula from the classic gateway that could not be converted into a source is shown read-only and no longer evaluated: until you replace it, the object bills only what those headers report.

Billing rules

The platform always enforces:
  • Responses with a 5xx status, and gateway-generated errors, bill 0 on every object — no usage source, header or SSE value can charge for a failed response.
  • Amounts are whole, non-negative units: a decimal value is cut to its integer part (2.9 bills 2), and a negative one counts as missing.
  • On fixed costs, a reported value is capped at the declared amount: the response can lower a request’s bill, never raise it.

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.

How plans appear on the pricing page

The pricing page shows every public plan. You decide how they are arranged by naming them:
  • Plans with the same name share one card. Give your monthly and yearly plans of a tier the same name, for example “Pro”, and buyers switch between them with the period switch above the cards (Monthly, Yearly…), which changes every card at once. Plans of one period with the same name and different rate limits share the card too, with a rate limit picker on it.
  • An unnamed plan gets a card of its own.
  • Two public plans with the same name can’t have the same period and rate limit, since buyers couldn’t tell them apart on the card. Creating, renaming or editing a plan into that state is refused (plan_card_conflict); an import creates such a plan as a draft instead.
  • When a longer period costs less per month for at least the same quota per month (12,000 a year against 1,000 a month), the card and the switch show the saving.
  • A free plan stays on the page whichever period is chosen. Private plans show only to the users you allow, on cards of their own (see Custom Users).
The Plans table marks a public plan Redundant when another public plan with the same period and rate limit offers at least its quotas and features for the same price or less. Buyers still see it; making it private takes it off the page.

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.