Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Create a customer price override

POST

/v1/price-overrides

const url = 'http://localhost:8080/v1/price-overrides';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"customer_id":"example","price_id":"example","mode":"per_unit","unit_amount_cents":"example","tiers":[{"up_to":1,"unit_amount_cents":"example"}],"package_size":1,"package_amount_cents":"example","reason":"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/price-overrides \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "customer_id": "example", "price_id": "example", "mode": "per_unit", "unit_amount_cents": "example", "tiers": [ { "up_to": 1, "unit_amount_cents": "example" } ], "package_size": 1, "package_amount_cents": "example", "reason": "example" }'

Gives one customer its own rate for one plan price. The override is keyed by the price, so it keeps applying when the price’s rate changes; removing the price ends it. If the customer already has an active override for that price, it is closed and replaced by this one. A new or replaced rate applies from the customer’s next billing period, in the customer’s time (its test clock’s, if it has one); the current period keeps the rate it started with. It applies from the join when a subscription of the customer first joins the plan in a period after it is created: an override created before a subscription starts (after a trial, before the trial ends), even on the same day, applies from its first period. On a test clock, it takes effect just after the clock’s time, so a subscription created at that same clock time bills the list price; advance the clock first. The override takes the plan’s currency. A plan swap does not carry it: the new plan’s price is another price.

Authorizations

BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

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 Body^required

application/json

object

customer_id

required

string

price_id

required

The plan price to override.

string

mode

required

As on PriceShape, also for the fields a mode does not use.

string

Allowed values: per_unit graduated package

unit_amount_cents

Price per unit in cents, as a decimal string. 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.

string

tiers

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.

Array<object>

object

up_to

integer format: int64

nullable

unit_amount_cents

Price per unit in cents in this tier, as a decimal string, with the limits of unit_amount_cents. A refusal names tiers[i].unit_amount_cents (i counts from 0).

string

package_size

Used when mode is package. Must be above 0.

integer format: int64

package_amount_cents

Price of one package in cents, as a decimal string, with the limits of unit_amount_cents. Used when mode is package.

string

reason

string

Responses

201

The new override

application/json

A customer’s negotiated rate for one plan price. It keeps applying when the price’s rate changes, and ends when the price is removed. It takes the plan’s currency.

object

required

string

tenant_id

string

customer_id

required

string

price_id

required

The plan price this override replaces the rate of, for this customer.

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

reason

string

active

required

boolean

created_at

required

When the override starts, in the customer’s time: wall time, or its test clock’s time. A subscription already on the plan gets it from its next period; one that first joins the plan in a period after this instant gets it from the join.

string format: date-time

deactivated_at

When the override ended, in the customer’s time. Absent while it is active.

string format: date-time

updated_at

required

string format: date-time

Example

{
  "id": "hc_cpo_1a2b3c4d5e6f7890",
  "mode": "per_unit"
}

400

invalid_request: the body is not valid JSON.

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

404

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

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

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

409

already_exists: another request created an override for the same customer and price at the same moment. Retry. invalid_state: the price was removed from its plan.

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

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

422

validation_error: a missing field, an unknown price, a rate that is not a number or is outside its limits, a price shape that cannot be billed (bad tier table, package size of 0), or an unknown field at any depth (param names it; the body must use only the fields listed here).

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

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

Create a customer price override

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Example

404

Example

409

Example

422

Example

Request Body^required