---
title: "List subscription entitlements"
method: GET
path: "/api/v1/subscriptions/{subscription_id}/entitlements"
tags: ["Subscriptions", "Entitlements"]
---

# List subscription entitlements

`GET /api/v1/subscriptions/{subscription_id}/entitlements`

## Path parameters

- `subscription_id` string, MeteroidId, required

## Response `200`

Effective entitlements for this subscription, with live usage

- EffectiveEntitlementListResponse
  - `data` EffectiveEntitlement[], required
    - `feature` FeatureRef, required
      - `id` string, MeteroidId, required
      - `name` string, required
      - `product` union
        - ExistingProductRef
          - `id` string, MeteroidId, required
        - NewProductRef
          - `fee_structure` union, required
            - RateFeeStructure
            - SlotFeeStructure
              - …
            - CapacityFeeStructure
              - …
            - UsageFeeStructure
              - …
            - ExtraRecurringFeeStructure
              - …
            - OneTimeFeeStructure
          - `fee_type` 'RATE' | 'SLOT' | 'CAPACITY' | 'USAGE' | 'EXTRA_RECURRING' | 'ONE_TIME', required
          - `name` string, required
    - `origin` ResolvedOrigin, required — Resolved entity that contributed the winning entitlement value, with a human-readable label.
      - `entity` union, required
        - FeatureEntitlementEntity
          - `id` string, MeteroidId, required
        - PlanEntitlementEntity
          - `id` string, MeteroidId, required
        - PlanVersionEntitlementEntity
          - `id` string, MeteroidId, required
        - AddOnEntitlementEntity
          - `id` string, MeteroidId, required
        - SubscriptionEntitlementEntity
          - `id` string, MeteroidId, required
        - QuoteEntitlementEntity
          - `id` string, MeteroidId, required
      - `name` string, nullable
    - `value` union, required
      - BooleanEffectiveEntitlementValue
        - `enabled` boolean, required
      - MeteredEffectiveEntitlementValue
        - `spec` MeteredEntitlementSpec, required
          - `enabled` boolean, required
          - `limit` string, decimal, nullable
          - `metric_id` string, MeteroidId, required
          - `overage_behavior` union, required — What happens past the limit.
            - BlockOverageBehavior — Deny access once usage reaches the limit. Meteroid does not enforce this — your integration must check and act.
              - …
            - AllowOverageBehavior — Keep serving usage past the limit; overage is billed or handled out-of-band.
          - `reset_period` union, required
            - BillingCycleResetPeriod — Resets each time your subscription renews — anchored to your billing cycle.
            - CalendarResetPeriod — Resets on calendar boundaries (e.g. the 1st of every month) — not tied to subscription start date.
              - …
            - FixedWindowResetPeriod — Resets at regular intervals — anchored to your subscription's exact activation time.
              - …
            - SlidingWindowResetPeriod — Always ends at now — e.g. 30 days means the last 30 days, old usage drops off automatically.
              - …
            - NeverResetPeriod — Never resets — counts all usage since the subscription was activated.
          - `warning_threshold_pct` integer, nullable
        - `usage` MeteredEntitlementUsage, required
          - `consumed` string, decimal, nullable
          - `remaining` string, decimal, nullable
          - `reset_at` string, date-time, nullable

## Other responses

- `401` — Unauthorized
- `404` — Subscription not found
- `429` — Too many requests

## Changes

- **2026-05-28** (v1) `ed86d893d43e` — 5 breaking, 4 info
  - added `#/components/schemas/BooleanEffectiveEntitlementValue, #/components/schemas/MeteredEffectiveEntitlementValue` to the `data/items/value` response property `oneOf` list for the response status `200`
  - removed the required property `data/items/created_at` from the response with the `200` status
  - removed the required property `data/items/feature_id` from the response with the `200` status
  - removed the required property `data/items/id` from the response with the `200` status
  - …5 more
- **2026-05-23** (v1) `ac42ddd7b4b4` — 5 breaking, 5 info
  - the response property `data/items/value/oneOf[subschema #2]/enabled` became optional for the status `200`
  - the response property `data/items/value/oneOf[subschema #2]/reset_period` became optional for the status `200`
  - removed the required property `data/items/feature` from the response with the `200` status
  - removed the required property `data/items/origin` from the response with the `200` status
  - …6 more
- **2026-05-18** (v1) `0cdc37620ffb` — 1 info
  - endpoint added
- **2025-07-09** (v1) `dece17f86f99` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/meteroid-oss/apis/meteroid/changes/api/v1/subscriptions/:subscription_id/entitlements/get.md)

---

[API](https://skmtc.dev/meteroid-oss/apis/meteroid.md) · [All operations](https://skmtc.dev/meteroid-oss/apis/meteroid/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meteroid-oss/meteroid/revisions/ed86d893d43e/schema)