Credits
Credits are how reading from the library is metered. Every organization has a balance, and each billable API call spends from it.
What costs credits
Credits are charged per API call for the reads below, and per library set for an export. Neither depends on how many variables or values come back: a request that resolves two hundred values costs the same as one that resolves two.
| Call | Cost |
|---|---|
GET /variables/{id} | 1 |
GET /variablesets/{id} | 1 |
GET /variablevalues | 10 |
GET /variablevalues/preview | 10 |
GET /export | 1 per library set exported |
Every other call, including POST, PUT, DELETE and the list endpoints | Free |
| Tags, users, variable values (creating, editing, deleting, listing) | Free |
The costs above are the defaults; they are set per deployment — see CreditCosts.
A cost of 0 makes that call free.
Only successful (2xx) calls are charged. A call that is unauthenticated, forbidden, not found (404) or
malformed (400) delivered nothing and costs nothing.
Opening a library set in the management UI reads it with GET /variablesets/{id}, so it spends 1 credit like any other
caller, and the Variable preview page costs 10 credits per preview.
The balance
An organization's total credits are:
the pricing band's included credits + the organization's Additional credits
The balance is used / total. The management UI shows both on the Organization page, and a caller can read them
from the account API with GET /organizations/me/credits, which returns { "usedCredits": …, "totalCredits": … }.
It needs a JWT but no particular permission — it only ever describes the caller's own organization.
When credits run out
Before a billable call runs, the library set API reads the organization's balance. If the call would take
used + cost above total, it is refused with 429 Too Many Requests and a plain-text body:
Insufficient credits: 3 available, 10 required.
Nothing is charged for a refused call, and a cheaper call can still succeed — with 3 credits left a preview (10)
is refused while a GET /variablevalues (1) is not.
If the balance cannot be read at all, the call fails with 500 rather than being served for free.
How spending is recorded
After a billable call succeeds, the library set API publishes a spend message to the credits-spent Service Bus
queue. The account API consumes the queue and adds the amount to the organization's used credits.
Because that is asynchronous, the balance can lag slightly behind real use: a burst of calls may all be admitted before their spends have been applied. Publishing is best-effort — if it fails, the failure is logged and the request still succeeds.
When credits reset
Used credits go back to 0 each time a subscription payment is applied — the PayPal PAYMENT.SALE.COMPLETED
webhook, which fires on every monthly renewal. An organization whose subscription lapses and falls back to the
default pricing band does not have its used credits reset.
See Shared libraries for how a service opts in.