A valid request URL is required to generate request examples{
"kind": "downgrade",
"enabled": true,
"headline": "<string>",
"target_price_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pause_months": 123,
"coupon_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z"
}{
"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"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Configure a save offer
Requires billing:write. One configuration per kind per environment, so this is a PUT: a screen toggling an offer does not know whether that offer already had a row and should not have to.
Each kind takes exactly one parameter and the others are ignored — downgrade takes target_price_id (a price, not a plan: the currency and interval somebody is already paying in are not derivable from a plan alone), pause takes pause_months (1–3; beyond that the honest offer is to cancel and come back), and discount takes coupon_id.
enabled defaults to true. An omitted flag on a request that carries a price would otherwise read as “turn this off”, which is a configuration somebody just wrote silently not being made.
Re-configuring a kind replaces its parameters rather than merging them, so a downgrade switched to a discount does not keep the price it used to point at.
Whether the offer is ever shown depends on two more things this call does not decide: the reason the customer gives, and whether the connected gateway can perform the act.
A valid request URL is required to generate request examples{
"kind": "downgrade",
"enabled": true,
"headline": "<string>",
"target_price_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pause_months": 123,
"coupon_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z"
}{
"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"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
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.
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: 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.
Path Parameters
Which save offer. The list is closed because each value names an act this API performs at a gateway.
downgrade, pause, discount 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
Make the offer. Defaults to true.
What the person reads. Empty leaves the portal's own wording.
downgrade only. Must be a live recurring price in this environment.
pause only.
1 <= x <= 3discount only. Must be a coupon in this environment that is not archived.
Response
The offer as it now stands.
A save offer as the tenant configured it, per environment. Exactly one of the three parameters is set, decided by kind; the other two are null.