Add a price to a plan
const url = 'http://localhost:8080/v1/plans/example/prices';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"meter_id":"example","dimension_match":{"additionalProperty":"example"},"mode":"per_unit","unit_amount_cents":"example","tiers":[{"up_to":1,"unit_amount_cents":"example"}],"package_size":1,"package_amount_cents":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/plans/example/prices \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "meter_id": "example", "dimension_match": { "additionalProperty": "example" }, "mode": "per_unit", "unit_amount_cents": "example", "tiers": [ { "up_to": 1, "unit_amount_cents": "example" } ], "package_size": 1, "package_amount_cents": "example" }'On a plan no subscription has used, the price applies at once
(effective: now). On a used plan it applies from each
subscriber’s next billing period (effective: next_period); until
then the plan’s other prices bill the meter’s usage as before. A
subscriber who first joins the plan in a period after the add pays
it from the join (see PriceWrite).
A price that names a removed price’s meter and dimension_match
adds that price back under its id. Its old customer overrides do
not come back.
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”One price to add to a plan.
object
The labels an event must carry for the price to take it.
Values are strings of 1 to 100 characters, keys too; at
most 16 labels. Omitted or {} takes every event of the
meter. Two prices of one plan and meter that could both take
one event with the same number of labels are refused (409
price_conflict).
object
per_unit bills quantity × unit_amount_cents. graduated bills each tier’s part of the quantity at that tier’s rate. package bills ceil(quantity ÷ package_size) × package_amount_cents: a part package bills as a whole one.
Price per unit in cents, as a decimal string (e.g. “0.0003” = $3.00 per 1,000,000 units). Used when mode is per_unit. 0 or more, under 10^18, at most 12 decimal places (trailing zeros do not count), and at most 100 characters. A JSON number is also read. A value outside them is refused with 422 and param naming the field. Invoice line amounts round to whole cents.
Used when mode is graduated. Each up_to is a whole number above the one before. The last tier has up_to: null (no upper bound), and only the last. Otherwise 422 with param tiers. A tier’s rate takes the limits of unit_amount_cents; a refusal names tiers[i].unit_amount_cents (i counts from 0).
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.
Used when mode is package. Must be above 0.
Price of one package in cents, as a decimal string (e.g. “0.2” with package_size 1000 = $0.002 per 1,000 units), with the limits of unit_amount_cents. Used when mode is package.
Responses
Section titled “Responses”The price, and when it applies
The answer to a price write: the price, and when the write applies.
now: no subscription has used the plan, so it applies at once.
next_period: each subscriber pays the new content from their next
billing period; the current period keeps the prices it started with.
A subscriber who first joins the plan in a period after the write
gets it from the join: a subscription that starts after it (after a
trial, from the trial’s end), an immediate plan change onto the
plan, or an item added on it. Each is priced from that moment by the
plan’s prices then, so a subscription that starts later on the day
of the write bills a price added that day and not one removed that
day. A subscription that was on the plan earlier in the period and
joins it again keeps the prices of its first join until its next
period. On a test clock, the write takes effect just after the
clock’s time: a subscriber who joins at that same clock time gets
the earlier prices.
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.
True on the answer to a removal.
On a removal, the customer overrides of the price it ended. Each ends when the removal takes effect for its customer.
object
Example
{ "id": "hc_prc_1a2b3c4d5e6f7890abcdef12", "mode": "per_unit", "effective": "now"}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" }}price_exists: the plan already has a price on this meter with
this dimension_match; edit it instead. price_conflict: a
price on the plan and meter could take the same events with the
same number of labels, so neither would win; the message names
it. Add a label to make one more specific, or give a shared
label another value. meter_overlap: the meter is new to a used
plan, and a customer on the plan already has it on another item,
of the same subscription or another 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: an unknown meter, a label that is not a
string or breaks the limits, a rate outside its limits, a price
shape that cannot be billed, or an unknown field (param names
it).
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" }}