> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # List Entitlements > Retrieve all entitlements for a customer, optionally filtered by feature or product. List items identify the entitlement with `entitlementId` (the original list contract). The get-by-id endpoint (`GET /v1/entitlements/{entitlementId}`) returns the same object but with a top-level `id` and `object: "entitlement"` instead — so use `item.entitlementId`, not `item.id`, when chaining a list result into a get-by-id call. For metered entitlements, each item carries live balance/usage fields, which the API resolves with one grant-engine balance lookup per metered item (bounded concurrency, up to `limit` items per page). ## OpenAPI ````yaml /openapi.json get /v1/entitlements openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v1/entitlements: get: tags: - Entitlements summary: List Entitlements description: >- Retrieve all entitlements for a customer, optionally filtered by feature or product. List items identify the entitlement with `entitlementId` (the original list contract). The get-by-id endpoint (`GET /v1/entitlements/{entitlementId}`) returns the same object but with a top-level `id` and `object: "entitlement"` instead — so use `item.entitlementId`, not `item.id`, when chaining a list result into a get-by-id call. For metered entitlements, each item carries live balance/usage fields, which the API resolves with one grant-engine balance lookup per metered item (bounded concurrency, up to `limit` items per page). operationId: listEntitlements parameters: - name: customerId in: query required: false schema: $ref: '#/components/schemas/CustomerId' description: >- The Paygentic customer id to retrieve entitlements for. Supply exactly one of `customerId` or `externalCustomerId`. When combined with `merchantId`, the customer must belong to that merchant or the request resolves to not found. example: cus_q3r4s5t6u7v8w9x0 - name: externalCustomerId in: query required: false schema: type: string minLength: 1 maxLength: 255 description: >- The merchant's own external customer reference (`Customer.externalId`, exact match), used to retrieve entitlements without first resolving it to a `cus_` id. Matches the `externalId` filter on `GET /v1/customers` (plain string, exact match — no pattern constraint, so any stored `externalId` is addressable). Supply exactly one of `customerId` or `externalCustomerId`. `externalId` is unique only within a merchant, so an effective merchant scope is required: either pass `merchantId`, or authenticate with a single-merchant API key. With no resolvable merchant scope the request is rejected. example: ext-customer-123 - name: merchantId in: query required: false schema: $ref: '#/components/schemas/OrganizationId' description: >- Optional merchant scope. With `externalCustomerId` it selects the merchant the external id is resolved within (required for the platform key, which has no single merchant). With `customerId` it acts as a tenant guard — the resolved customer must belong to this merchant, otherwise the request resolves to not found. A passed `merchantId` is only a filter and never grants access the caller does not already hold; authorization is always evaluated against the resolved customer's merchant. example: org_a1b2c3d4e5f6g7h8 - name: featureKey in: query required: false schema: type: string description: >- Filter results to a specific feature by its key. When specified, `productId` is also required. Use this to check access to a single feature. - name: productId in: query required: false schema: $ref: '#/components/schemas/ProductId' description: >- Filter results to entitlements for a specific product. Required when `featureKey` is specified since feature keys are scoped to products. - name: subscriptionId in: query required: false schema: $ref: '#/components/schemas/SubscriptionId' description: Filter results to entitlements for a specific subscription. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: >- Maximum number of entitlements to return per page. Use with `offset` for pagination. - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: >- Number of entitlements to skip. Use with `limit` for pagination through large result sets. - name: at in: query required: false schema: type: string format: date-time description: >- Evaluate balance and access at this point in time (RFC 3339 datetime with any UTC offset, e.g. 2024-01-15T10:30:00Z or 2024-01-15T15:30:00+05:30). Defaults to current time. responses: '200': description: Successfully retrieved the list of entitlements for the customer. content: application/json: schema: type: object required: - object - data - pagination properties: object: type: string enum: - list default: list data: type: array items: $ref: '#/components/schemas/EntitlementListItem' description: >- Array of entitlement list items. The shape of each item varies by featureType. pagination: $ref: '#/components/schemas/OffsetPagination' examples: multipleEntitlements: summary: Multiple entitlements with different feature types description: >- A customer with a Pro plan that includes seat limits (static) and SSO access (boolean). value: object: list data: - entitlementId: ent_a7b8c9d0e1f2g3h4 customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_max_users featureKey: max_users featureType: static productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_pro_plan status: active activeFrom: '2024-01-01T00:00:00Z' activeTo: '2025-01-01T00:00:00Z' hasAccess: true metadata: {} config: limit: 25 - entitlementId: ent_b8c9d0e1f2g3h4i5 customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_sso_enabled featureKey: sso_enabled featureType: boolean productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_pro_plan status: active activeFrom: '2024-01-01T00:00:00Z' activeTo: null hasAccess: true metadata: {} config: null pagination: limit: 10 offset: 0 total: 2 staticFeatureWithConfig: summary: Static feature with configuration description: >- An entitlement for a feature that includes configuration values the customer is entitled to. value: object: list data: - entitlementId: ent_d0e1f2g3h4i5j6k7 customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_storage_quota featureKey: storage_quota featureType: static productId: prod_storage123456 subscriptionId: sub_storage_plan status: active activeFrom: '2024-03-15T00:00:00Z' activeTo: null hasAccess: true metadata: {} config: limitGB: 500 allowedFileTypes: - pdf - doc - xlsx - png - jpg pagination: limit: 10 offset: 0 total: 1 expiredEntitlement: summary: Entitlement that is no longer active description: >- A canceled entitlement where hasAccess is false. This can happen when a subscription is canceled or expires. value: object: list data: - entitlementId: ent_e1f2g3h4i5j6k7l8 customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_premium_support featureKey: premium_support featureType: boolean productId: prod_support789012 subscriptionId: null status: expired activeFrom: '2023-01-01T00:00:00Z' activeTo: '2024-01-01T00:00:00Z' hasAccess: false metadata: {} config: null pagination: limit: 10 offset: 0 total: 1 meteredEntitlement: summary: Metered entitlement with cap and live usage description: >- A usage-based feature with a hard cap (`isSoftLimit: false`) and live balance, usage, and period bounds from the grant engine. value: object: list data: - entitlementId: ent_c9d0e1f2g3h4i5j6 customerId: cus_q3r4s5t6u7v8w9x0 featureId: feat_api_calls featureKey: api_calls featureType: metered productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_pro_plan status: active activeFrom: '2024-03-01T00:00:00Z' activeTo: null hasAccess: true metadata: {} config: null isSoftLimit: false balance: 8340 usageInPeriod: 1660 overage: 0 currentPeriodStart: '2024-03-01T00:00:00Z' currentPeriodEnd: '2024-04-01T00:00:00Z' pricingUnitId: null pagination: limit: 10 offset: 0 total: 1 emptyResult: summary: No entitlements found description: >- Response when a customer has no entitlements, or no entitlements match the filter criteria. value: object: list data: [] pagination: limit: 10 offset: 0 total: 0 '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization ProductId: type: string pattern: ^prod_[a-zA-Z0-9]+$ description: Unique identifier for a product SubscriptionId: type: string pattern: ^sub_[a-zA-Z0-9]+$ description: Unique identifier for a subscription EntitlementListItem: oneOf: - $ref: '#/components/schemas/BooleanEntitlementListItem' - $ref: '#/components/schemas/StaticEntitlementListItem' - $ref: '#/components/schemas/MeteredEntitlementListItem' discriminator: propertyName: featureType mapping: boolean: $ref: '#/components/schemas/BooleanEntitlementListItem' static: $ref: '#/components/schemas/StaticEntitlementListItem' metered: $ref: '#/components/schemas/MeteredEntitlementListItem' description: >- An entitlement as returned by the list endpoint. The shape varies by featureType. Uses `entitlementId` (not `id`) for backwards compatibility with the original list contract. OffsetPagination: type: object description: Offset-based pagination response. properties: limit: type: integer description: Requested page size. offset: type: integer description: Number of items skipped. total: type: integer description: Total number of items available. required: - limit - offset - total BooleanEntitlementListItem: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementListItemBase' - type: object required: - config properties: featureType: type: string enum: - boolean config: type: object nullable: true additionalProperties: true description: >- Always `null` for boolean entitlements. Surfaced on every list item so clients can read `item.config` without first switching on `featureType`. StaticEntitlementListItem: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementListItemBase' - type: object required: - config properties: featureType: type: string enum: - static config: type: object additionalProperties: true description: Configuration values for this entitlement. MeteredEntitlementListItem: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementListItemBase' - type: object required: - balance - usageInPeriod - overage - isSoftLimit - config - currentPeriodStart - currentPeriodEnd - pricingUnitId properties: featureType: type: string enum: - metered config: type: object nullable: true additionalProperties: true description: >- Always `null` for metered entitlements. Surfaced on every list item so clients can read `item.config` without first switching on `featureType`. isSoftLimit: type: boolean description: >- When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate. balance: type: number description: >- Remaining balance for the current period. When `pricingUnitId` is set, this is expressed in that pricing unit's credits (a balance shared across every feature drawing the same unit); otherwise it is in the feature's native metered units. usageInPeriod: type: number description: >- Total usage consumed in the current billing period, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). When `pricingUnitId` is set, this is the shared-pool aggregate across every feature drawing the same unit, not usage specific to this feature. overage: type: number description: >- Amount of usage exceeding the balance, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). pricingUnitId: type: string nullable: true pattern: ^pu_[a-zA-Z0-9]+$ description: >- The pricing unit this feature is denominated in when it draws a credit pool. When set, `balance`/`usageInPeriod`/`overage` are in that unit's credits and reflect a balance shared across all features on the same unit. `null` for currency-denominated features (native metered units). currentPeriodStart: type: string format: date-time nullable: true description: >- Start of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation "dark window", when the query time is earlier than `activeFrom`) this instead describes the pre-activation `[subscription start, activation)` window and may be `null` when there is no associated subscription. currentPeriodEnd: type: string format: date-time nullable: true description: >- End of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation "dark window", when the query time is earlier than `activeFrom`) this instead holds `activeFrom` — the end of the pre-activation `[subscription start, activation)` window. Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format EntitlementListItemBase: type: object description: >- Common fields shared by all entitlement list items. List items use `entitlementId` (not `id`) to preserve the original public field name on `/v1/entitlements`. The get-by-id endpoint returns the same object with a top-level `id` and `object: "entitlement"` instead. required: - entitlementId - customerId - featureId - featureKey - featureType - productId - subscriptionId - status - activeFrom - activeTo - hasAccess - metadata properties: entitlementId: type: string pattern: ^ent_[a-zA-Z0-9]+$ description: Unique identifier for the entitlement. customerId: $ref: '#/components/schemas/CustomerId' featureId: type: string pattern: ^feat_[a-zA-Z0-9]+$ description: The feature this entitlement grants access to. featureKey: type: string description: The unique key identifying the feature. featureType: $ref: '#/components/schemas/EntitlementFeatureType' productId: $ref: '#/components/schemas/ProductId' subscriptionId: type: string nullable: true description: The subscription this entitlement is associated with, if any. status: $ref: '#/components/schemas/EntitlementStatus' activeFrom: type: string format: date-time description: When the entitlement becomes active. activeTo: type: string format: date-time nullable: true description: When the entitlement expires. Null means no expiration. hasAccess: type: boolean description: >- Whether the customer currently has active access to this entitlement. metadata: type: object additionalProperties: type: string description: Additional metadata for the entitlement. EntitlementFeatureType: type: string enum: - boolean - static - metered description: The type of feature. EntitlementStatus: type: string enum: - active - canceled - expired description: Current status of the entitlement. responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````