Error

A valid request URL is required to generate request examples

{
  "price": {
    "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"
  },
  "archived_price": {
    "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

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 included. Existing subscriptions keep the archived price; new customers get the new one.

POST

organization

catalogue

prices

{id}

reprice

Error

A valid request URL is required to generate request examples

{
  "price": {
    "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"
  },
  "archived_price": {
    "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 price being superseded. It must still be live.

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

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.

price

object

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

archived_price

object

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.

Show child attributes

Remove a feature from a plan Archive a price

⌘I

Overview

Endpoints

Reprice: supersede a price

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response