Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "BRL",
  "amount_minor": 123,
  "currency_exponent": 123,
  "interval_count": 123,
  "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"
  }
}

Catalogue

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: R $149 and US$ 29 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.

POST

organization

catalogue

plans

{id}

prices

Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "BRL",
  "amount_minor": 123,
  "currency_exponent": 123,
  "interval_count": 123,
  "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

Authorization

string

header

required

A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.

Headers

X-Organization-Id

string

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

string<uuid>

required

The plan this price belongs to.

Query Parameters

environment

enum<string>

default:live

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.

Available options:

live,

test

Body

application/json

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.

kind

enum<string>

required

Available options:

recurring,

one_time

currency

string

required

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.

Example:

"BRL"

amount_minor

integer<int64>

required

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.

Required range: x >= 0

tax_behavior

enum<string>

required

Whether 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.

Available options:

inclusive,

exclusive

interval_unit

enum<string>

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.

Available options:

day,

week,

month,

year

interval_count

integer

How many intervals between charges. Required on recurring, refused on one_time.

Required range: x >= 1

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.

string<uuid>

kind

enum<string>

one_time is a lifetime deal or a one-off purchase and carries no interval; recurring always carries one.

Available options:

recurring,

one_time

currency

string

ISO 4217, uppercase. Never absent — an amount with no currency is not a price.

Example:

"BRL"

amount_minor

integer<int64>

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.

currency_exponent

integer | null

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.

interval_unit

enum<string> | null

null on a one_time price.

Available options:

day,

week,

month,

year,

null

interval_count

integer | null

How many intervals between charges. null on a one_time price — never 0.

tax_behavior

enum<string>

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.

Available options:

inclusive,

exclusive

archived

boolean

No longer sold. Existing subscriptions keep it.

providers

object[]

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

created_at

string<date-time>

Update a plan Set a feature on a plan

⌘I

Overview

Endpoints

Add a price to a plan

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response