A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"kind": "percent",
"percent_off": 123,
"amount_minor": 123,
"currency": "BRL",
"currency_exponent": 123,
"duration": "once",
"duration_months": 123,
"max_redemptions": 123,
"expires_at": "2023-11-07T05:31:56Z",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_coupon_id": "<string>"
}
],
"created_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"
}
}Archive a coupon
Requires billing:write. Withdraws the offer: the coupon can no longer be applied to a new checkout.
The only edit a coupon accepts, and idempotent — archiving twice does not move the date the offer was withdrawn. Subscriptions already discounted keep their discount: the gateway holds the promise, and this bounds new redemptions only.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"kind": "percent",
"percent_off": 123,
"amount_minor": 123,
"currency": "BRL",
"currency_exponent": 123,
"duration": "once",
"duration_months": 123,
"max_redemptions": 123,
"expires_at": "2023-11-07T05:31:56Z",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_coupon_id": "<string>"
}
],
"created_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"
}
}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
The coupon to withdraw. One 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 Response
The coupon, now archived.
A discount you promise on your own catalogue. Its terms are immutable — a subscription bought under a coupon keeps producing invoices that only make sense against the terms as they were — so there is no update: a different discount is a new coupon, and this one is withdrawn by archiving.
The fields of the other kind and the other durations are null, never 0: 0% off and an amount of nothing are numbers a screen would render.
What the payer sees beside the discount at the gateway's checkout.
percent, amount A whole percentage, 1–100. null on an amount coupon.
The amount off, an integer in the currency's minor unit. null on a percent coupon.
ISO 4217, uppercase — the amount never travels without it. null on a percent coupon.
"BRL"
How many decimal places the currency has, so amount_minor can be rendered without hard-coding a divisor. null on a percent coupon.
How long the discount keeps applying to a recurring subscription: the first invoice, duration_months of them, or every one.
once, repeating, forever How many invoices repeating covers. null on the other durations.
How many redemptions the offer is good for, across all customers. null is no cap.
When the offer stops being redeemable. null is never. Subscriptions already discounted keep their discount either way.
Withdrawn: no new checkout may apply it. Existing discounts survive.
How this coupon is known at each payment provider. Empty is the ordinary state — the gateway's coupon is minted by the first checkout that applies this one on each account.
Show child attributes
Show child attributes