> ## 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. # List subscriptions ## OpenAPI ````yaml /openapi/subscriptions.yaml get /subscriptions 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: get: tags: - Subscriptions summary: List subscriptions operationId: subscriptions_list parameters: - name: customer in: query description: Filter by customer id. schema: type: string - name: status in: query description: Filter by status. schema: type: string enum: - incomplete - trialing - active - past_due - unpaid - canceled - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: starting_after in: query description: >- Cursor: a subscription id (typically the previous response's `next_cursor`). Returns results strictly after it, newest first. Cannot be combined with `offset`. schema: type: string responses: '200': description: A paginated list of subscriptions. content: application/json: schema: $ref: '#/components/schemas/SubscriptionList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - subscriptions:read components: parameters: Limit: name: limit in: query description: Page size (default 20, max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 Offset: name: offset in: query description: Number of records to skip. schema: type: integer minimum: 0 default: 0 schemas: SubscriptionList: type: object required: - data - has_more - object - total_count properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/Subscription' has_more: type: boolean description: True when more records exist beyond this page. next_cursor: type: string description: >- Present when `has_more` is true: the last returned subscription's id. Pass it as `starting_after` on the next request. total_count: type: integer description: Total number of subscriptions matching the query. Subscription: type: object required: - billing_cycle_anchor - cancel_at_period_end - collection_method - created_at - current_period_end - current_period_start - customer - id - items - livemode - metadata - object - status - updated_at properties: id: type: string object: type: string enum: - subscription customer: type: string description: Customer id (`cus_…`). status: type: string enum: - incomplete - trialing - active - past_due - unpaid - canceled description: | `incomplete` — created; first invoice not yet paid. `trialing` — in free trial; no invoice yet (or a zero-total one). `active` — most recent invoice paid; in good standing. `past_due` — most recent invoice payment failed; in dunning. `unpaid` — dunning exhausted; service stopped. Terminal. `canceled` — terminated (immediately or at period end). Terminal. collection_method: type: string enum: - charge_automatically - send_invoice default_payment_method: type: string nullable: true description: >- The payment method used for automatic renewal charges (`pm_…`). Null when not set. items: type: array items: $ref: '#/components/schemas/SubscriptionItem' current_period_start: type: integer description: Unix epoch seconds. Start of the current billing period. current_period_end: type: integer description: Unix epoch seconds. End of the current billing period. billing_cycle_anchor: type: integer description: >- Unix epoch seconds. The reference point used to compute period boundaries. trial_start: type: integer nullable: true description: >- Unix epoch seconds. Start of the trial period. Null when the subscription was not created with a trial. trial_end: type: integer nullable: true description: Unix epoch seconds. End of the trial period. Null when no trial. cancel_at_period_end: type: boolean description: >- True when the subscription is scheduled to cancel at the end of the current period. canceled_at: type: integer nullable: true description: >- Unix epoch seconds. When the cancellation was requested. Null while not canceled. ended_at: type: integer nullable: true description: >- Unix epoch seconds. When the subscription terminated. Null while active. latest_invoice: type: string nullable: true description: >- Most recent invoice id (`inv_…`). Null before the first invoice is issued. metadata: type: object additionalProperties: type: string livemode: type: boolean created_at: type: integer description: Unix epoch seconds. updated_at: type: integer Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string SubscriptionItem: type: object required: - id - metadata - price - quantity properties: id: type: string description: Item id (`si_…`). price: type: string description: Recurring price id (`price_…`). quantity: type: integer metadata: type: object additionalProperties: 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' 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 `.' ````