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"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Catalogue

Update a plan

Requires billing:write. Changes what a plan says about itself, and whether it is still sold. Send only the fields you are changing.

There is no separate archive endpoint: archived is a state a plan can come back from, so true withdraws it from the pricing table and false puts it back. Archiving is idempotent — the date it stopped being sold does not move if you archive it twice. Nothing is deleted, because subscriptions point at plans and a deleted plan is a subscription that cannot say what it is for.

key is refused rather than ignored: a caller sending it believes it will change, and dropping it in silence is how your own gate stops matching a plan nobody told you was renamed.

PATCH

organization

catalogue

plans

{id}

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"
  }
}

{
  "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.

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

name

string

description

string

display_order

integer

archived

boolean

true withdraws the plan from sale, false puts it back.

Response

The plan as it now stands. prices and features are not included — re-read the catalogue for those.

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>

Create a plan Add a price to a plan

⌘I

Overview

Endpoints

Update a plan

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response