> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jojapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billable Objects

> Define what your API charges for — Credits, AI tokens, compute time, or any resource you meter.

> This article is for API providers. For the consumer view of per-object pricing and usage, see [Credit & Usage](/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](/consumers/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:

```
{{default(response.headers["x-jojapi-credits-used"], 1)}}
```

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:

| You enter                                          | Meaning                                                                                                                                               |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| A plain number (`5`)                               | Fixed: the request always bills exactly this many units. The amount is also an upper bound — a response can lower it (see below) but never exceed it. |
| A formula (`{{response.json.usage.total_tokens}}`) | Metered: the amount is computed from the final response on every request.                                                                             |
| Nothing (empty)                                    | Metered: inherits the object's default formula. With no default either, the object bills 0.                                                           |

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](/studio/adjusting-credit-usage)).

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). The plan form warns you when your API's endpoints consume an object the plan leaves out.

Like all plan pricing, per-object quotas and tiers are immutable once the plan is created; publish a new plan (and optionally transfer subscribers) to change pricing.