Promise this customer something the plan does not
Requires billing:write. Grants a feature to one customer regardless of their plan, or withholds one the plan carries.
An upsert, addressed by the pair that identifies it — a screen editing a cell does not know whether the cell already had a row and should not have to. There is no PATCH: a partial edit would have to decide what an omitted enabled means, and every answer to that is wrong in the direction that takes a feature away from somebody paying for it.
enabled and note are both required. enabled because a default of false would withhold a feature by omission; note because an override outlives the conversation that produced it, and a row nobody can explain is a row nobody dares remove.
Which number to send is decided by the feature’s kind, not by the request: a boolean feature carries neither, a metered one needs limit (-1 for unlimited), a credit one needs included_quantity. A withheld feature carries neither whatever its kind — a ceiling on something the customer does not have is a number nobody chose.
Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.
Headers
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. Absent, the session's default organization answers.
Path Parameters
The customer.
One of your own catalogue features. A feature from the other environment answers 404.
Query Parameters
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 Body
true grants the feature, false withholds it. Required.
What was agreed. Required and never blank.
The ceiling, on a metered feature. -1 is unlimited and 0 is a real limit — none at all.
Credits granted per period, on a credit feature. 0 is allowed: the plan carries the feature and grants none of it.
When the promise runs out. Omit for one that does not. A date in the past is refused — it would store a promise that never applied; to withdraw a feature, send enabled: false.
Response
The override as it now stands.
A promise made to one customer on top of their plan — "we agreed to give this account unlimited seats" — or one made against it: "enabled": false withholds a feature the plan carries.
It REPLACES the plan's answer for that feature and never adds to it. Not a maximum: a downward override is as real as an upward one, and a merge rule that could only grant more would refuse half of its own use cases. Additive grants are a credit top-up, which is a ledger rather than this.
The feature's display name, so a list of overrides reads as sentences rather than as keys.
What one unit of the feature is called. Empty on a boolean feature.
Taken from the feature rather than from the request, so it cannot disagree with it.
boolean, metered, credit Whether this override grants the feature or withholds it. Removing the override is a different act from withholding it: removing hands the feature back to whatever the plan says.
The ceiling this customer gets instead of the plan's, on a metered feature. -1 is unlimited; 0 is a real limit — none at all.
The credits this customer is granted per period instead of the plan's.
What was agreed. Required and never blank: an override outlives the conversation, the deal and frequently the person who made it, and a row nobody can explain is a row nobody dares remove.
"Migration deal, agreed with Ana on the 12th — unlimited seats through Q1."
When the promise runs out; null when it does not. An expired override stops applying on its own and the row is kept, so "they had unlimited seats until March" is still answerable.
Whether expires_at has passed, stated rather than left to your clock — resolution compares against the server's.