Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "key": "api_calls",
  "name": "<string>",
  "description": "<string>",
  "unit_name": "<string>",
  "archived": true,
  "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 feature

Requires billing:write. Declares one thing your product does, that your plans may or may not include. Yours, not UserKit’s — the key is a string your code gates on, and this namespace never meets the one our own plans use.

The kind decides what else the feature must carry, in both directions:

boolean — no unit_name and no reset_period. It counts nothing.
metered — both are required. A limit with no unit is a number nobody can read, and the reset period is what makes “how much this period” answerable.
credit — unit_name is required and reset_period is forbidden: a balance is granted and spent, never reset. The grant’s cadence belongs to the plan.

How a feature is measured is permanent once created — see PATCH /v1/organization/catalogue/features/{id}.

A feature created here is on no plan. Put it on one with PUT /v1/organization/catalogue/plans/{planId}/features/{featureId}.

POST

organization

catalogue

features

Error

A valid request URL is required to generate request examples

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "key": "api_calls",
  "name": "<string>",
  "description": "<string>",
  "unit_name": "<string>",
  "archived": true,
  "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"
  }
}

Autorizações

Authorization

string

header

obrigatório

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

Cabeçalhos

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.

Parâmetros de consulta

environment

enum<string>

padrão: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.

Opções disponíveis:

live,

test

Corpo

application/json

key

string

obrigatório

Lowercase letters, digits, _, - and .. Unique within the environment. What your own code compares against.

Maximum string length: 64

Exemplo:

"api_calls"

name

string

obrigatório

kind

enum<string>

obrigatório

Opções disponíveis:

boolean,

metered,

credit

description

string

padrão:""

unit_name

string

What one unit is called (seats, runs, tokens). Required for metered and credit, forbidden for boolean.

reset_period

enum<string>

Required for metered and forbidden for the other kinds. billing_period is renewal to renewal rather than a calendar unit.

Opções disponíveis:

day,

week,

month,

year,

billing_period

Resposta

The feature.

One thing your product does, that your plans may or may not include. Yours, not UserKit's — the key is a string your code gates on.

string<uuid>

key

string

Lowercase letters, digits, _, - and .. What your own code compares against.

Exemplo:

"api_calls"

name

string

description

string

kind

enum<string>

boolean is on or off. metered is counted against a ceiling that resets. credit is spent from a balance — a counter answers “how much this period”, a balance answers “how much is left”.

Opções disponíveis:

boolean,

metered,

credit

unit_name

string

What one unit is called (seats, runs, tokens). Empty on a boolean feature and required on the others: a limit with no unit is a number nobody can read.

reset_period

enum<string> | null

How a metered feature's counter is bucketed; null for the other kinds. It belongs to the feature rather than to the plan, so a counter keeps its shape when a customer changes plan mid-period.

Opções disponíveis:

day,

week,

month,

year,

billing_period,

null

archived

boolean

created_at

string<date-time>

Archive a price Update a feature

⌘I

Visão geral

Endpoints

Create a feature

Autorizações

Cabeçalhos

Parâmetros de consulta

Corpo

Resposta