A valid request URL is required to generate request examples{
"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"
}
}Add a price to a plan
Requires billing:write. Prices a plan in one currency.
A plan has many prices, one per currency and recurrence: R149andUS29 are both correct and neither converts into the other, so each is a number a person chose. amount_minor is an integer in the currency’s minor unit and travels with currency always — an amount without a currency is not a price, and 1000 is R$10.00 in BRL and ¥1000 in JPY.
Exactly one live price may exist per plan per currency per recurrence — that is the offer. Changing the money is not an update: use POST /v1/organization/catalogue/prices/{id}/reprice, which archives the old offer and creates the new one in one step. This endpoint is for the currency or recurrence a plan does not have yet.
A valid request URL is required to generate request examples{
"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"
}
}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 plan this price belongs to.
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
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.
Response
The price. providers is empty until the price is mapped onto a payment provider — until then nothing can charge it.
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.
one_time is a lifetime deal or a one-off purchase and carries no interval; recurring always carries one.
recurring, one_time ISO 4217, uppercase. Never absent — an amount with no currency is not a price.
"BRL"
The amount as an integer in the currency's minor unit. 14900 is R$149.00; in a zero-decimal currency the same integer is 14,900 whole units.
How many decimal places the currency has, so amount_minor can be rendered without hard-coding a divisor: 2 for BRL and USD, 0 for JPY and CLP, 3 for KWD. null only if the stored code is one this API no longer prices in.
null on a one_time price.
day, week, month, year, null How many intervals between charges. null on a one_time price — never 0.
The free period this offer promises before the first charge, in days. null is no trial — never 0, so a screen never decides what a zero-day trial means. Checkouts started on this price carry it by default.
The quantity of this price follows the customer's own member count — derived at checkout and kept in step automatically as members join and leave. Part of the offer, so it is as immutable as the amount.
Whether amount_minor already contains tax. There is no third “undecided” value: the calculation belongs to the payment provider, but this input is yours and is answered when the price is created.
inclusive, exclusive No longer sold. Existing subscriptions keep it.
How this price is known at each payment provider. Empty means nothing can charge it yet. A price may be mapped onto more than one provider, and onto more than one account of the same provider.
Show child attributes
Show child attributes