This article is for API providers. Billing is configured per billable object — this page covers the ways your server can report the actual amount at request time.The usual way to meter usage is a usage source on the endpoint’s billing element (or the object’s default source): the gateway reads the amount from the finished response and bills it. Your server reports the amount in one of three ways.
Reporting with a response header
Return the amount in a header and choose the Response header source with that header’s name and a default. The conventional header isX-Jojapi-Credits-Used; the source Response header x-jojapi-credits-used with default 1 bills:
- the header’s value when present (an explicit
0bills nothing); 1when your server doesn’t send the header, or sends a value that isn’t a non-negative number.
x-jojapi-* headers from the client response. A header that carries several amounts, such as x-billing: Images=3; Videos=1, takes the Header key=value source; an amount in the JSON body, such as usage.total_tokens, the JSON field source.
Reporting with the gateway’s usage headers
Without any source configured, your server (or your Worker in code mode) can name the amounts itself. The gateway reads these headers for every object no usage source covers:x-jojapi-usage holds one entry per object slug; x-jojapi-<slug>-used is the shorthand for a single object, read when x-jojapi-usage does not name it. A configured usage source wins over both.
Reporting inside SSE streams
For Server-Sent Events responses (content-type: text/event-stream), send a message during the stream:
0 means “charge nothing” — it never falls through to a default.
Rules
- On fixed costs, reported values are capped at the declared amount — you can lower a request’s bill, never raise it above what consumers see.
- Responses with a 5xx status bill 0 on every object, regardless of any header, SSE message or usage source. Failed responses are always free.
- Values are whole, non-negative units: a decimal is cut to its integer part, and anything else counts as missing, so the source’s default, the fixed amount, or 0 applies.
