> ## 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. # Get Entitlement > Retrieve a specific entitlement by ID. For metered entitlements, the response includes live balance, usage, and access status for the current billing period. ## OpenAPI ````yaml /openapi.json get /v1/entitlements/{entitlementId} 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/{entitlementId}: parameters: - name: entitlementId in: path required: true description: The unique identifier of the entitlement schema: type: string pattern: ^ent_[a-zA-Z0-9]+$ get: tags: - Entitlements summary: Get Entitlement description: >- Retrieve a specific entitlement by ID. For metered entitlements, the response includes live balance, usage, and access status for the current billing period. operationId: getEntitlement parameters: - name: entitlementId in: path required: true schema: type: string pattern: ^ent_[a-zA-Z0-9]+$ description: The unique identifier of the entitlement. - 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 entitlement. content: application/json: schema: $ref: '#/components/schemas/EntitlementDetail' examples: booleanEntitlement: summary: Boolean entitlement value: object: entitlement id: ent_a7b8c9d0e1f2g3h4 customerId: cus_x1y2z3a4b5c6d7e8 featureId: feat_p1q2r3s4t5u6v7w8 featureKey: sso_enabled featureType: boolean productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_m1n2o3p4q5r6s7t8 status: active hasAccess: true activeFrom: '2024-01-01T00:00:00Z' activeTo: null config: null metadata: {} staticEntitlement: summary: Static entitlement value: object: entitlement id: ent_b8c9d0e1f2g3h4i5 customerId: cus_x1y2z3a4b5c6d7e8 featureId: feat_q2r3s4t5u6v7w8x9 featureKey: storage_limit featureType: static productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_m1n2o3p4q5r6s7t8 status: active hasAccess: true activeFrom: '2024-01-01T00:00:00Z' activeTo: null config: limitGB: 500 allowedFileTypes: - pdf - doc - png metadata: {} meteredEntitlement: summary: Metered entitlement with balance value: object: entitlement id: ent_c9d0e1f2g3h4i5j6 customerId: cus_x1y2z3a4b5c6d7e8 featureId: feat_r3s4t5u6v7w8x9y0 featureKey: api_calls featureType: metered productId: prod_m5n6o7p8q9r0s1t2 subscriptionId: sub_m1n2o3p4q5r6s7t8 status: active hasAccess: true activeFrom: '2024-01-01T00:00:00Z' activeTo: null config: null isSoftLimit: false balance: 8340 usageInPeriod: 1660 overage: 0 currentPeriodStart: '2024-03-01T00:00:00Z' currentPeriodEnd: '2024-04-01T00:00:00Z' pricingUnitId: null metadata: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: EntitlementDetail: oneOf: - $ref: '#/components/schemas/BooleanEntitlementDetail' - $ref: '#/components/schemas/StaticEntitlementDetail' - $ref: '#/components/schemas/MeteredEntitlementDetail' discriminator: propertyName: featureType mapping: boolean: $ref: '#/components/schemas/BooleanEntitlementDetail' static: $ref: '#/components/schemas/StaticEntitlementDetail' metered: $ref: '#/components/schemas/MeteredEntitlementDetail' description: A specific entitlement. The response shape varies by featureType. BooleanEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - 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 entitlement so clients can read `config` without first switching on `featureType`. StaticEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - type: object required: - config properties: featureType: type: string enum: - static config: type: object additionalProperties: true description: Configuration values for this entitlement. MeteredEntitlementDetail: unevaluatedProperties: false allOf: - $ref: '#/components/schemas/EntitlementDetailBase' - 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 entitlement so clients can read `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 EntitlementDetailBase: type: object description: Common fields shared by all entitlement types. required: - object - id - customerId - featureId - featureKey - featureType - productId - subscriptionId - status - activeFrom - activeTo - hasAccess - metadata properties: object: type: string enum: - entitlement default: entitlement id: 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. CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer EntitlementFeatureType: type: string enum: - boolean - static - metered description: The type of feature. ProductId: type: string pattern: ^prod_[a-zA-Z0-9]+$ description: Unique identifier for a product 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' NotFound: description: Not Found - The requested resource could not be found 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 ````