Get plan

GET

/v1/plans/{id}

curl --request GET \
  --url http://localhost:8080/v1/plans/example \
  --header 'Authorization: Bearer <token>'

• Local development

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string

Responses

200

The plan, with its prices

Media typeapplication/json

A plan as Get, Create and Update plan answer it.

object

id

required

string

tenant_id

string

code

required

string

name

required

string

currency

required

string

billing_interval

required

string

Allowed values: monthly yearly

status

required

string

Allowed values: active archived

base_amount_cents

required

integer format: int64

base_bill_timing

required

When the recurring base fee is invoiced relative to the period it covers. in_arrears: base + usage billed at period end. in_advance: base billed at period start (day 1 on create; cycle-close invoice carries upcoming period’s base + elapsed period’s usage). Usage lines are always arrears regardless of this field. A plan with no base fee is in_arrears. See ADR-031.

string

Allowed values: in_advance in_arrears

prices

required

The plan’s usage prices from now on. A plan’s meters are the meters it has a price for.

Array<object>

One usage price of a plan: a meter, the events it takes (dimension_match) and its rate. The price takes the plan’s currency. Its id stays the same when its rate changes; its meter and dimension_match are its identity and never change.

object

id

required

string

tenant_id

string

plan_id

required

string

meter_id

required

string

dimension_match

required

The labels an event must carry for this price to take it, for example {"model": "claude-opus-4.5", "token_type": "input"}. {} takes every event of the meter. Of the prices whose labels an event carries, the one with the most labels takes it.

object

key

additional properties

string

mode

required

As on PriceShape.

string

Allowed values: per_unit graduated package

unit_amount_cents

required

Price per unit in cents, as a decimal string.

string

tiers

required

Empty ([]) unless mode is graduated.

Array<object>

object

up_to

required

The tier’s upper bound in whole units: the tier prices the quantity above the previous tier’s bound, up to this one. null on the last tier, which has no upper bound. Only the last tier is null, and it must be.

integer format: int64

nullable

unit_amount_cents

required

Price per unit in cents in this tier, as a decimal string.

string

package_size

required

integer format: int64

package_amount_cents

required

Price of one package in cents, as a decimal string.

string

created_at

required

string format: date-time

updated_at

required

When the content shown was saved.

string format: date-time

description

string

tax_code

Stripe tax code for this plan. Absent means the tenant’s default_product_tax_code.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

used

required

Whether a subscription has ever used the plan (canceled ones and scheduled plan changes included). On a plan no one has used, a price change applies at once; on a used plan, from each subscriber’s next billing period, and from the join for a subscriber who first joins the plan in a period after it.

boolean

live_subscription_count

required

Subscriptions on this plan that are not canceled. While it is above 0, base_amount_cents cannot change (see Update plan).

integer

Example

{
  "billing_interval": "monthly",
  "status": "active",
  "base_bill_timing": "in_advance",
  "prices": [
    {
      "id": "hc_prc_1a2b3c4d5e6f7890abcdef12",
      "mode": "per_unit"
    }
  ]
}

404

not_found: no plan with this id in this tenant and mode.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}