List a customer's entitlement overrides

Lists the overrides granted to a customer, newest first, including expired ones (active: false) unless active=true. Each has its feature, value, reason, who set it and its expiry.

Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

At a glance

REST: GET /api/v1/customers/{id}/entitlement_overrides
MCP tool: customers_entitlement_overrides_list
Operation ID: customers.entitlement_overrides.list
Scope: Brand
Permission: customers:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the customers:read scope
Since: M5

Request

Path parameters

Field	Type	Description
`id`	`cus_…` ID	The customer's ID (`cus_…`).

Query parameters

Field	Type	Required	Description
`active`	boolean or string	No	true: only overrides that apply now (not expired).
`limit`	integer (1 to 100)	No
`starting_after`	`ceo_…` ID	No	The override's ID (`ceo_…`).

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`ceo_…` ID
`data[].object`	`"entitlement_override"`
`data[].customerId`	`cus_…` ID
`data[].brandId`	`brd_…` ID
`data[].livemode`	boolean
`data[].featureKey`	string
`data[].value`	boolean or number or string
`data[].reason`	string
`data[].setBy`	object	Who granted it.
`data[].setBy.type`	string
`data[].setBy.id`	string
`data[].expiresAt`	date-time or null
`data[].active`	boolean	Whether the override applies at the time of the request (not expired).
`data[].createdAt`	date-time
`has_more`	boolean
`next_cursor`	string or null

Examples

Overrides that apply now

HTTP

GET /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/entitlement_overrides?active=true
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "ceo_01m4ty3c2b5qx7mhd9k8w6s0b2",
      "object": "entitlement_override",
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "featureKey": "seats.max",
      "value": 20,
      "reason": "Goodwill while their team migrates (ticket 4821)",
      "setBy": {
        "type": "user",
        "id": "usr_01m4ty3c2b5qx7mhd9k8w6s0b4"
      },
      "expiresAt": "2026-11-14T00:00:00.000Z",
      "active": true,
      "createdAt": "2026-10-14T10:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a customer ID, or a filter or pagination value is invalid.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such customer in this mode (customers belong to one brand and one mode).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`livemode_not_allowed`	403	You have no live-mode access, so you can't act on live customers.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	You can't read this brand's customers (`customers:read`).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

Overrides that apply now#

Errors#