Remove a price from a plan

DELETE

/v1/plans/{id}/prices/{price_id}

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

• Local development

On a plan no subscription has used, the price is gone at once. On a used plan it takes no part from each subscriber’s next billing period; the current period keeps it. A subscriber who first joins the plan in a period after the removal does not pay it (see PriceWrite). The removal ends every customer override of the price, each when the removal takes effect for its customer, and the answer names them (ended_overrides). Adding the price back later keeps its id but not the overrides.

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string

price_id

required

string

Responses

200

The removed price, when the removal applies, and the overrides it ended

Media typeapplication/json

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

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

effective

required

string

Allowed values: now next_period

removed

True on the answer to a removal.

boolean

ended_overrides

On a removal, the customer overrides of the price it ended. Each ends when the removal takes effect for its customer.

Array<object>

object

id

required

string

customer_id

required

string

Example

{
  "id": "hc_prc_1a2b3c4d5e6f7890abcdef12",
  "mode": "per_unit",
  "effective": "now"
}

404

not_found: no such plan, or no such price on it (a removed price included).

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