Update plan
const url = 'http://localhost:8080/v1/plans/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","description":"example","base_amount_cents":1,"base_bill_timing":"in_advance","status":"active","tax_code":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url http://localhost:8080/v1/plans/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "description": "example", "base_amount_cents": 1, "base_bill_timing": "in_advance", "status": "active", "tax_code": "example" }'A field left out keeps its current value. To clear description
or tax_code, send an empty string. code, currency and
billing_interval cannot be changed: sending one is a 422 naming
it. The plan’s
usage prices change through /v1/plans/{id}/prices.
base_amount_cents cannot change while a subscription that is not
canceled uses the plan (live_subscription_count on Get plan):
create a new plan instead. It can be set to 0. base_bill_timing
cannot change once a subscription has used the plan (used). A
plan with no base fee must be in_arrears. name, description,
tax_code and status change at once.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Makes the call safe to retry. Send a unique value (a UUID works) and
the same value on every retry. For 24 hours, a repeat with the same
key, method, path and body gets the first response again, with an
Idempotent-Replayed: true header, instead of running again. The
error cases are in docs/api-surface.md. The usage routes do not take
it: each usage event carries its own idempotency_key.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Whitespace is trimmed. Empty or omitted keeps the current name.
Whitespace is trimmed. Omit to keep the current description; an empty string clears it.
0 or more. Omit to keep the current base fee.
Stripe product tax code. Omit to keep the current code; an empty string clears it, and the base fee then uses the tenant’s default_product_tax_code.
Responses
Section titled “Responses”The updated plan, with its prices
A plan as Get, Create and Update plan answer it.
object
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.
The plan’s usage prices from now on. A plan’s meters are the meters it has a price for.
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
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
As on PriceShape.
Price per unit in cents, as a decimal string.
Empty ([]) unless mode is graduated.
object
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.
Price per unit in cents in this tier, as a decimal string.
Price of one package in cents, as a decimal string.
When the content shown was saved.
Stripe tax code for this plan. Absent means the tenant’s default_product_tax_code.
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.
Subscriptions on this plan that are not canceled. While it
is above 0, base_amount_cents cannot change (see Update
plan).
Example
{ "billing_interval": "monthly", "status": "active", "base_bill_timing": "in_advance", "prices": [ { "id": "hc_prc_1a2b3c4d5e6f7890abcdef12", "mode": "per_unit" } ]}invalid_request: the body is not valid JSON.
object
object
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.
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.
Example
{ "error": { "type": "invalid_request_error" }}not_found: no plan with this id in this tenant and mode.
object
object
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.
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.
Example
{ "error": { "type": "invalid_request_error" }}invalid_state: another write changed the plan’s base fee
during this one.
object
object
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.
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.
Example
{ "error": { "type": "invalid_request_error" }}validation_error: the base fee changed while live
subscriptions use the plan (param plan), base_bill_timing
changed on a used plan or is in_advance with a base of 0, a
negative base fee, a status other than active or
archived, an invalid tax_code, or an unknown field such as
meter_ids (a plan’s meters are its prices’ meters).
object
object
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.
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.
Example
{ "error": { "type": "invalid_request_error" }}internal_error. Nothing is changed.
object
object
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.
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.
Example
{ "error": { "type": "invalid_request_error" }}