---
title: "List customer entitlement grants"
method: GET
path: "/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants"
tags: ["Entitlements", "Customers"]
---

# List customer entitlement grants

`GET /api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants`

List all grants issued for an entitlement. The entitlement can be defined either by its id or featureKey.

## 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.
- `entitlementIdOrFeatureKey` string, required

## Query parameters

- `includeDeleted` boolean
- `page` integer
- `pageSize` integer
- `offset` integer
- `limit` integer
- `order` 'ASC' | 'DESC' — The order direction.
- `orderBy` 'id' | 'createdAt' | 'updatedAt' — Order by options for grants.

## Response `200`

The request has succeeded.

- GrantV2PaginatedResponse — 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` EntitlementGrantV2[], required — The items in the current page.
    - `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.
    - `amount` number, double, required — The amount to grant. Should be a positive number.
    - `priority` integer — The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.
    - `effectiveAt` string, date-time, required — Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).
    - `minRolloverAmount` number, double — Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))
    - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource.
    - `maxRolloverAmount` number, double — Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. The default value equals grant amount. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))
    - `expiration` ExpirationPeriod — The grant expiration definition
      - `duration` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — The expiration duration enum
      - `count` integer, required — The number of time units in the expiration period.
    - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user.
    - `id` string, required — Readonly unique ULID identifier.
    - `entitlementId` string, required — The unique entitlement ULID that the grant is associated with.
    - `nextRecurrence` string, date-time — The next time the grant will recurr.
    - `expiresAt` string, date-time — The time the grant expires.
    - `voidedAt` string, date-time — The time the grant was voided.
    - `recurrence` 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.

## 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)