> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check subscription entitlement

> Returns the current access decision for the subscription. The
`entitled` field is the access gate; `access_until` is informational
only and may be in the past or null while `entitled` is true (for
example while an automatic payment retry is in progress). Gate access
on `entitled`; do not use `access_until` as the access boundary.




## OpenAPI

````yaml /openapi/subscriptions.yaml get /subscriptions/{id}/entitlement
openapi: 3.0.3
info:
  title: Ionic Subscriptions API
  version: '2026-05-01'
  description: |
    Recurring billing subscriptions.

    A subscription (`sub_…`) attaches one or more priced items to a customer
    and bills them automatically each period. Each item references a recurring
    price (`price_…`); all items must share one currency and one billing
    cadence. A first invoice is issued at creation (unless the subscription
    opens with a trial); subsequent invoices are issued at each period boundary.

    All timestamps are Unix epoch seconds. Monetary amounts are integers in
    the currency's minor unit (for example cents for USD); amounts are
    determined by the item prices, not carried on the subscription itself.
    Identifiers are opaque, prefixed strings: subscriptions are `sub_…` and
    subscription items are `si_…`.

    Authentication uses a merchant secret key as a bearer token. Read
    endpoints require the `subscriptions:read` permission; write endpoints
    require `subscriptions:write`. The mode of the key (test or live) scopes
    which subscriptions it can see and mutate, reflected by each resource's
    `livemode` field. Mutating endpoints accept an optional `Idempotency-Key`
    header.

    Errors are returned as `{ "error": { "code": "...", "message": "..." } }`.
    A malformed path identifier returns 400. An operation rejected by the
    subscription's state machine (for example canceling an already-canceled
    subscription) returns 422. Concurrent updates are retried automatically;
    if they still conflict, the API returns 409 and the request can be retried.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: API base URL for your environment.
security:
  - secretKey: []
tags:
  - name: Subscriptions
    description: Create, manage, and inspect recurring billing subscriptions.
paths:
  /subscriptions/{id}/entitlement:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      tags:
        - Subscriptions
      summary: Check subscription entitlement
      description: |
        Returns the current access decision for the subscription. The
        `entitled` field is the access gate; `access_until` is informational
        only and may be in the past or null while `entitled` is true (for
        example while an automatic payment retry is in progress). Gate access
        on `entitled`; do not use `access_until` as the access boundary.
      operationId: subscriptions_check_entitlement
      responses:
        '200':
          description: The entitlement decision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - secretKey:
            - subscriptions:read
components:
  parameters:
    SubscriptionId:
      name: id
      in: path
      required: true
      description: The subscription id (`sub_…`).
      schema:
        type: string
  schemas:
    SubscriptionEntitlement:
      type: object
      description: The access decision for a subscription.
      required:
        - access_until
        - entitled
        - reason
      properties:
        entitled:
          type: boolean
          description: >-
            True when the subscriber has active access. Use this field as the
            access gate; do not use `access_until` as the boundary.
        reason:
          type: string
          description: A human-readable explanation of the entitlement decision.
        access_until:
          type: string
          nullable: true
          description: >-
            RFC 3339 timestamp of when access expires. Informational only — may
            be null or in the past while `entitled` is true (for example during
            dunning or when a renewal sweep is pending).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable error code.
            message:
              type: string
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_DATA
              message: invalid collection_method
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key lacks the required permission, or the merchant is not active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SubscriptionNotFound:
      description: No subscription with that id is visible to this key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SUBSCRIPTION_NOT_FOUND
              message: subscription not found
    RateLimited:
      description: Too many requests. Honour the `Retry-After` header before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: |
        The API could not return a successful response. For a mutating request,
        retrieve the resource before retrying because the operation may have
        completed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer <key>`.'

````