List active price overrides

GET

/v1/price-overrides

curl --request GET \
  --url 'http://localhost:8080/v1/price-overrides?limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

• Local development

Active overrides only, newest first. Closed or deleted overrides are not listed. Requires pricing write permission.

Authorizations

• BearerAuth

Parameters

Query Parameters

customer_id

string

Only this customer’s overrides.

price_id

string

Only this price’s overrides.

limit

integer

default: 50 >= 1 <= 100

Rows per page, from 1 to 100. Default 50. Any other value, or one that is not a whole number, is a 422 with param: limit.

offset

integer

0

Rows to skip, 0 or more. Default 0. A negative value, or one that is not a whole number, is a 422 with param: offset.

Responses

200

Overrides

Media typeapplication/json

object

data

required

Array<object>

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

id

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

total

required

How many rows match the request’s filters, on every page, not only this one. The audit log and the customer list’s search and name or email sort say where they stop counting.

integer

Example

{
  "data": [
    {
      "id": "hc_cpo_1a2b3c4d5e6f7890",
      "mode": "per_unit"
    }
  ]
}

422

limit or offset is out of range or not a whole number, or the request sends the removed after cursor (param names it)

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