Skip to main content
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 is X-Jojapi-Credits-Used; the source Response header x-jojapi-credits-used with default 1 bills:
  • the header’s value when present (an explicit 0 bills nothing);
  • 1 when your server doesn’t send the header, or sends a value that isn’t a non-negative number.
Any header name works, and the gateway strips 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:
The in-band value applies to the first object in the endpoint’s billing list and takes precedence over that object’s usage source and headers. An explicit 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.