A valid request URL is required to generate request examples{
"feature_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"feature_key": "<string>",
"kind": "boolean",
"limit": 123,
"unlimited": true,
"included_quantity": 123,
"rollover": "none",
"rollover_cap": 123,
"overdraft_limit": 123,
"overage_meter_ref": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Set a feature on a plan
Requires billing:write. Says that a plan carries a feature, and with how much of it. One cell of the pricing matrix.
An upsert, because a screen toggling a cell does not know whether that cell already had a row and should not have to. The feature’s kind decides which fields the body may carry, and it is read from the feature rather than taken from you:
boolean— no number at all. It is included or it is not.metered—limitis required.-1is unlimited;0is a real limit, none at all.credit—included_quantityis required (how many units the plan grants per period — or per purchase, when the plan is sold at aone_timeprice: a credit pack), and so are the grant’s terms:rollover(none,allorcapped) andoverdraft_limit(0if the balance may not go below zero).rollover_capis required exactly whenrolloveriscapped, and must be positive — a cap of0isnonespelled worse.overage_meter_refis the one optional term: name it and consumption past the floor can be billed instead of refused, leave it out and it cannot.
The terms are declared, never defaulted: what happens to an unspent balance is part of what somebody pays for, so a cell that says nothing about it is refused rather than read as “it expires”. Sending the wrong field for the kind is refused rather than ignored, in both directions.
A valid request URL is required to generate request examples{
"feature_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"feature_key": "<string>",
"kind": "boolean",
"limit": 123,
"unlimited": true,
"included_quantity": 123,
"rollover": "none",
"rollover_cap": 123,
"overdraft_limit": 123,
"overage_meter_ref": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Cabeçalhos
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Parâmetros de caminho
The plan.
The feature it carries.
Parâmetros de consulta
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Corpo
The ceiling, on a metered feature. -1 is unlimited. Omit on the other kinds.
How many units the plan grants per period, on a credit feature. Omit on the other kinds.
What happens to a credit feature's unspent units when the next grant arrives: they expire, accumulate without bound, or accumulate up to rollover_cap. Required on a credit feature; omit on the other kinds.
none, all, capped, null The ceiling unspent credits accumulate to, in the feature's own units. Required — and positive — exactly when rollover is capped; omit otherwise.
How far below zero a credit feature's balance may go before a spend is refused, in the feature's own units. 0 — the balance may not go below zero — is a real value and must be said. Required on a credit feature; omit on the other kinds.
The gateway's own name for the meter that prices consumption past the floor — a Stripe billing meter's event name, for instance, taken from your own gateway dashboard. Optional on a credit feature and refused on the other kinds. Omitted, the excess is not priced, which means it is refused: this is the one credit term whose absence has a safe answer, so it is the one that is not required.
Resposta
The cell.
One cell of the plan/feature matrix: how much of a feature a plan carries. A feature a plan does not carry is simply absent from the list.
The feature's kind, which decides which of the two numbers below applies.
boolean, metered, credit The ceiling, on a metered feature; null on the other kinds. -1 is unlimited and 0 is a real limit — none at all.
Whether limit is the unlimited sentinel, so a client never has to know the number.
How many credits the plan grants per period — or per purchase, when the plan is sold at a one_time price — on a credit feature; null otherwise.
What happens to unspent credits when the next grant arrives, on a credit feature; null on the kinds that have no balance — never none, which would read as a policy somebody chose.
none, all, capped, null The ceiling unspent credits accumulate to, when rollover is capped; null otherwise.
How far below zero the balance may go before a spend is refused, on a credit feature; 0 means it may not. null on the other kinds.
Where consumption past the floor is priced at the gateway. null where nothing is — and then the spend is refused instead of billed, whatever the environment's credit_overage says.