---
title: "Get entitlements state"
method: GET
path: "/api/v1/customers/{id}/entitlements"
tags: ["Entitlements"]
---

# Get entitlements state

`GET /api/v1/customers/{id}/entitlements`

Retrieves the effective entitlements for a customer or resource, including feature and credit entitlements.

**Warning:** This REST API endpoint lacks built-in client-side caching, fallback mechanisms, and low-latency guarantees. It is not recommended for hot-path entitlement checks. For production use, consider using the Stigg Node Server SDK with caching or the Sidecar for low-latency cached responses.

## Path parameters

- `id` string, required

## Query parameters

- `resourceId` string

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Response `200`

The entitlements state including feature and credit entitlements, and an optional access denied reason.

- EntitlementsStateResponseDto — Response object
  - `data` object, required — The effective entitlements state for a customer or resource.
    - `entitlements` union[], required — List of effective feature and credit entitlements
      - union
        - object
          - `isGranted` boolean, required
          - `type` 'FEATURE', required
          - `accessDeniedReason` 'FeatureNotFound' | 'CustomerNotFound' | 'CustomerIsArchived' | 'CustomerResourceNotFound' | 'NoActiveSubscription' | 'NoFeatureEntitlementInSubscription' | 'RequestedUsageExceedingLimit' | 'RequestedValuesMismatch' | 'BudgetExceeded' | 'Unknown' | 'FeatureTypeMismatch' | 'Revoked' | 'InsufficientCredits' | 'EntitlementNotFound', nullable, required
          - `feature` object
            - `id` string, required — The unique reference ID of the entitlement.
            - `displayName` string, required — The human-readable name of the entitlement, shown in UI elements.
            - `featureType` 'BOOLEAN' | 'NUMBER' | 'ENUM', required — The type of feature associated with the entitlement.
            - `featureStatus` 'NEW' | 'SUSPENDED' | 'ACTIVE', required — The current status of the feature.
          - `usageLimit` number, nullable
          - `hasUnlimitedUsage` boolean
          - `resetPeriod` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR', nullable
          - `currentUsage` number
          - `usagePeriodAnchor` string, date-time — The anchor for calculating the usage period for metered entitlements with a reset period configured
          - `usagePeriodStart` string, date-time — The start date of the usage period for metered entitlements with a reset period configured
          - `usagePeriodEnd` string, date-time — The end date of the usage period for metered entitlements with a reset period configured
          - `entitlementUpdatedAt` string, date-time — Timestamp of the last update to the entitlement grant or configuration.
          - `validUntil` string, date-time — The next time the entitlement should be recalculated
        - object
          - `isGranted` boolean, required
          - `type` 'CREDIT', required
          - `accessDeniedReason` 'FeatureNotFound' | 'CustomerNotFound' | 'CustomerIsArchived' | 'CustomerResourceNotFound' | 'NoActiveSubscription' | 'NoFeatureEntitlementInSubscription' | 'RequestedUsageExceedingLimit' | 'RequestedValuesMismatch' | 'BudgetExceeded' | 'Unknown' | 'FeatureTypeMismatch' | 'Revoked' | 'InsufficientCredits' | 'EntitlementNotFound', nullable, required
          - `usageLimit` number, required
          - `currentUsage` number, required
          - `usageUpdatedAt` string, date-time, required — Timestamp of the last update to the credit usage.
          - `currency` object, required — The currency associated with a credit entitlement.
            - `currencyId` string, required — The unique identifier of the custom currency.
            - `displayName` string, required — The display name of the currency.
            - `description` string, nullable — A description of the currency.
            - `unitSingular` string, nullable — The singular form of the currency unit.
            - `unitPlural` string, nullable — The plural form of the currency unit.
            - `metadata` object, nullable — Additional metadata associated with the currency.
          - `entitlementUpdatedAt` string, date-time — Timestamp of the last update to the entitlement grant or configuration.
          - `validUntil` string, date-time — The next time the entitlement should be recalculated
          - `usagePeriodEnd` string, date-time — The end date of the current billing period for recurring credit grants.
    - `accessDeniedReason` 'CustomerNotFound' | 'NoActiveSubscription' | 'CustomerIsArchived', nullable, required — Reason why entitlements access was denied, if applicable

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `404` — Entitlements not found.
- `429` — Too many requests.

---

[API](https://skmtc.net/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.net/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stiggio/stigg-api/revisions/3e2c8cfcd035/schema)