--- title: "List customer entitlements" method: GET path: "/api/v2/customers/{customerIdOrKey}/entitlements" tags: ["Entitlements"] --- # List customer entitlements `GET /api/v2/customers/{customerIdOrKey}/entitlements` List all entitlements for a customer. For checking entitlement access, use the /value endpoint instead. ## Path parameters - `customerIdOrKey` union, required — ULID (Universally Unique Lexicographically Sortable Identifier) or external unique key. - string — ULID (Universally Unique Lexicographically Sortable Identifier). - string — ExternalKey is a looser version of key. ## Query parameters - `includeDeleted` boolean - `page` integer - `pageSize` integer - `order` 'ASC' | 'DESC' — The order direction. - `orderBy` 'createdAt' | 'updatedAt' — Order by options for entitlements. ## Response `200` The request has succeeded. - EntitlementV2PaginatedResponse — Paginated response - `totalCount` integer, required — The total number of items. - `page` integer, required — The page index. - `pageSize` integer, required — The maximum number of items per page. - `items` EntitlementV2[], required — The items in the current page. - union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `type` 'metered', required - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `issue` IssueAfterReset — Issue after reset - `amount` number, double, required — The initial grant amount - `priority` integer — The priority of the issue after reset - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `lastReset` string, date-time, required — The time the last reset happened. - `currentUsagePeriod` Period, required — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - `customerKey` string — The identifier key unique to the customer - `customerId` string, required — The identifier unique to the customer - object — A static entitlement. - `type` 'static', required - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - `customerKey` string — The identifier key unique to the customer - `customerId` string, required — The identifier unique to the customer - object — Entitlement template of a boolean entitlement. - `type` 'boolean', required - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - `customerKey` string — The identifier key unique to the customer - `customerId` string, required — The identifier unique to the customer ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/versions/927d82ffe647/schema)