A valid request URL is required to generate request examples{
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "BRL",
"amount_minor": 123,
"currency_exponent": 123,
"interval_unit": "day",
"interval_count": 123,
"trial_days": 123,
"per_seat": true,
"tax_behavior": "inclusive",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_price_id": "<string>",
"provider_product_id": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z"
},
"archived_price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "BRL",
"amount_minor": 123,
"currency_exponent": 123,
"interval_unit": "day",
"interval_count": 123,
"trial_days": 123,
"per_seat": true,
"tax_behavior": "inclusive",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_price_id": "<string>",
"provider_product_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"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Reprice: supersede a price
Requires billing:write. This is how the money changes. A price cannot be edited — there is no PATCH on one, and the database refuses an in-place edit of the amount, the currency, the kind, the recurrence, the tax posture or the plan.
The reason is that a price is what somebody agreed to pay. A subscription refers to the price it was sold at, so editing the amount silently rewrites what an existing customer consented to and leaves no trace it was ever different.
So repricing is: archive the old price, create the new one. Both happen here, in one transaction, in that order — and the order is not interchangeable. Only one live price may exist per plan per currency per recurrence, so creating first would be refused in the ordinary case (the same offer at a new number), and doing the two calls yourself leaves a window where the plan has no live price at all. A failure leaves the old price exactly where it was.
The new price inherits the plan and nothing else: state the whole offer, currency and trial_days included — a trial omitted here is a trial withdrawn, not one carried over. Existing subscriptions keep the archived price; new customers get the new one.
A valid request URL is required to generate request examples{
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "BRL",
"amount_minor": 123,
"currency_exponent": 123,
"interval_unit": "day",
"interval_count": 123,
"trial_days": 123,
"per_seat": true,
"tax_behavior": "inclusive",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_price_id": "<string>",
"provider_product_id": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z"
},
"archived_price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "BRL",
"amount_minor": 123,
"currency_exponent": 123,
"interval_unit": "day",
"interval_count": 123,
"trial_days": 123,
"per_seat": true,
"tax_behavior": "inclusive",
"archived": true,
"providers": [
{
"provider": "stripe",
"provider_account_id": "<string>",
"provider_price_id": "<string>",
"provider_product_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"
}
}{
"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 price being superseded. It must still be live.
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
A price on the way in — what both creating and repricing send. Every field is stated: there is no PATCH on a price, so no request carrying this is editing one, and "leave that field as it was" has no meaning here.
recurring, one_time ISO 4217, uppercase. Required — an amount with no currency is not a price, and 1000 is R$10.00 in BRL and ¥1000 in JPY.
"BRL"
An integer in the currency's minor unit: 14900 is R$149.00. Never a decimal, and never divided by 100 on the way in — the currency's exponent is 0 for JPY and CLP and 3 for KWD.
x >= 0Whether amount_minor already contains the tax. Required, with no third "undecided" value: we calculate no tax — that is the payment provider's job — but whether the number includes it is an input only the person who typed the number knows, and the moment it matters is the moment somebody is charged.
inclusive, exclusive Required on a recurring price and refused on a one_time one, rather than ignored: a lifetime deal carrying a monthly interval is how it ends up in a renewal job's query.
day, week, month, year How many intervals between charges. Required on recurring, refused on one_time.
x >= 1The free period this offer promises before the first charge, in days. Part of the offer — checkouts started on this price carry it by default — and therefore as immutable as the amount: changing the trial is a reprice. Omit (or send 0) for no trial. Refused on a one_time price rather than ignored: a payment has no trial.
x >= 1The quantity of this price follows the customer's own member count: a checkout on it derives the quantity from the roster and refuses one in the request, and the count is kept in step at the gateway as members join and leave. Part of the offer and as immutable as the amount — changing it is a reprice. Refused on a one_time price rather than ignored: a payment has no period over which a head count could be re-billed.
Resposta
Both rows: the new offer, and the one it superseded. The archived price comes back so a screen showing it does not have to re-read the catalogue to learn it is gone.
One plan's amount in one currency. A plan has many prices, one per currency: selling in BRL and USD is a price per currency, a number you chose, never a conversion at display time.
A price is immutable. Repricing means creating a new price and archiving the old one, because a subscription refers to the price it was sold at and editing the amount would silently change what somebody agreed to pay.
Show child attributes
Show child attributes
One plan's amount in one currency. A plan has many prices, one per currency: selling in BRL and USD is a price per currency, a number you chose, never a conversion at display time.
A price is immutable. Repricing means creating a new price and archiving the old one, because a subscription refers to the price it was sold at and editing the amount would silently change what somebody agreed to pay.
Show child attributes
Show child attributes