> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # List subscriptions > Lists the subscriptions of your organization for the `live` or `test` mode of the API key used, with their subscription items included. The list is paginated with cursors: use the `Link` response header or the `starting_after` and `ending_before` query parameters to navigate between pages. **`v2`** ยท Base URL `https://api.fintoc.com/v2` ## OpenAPI ````yaml reference/fintoc-api-v2.json GET /subscriptions openapi: 3.1.0 info: title: fintoc-api-v2 version: v2026-02-01 servers: - url: https://api.fintoc.com/v2 security: [] paths: /subscriptions: get: tags: - Subscriptions summary: List subscriptions description: >- Lists the subscriptions of your organization for the `live` or `test` mode of the API key used, with their subscription items included. The list is paginated with cursors: use the `Link` response header or the `starting_after` and `ending_before` query parameters to navigate between pages. operationId: subscriptions-list parameters: - name: ending_before in: query required: false schema: type: string description: >- A cursor to use in pagination. `ending_before` is a subscription ID that defines your place in the list. For example, if you make a list request and receive 30 subscriptions, starting with `sub_bar`, your subsequent call can include `ending_before=sub_bar` to fetch the previous page of the list. - name: limit in: query required: false schema: type: integer example: 30 description: >- Maximum number of subscriptions to return per page. Ranges from `1` to `300`. Defaults to `30`. - name: starting_after in: query required: false schema: type: string description: >- A cursor to use in pagination. `starting_after` is a subscription ID that defines your place in the list. For example, if you make a list request and receive 30 subscriptions, ending with `sub_foo`, your subsequent call can include `starting_after=sub_foo` to fetch the next page of the list. responses: '200': description: >- List of subscriptions for the current mode, with their items included. content: application/json: examples: subscriptions_list: value: - id: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v object: subscription billing_cycle_anchor: '2026-06-01T15:00:00Z' collection_method: send_invoice created_at: '2026-06-01T15:00:00Z' customer: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu items: - id: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf object: subscription_item price: currency: CLP product: id: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz object: product created_at: '2026-06-01T15:00:00Z' description: Access to every premium feature. image_url: https://example.com/image.png metadata: {} mode: live name: Premium plan recurring: interval: month interval_count: 1 unit_amount: 10000 quantity: 1 metadata: order_id: '12345' mode: live payment_method: null status: active trial_end: null schema: type: array items: $ref: '#/components/schemas/subscription' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: subscription: type: object properties: id: type: string description: Unique identifier of the subscription. example: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v object: const: subscription description: Type of the object. Always `subscription`. billing_cycle_anchor: type: string format: date-time description: >- ISO 8601 timestamp that anchors the billing cycle. Fintoc sets this anchor to the subscription's creation time, or to `trial_end` when a trial applies. Fintoc measures every billing period from this anchor. example: '2026-06-01T15:00:00Z' collection_method: type: string enum: - charge_automatically - send_invoice description: >- Method Fintoc uses to collect the invoices the subscription generates. One of `charge_automatically` (Fintoc charges the saved payment method) or `send_invoice` (Fintoc sends the invoice for the customer to pay). Subscriptions created through the API always use `send_invoice`. example: send_invoice created_at: type: string format: date-time description: ISO 8601 timestamp of when the subscription was created. example: '2026-06-01T15:00:00Z' customer: type: string description: ID of the customer the subscription bills. example: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu items: type: array items: $ref: '#/components/schemas/subscription_item' description: Items the subscription bills for on every billing cycle. metadata: type: object description: Set of key-value pairs attached to the subscription. example: order_id: '12345' mode: type: string enum: - live - test description: >- Mode of the object. One of `live` or `test`. `test` subscriptions use fake data for integration testing and do not collect real money. example: live payment_method: type: - string - 'null' description: >- ID of the payment method charged when `collection_method` is `charge_automatically`. Always `null` for subscriptions created through the API. example: null status: type: string enum: - active - canceled - incomplete - trialing description: >- Current status of the subscription. One of `active`, `incomplete` (the first invoice payment has not yet succeeded), `trialing` (the trial period has not ended), or `canceled` (the subscription stopped generating invoices). example: active trial_end: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp at which the trial period ends, or `null` if the subscription has no trial. example: null required: - id - object - billing_cycle_anchor - collection_method - created_at - customer - items - metadata - mode - payment_method - status - trial_end error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message subscription_item: type: object properties: id: type: string description: Unique identifier of the subscription item. example: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf object: const: subscription_item description: Type of the object. Always `subscription_item`. price: type: object description: Price the item bills for on every billing cycle. properties: currency: type: string enum: - CLF - CLP - MXN description: >- Three-letter ISO 4217 currency code, returned in uppercase. One of `CLP`, `MXN` or `CLF`. example: CLP product: type: object description: Product the price belongs to. properties: id: type: string description: Unique identifier of the product. example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz object: const: product description: Type of the object. Always `product`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the product was created. example: '2026-06-01T15:00:00Z' description: type: - string - 'null' description: Free-text description of the product. example: Access to every premium feature. image_url: type: - string - 'null' description: HTTPS URL of an image of the product. example: https://example.com/image.png metadata: type: object description: Set of key-value pairs attached to the product. example: category: saas mode: type: string enum: - live - test description: >- Mode of the object. One of `live` or `test`. `test` products use fake data for integration testing. example: live name: type: string description: Name of the product. example: Premium plan required: - id - object - created_at - description - image_url - metadata - mode - name recurring: type: object description: Billing cadence of the price. properties: interval: type: string enum: - month - year description: >- Frequency at which the price bills. One of `month` or `year`. example: month interval_count: type: integer description: >- Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months. example: 1 required: - interval - interval_count unit_amount: type: integer description: >- Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN. example: 10000 required: - currency - product - recurring - unit_amount quantity: type: integer description: Number of units of the price the item bills for. example: 1 required: - id - object - price - quantity securitySchemes: api_key: type: apiKey name: Authorization in: header ````