Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "key": "pro",
  "name": "<string>",
  "description": "<string>",
  "display_order": 123,
  "archived": true,
  "prices": [
    {
      "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"
    }
  ],
  "features": [
    {
      "feature_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "feature_key": "<string>",
      "limit": 123,
      "unlimited": true,
      "included_quantity": 123
    }
  ],
  "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"
  }
}

Catalogue

Create a plan

Requires billing:write. Adds a plan to one environment’s catalogue. Build it in test and the live catalogue is untouched.

key is yours and permanent: it is the handle your own code compares against and the value promoting a catalogue to live matches on, so it cannot be changed afterwards — renaming it would detach every gate from the plan it names without reporting anything. A plan under a new key is a new plan, and archiving the old one costs nothing.

A plan created here has no price and carries no features yet. Price it with POST /v1/organization/catalogue/plans/{id}/prices and fill the matrix with PUT /v1/organization/catalogue/plans/{planId}/features/{featureId}.

POST

organization

catalogue

plans

Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "key": "pro",
  "name": "<string>",
  "description": "<string>",
  "display_order": 123,
  "archived": true,
  "prices": [
    {
      "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"
    }
  ],
  "features": [
    {
      "feature_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "feature_key": "<string>",
      "limit": 123,
      "unlimited": true,
      "included_quantity": 123
    }
  ],
  "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

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.

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

key

string

required

Lowercase letters, digits, _, - and .. Unique within the environment. Narrow on purpose: it ends up in your source, in a URL and in a payment provider's metadata, and a key that gets escaped differently in three places stops matching in one of them.

Maximum string length: 64

Example:

"pro"

name

string

required

What the pricing table draws.

description

string

default:""

display_order

integer

default:0

Where the plan sits on a pricing table. Yours to decide rather than inferred from the price.

Response

The plan. prices and features are absent — it has none yet.

A plan you sell. Its prices and the features it carries come with it, because a pricing table needs all of them at once.

string<uuid>

key

string

Your own stable handle for the plan — lowercase letters, digits, _, - and .. Unique within an environment, and what promoting a catalogue to live matches on.

Example:

"pro"

name

string

description

string

display_order

integer

Where the plan sits on a pricing table.

archived

boolean

No longer sold. Archived rather than deleted, because subscriptions point at it.

prices

object[]

Show child attributes

features

object[]

Show child attributes

created_at

string<date-time>

Read the catalogue Update a plan

⌘I

Overview

Endpoints

Create a plan

Authorizations

Headers

Query Parameters

Body

Response