> ## 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. Results are paginated.

**`v1`** · Base URL `https://api.fintoc.com/v1`


## OpenAPI

````yaml reference/fintoc-api.json GET /subscriptions
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v1
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. Results are paginated.
      operationId: subscriptions-list
      parameters:
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2021-01-01T00:00:00.000Z'
          description: >-
            ISO 8601 datetime. Limits the results to subscriptions created at
            this datetime or after.
        - name: until
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2021-12-31T00:00:00.000Z'
          description: >-
            ISO 8601 datetime. Limits the results to subscriptions created at
            this datetime or before.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: Page number to retrieve. Starts at `1`.
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            example: 30
          description: >-
            Number of subscriptions per page. Defaults to `30`. The maximum is
            `300`.
      responses:
        '200':
          description: List of subscriptions for the current mode.
          headers:
            Link:
              schema:
                type: string
              description: Pagination links (`first`, `prev`, `next`, and `last`).
            X-Total-Count:
              schema:
                type: integer
              description: Total number of subscriptions across all pages.
          content:
            application/json:
              examples:
                subscriptions_list:
                  value:
                    - id: sub_m7N9rAWJS9dWDKEe
                      object: subscription
                      account:
                        id: acc_nMNejK7BT8oGbvO4
                        object: account
                        balance: null
                        currency: CLP
                        holder_id: '111111111'
                        holder_name: Jon Snow
                        institution:
                          id: cl_banco_estado
                          country: cl
                          name: Banco Estado
                        name: Cuenta Corriente
                        number: '9530516286'
                        official_name: Cuenta Corriente Moneda Local
                        type: checking_account
                      created_at: '2023-03-08T15:24:11Z'
                      mode: live
                      reference_id: ABC12345
                      status: active
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/subscriptions_subscription'
        '400':
          description: >-
            Invalid request: `since` or `until` is not a valid ISO 8601
            datetime.
          content:
            application/json:
              examples:
                invalid_date:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_date
                      param: since
                      message: >-
                        Invalid date: 13/01/2024. You need to provide a date in
                        ISO 8601 format (YYYY-MM-DD)
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '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:
    subscriptions_subscription:
      type: object
      description: >-
        Represents a payer's authorization to charge a bank account. Fintoc
        creates a `Subscription` when a `SubscriptionIntent` succeeds, and an
        `active` subscription accepts charges.
      properties:
        id:
          type: string
          description: Unique identifier of the subscription.
          example: sub_m7N9rAWJS9dWDKEe
        object:
          const: subscription
          description: Type of the object. Always `subscription`.
        account:
          $ref: '#/components/schemas/subscriptions_account'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp, in UTC, of when the subscription was created.
          example: '2023-03-08T15:24:11Z'
        mode:
          $ref: '#/components/schemas/mode'
        reference_id:
          type: string
          description: >-
            Identifier the payer's bank uses to display the subscription on the
            bank's portal. Defaults to the account holder's ID when not provided
            on creation.
          example: ABC12345
        status:
          type: string
          enum:
            - pending
            - active
            - canceled
          description: >-
            Status of the subscription. One of `pending` (the bank has not
            confirmed the subscription yet), `active` (the subscription accepts
            charges), or `canceled` (the subscription no longer accepts
            charges).
          example: active
      required:
        - id
        - object
        - account
        - created_at
        - mode
        - reference_id
        - status
    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
    subscriptions_account:
      type: object
      description: Represents the bank account a payer authorized for a subscription.
      properties:
        id:
          type: string
          description: Unique identifier of the account.
          example: acc_nMNejK7BT8oGbvO4
        object:
          const: account
          description: Type of the object. Always `account`.
        balance:
          description: >-
            Balance of the account. Always `null` in API responses; only present
            in webhook event payloads.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/balance'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Three-letter ISO 4217 currency code of the account.
          example: CLP
        holder_id:
          type: string
          description: >-
            Fiscal identifier of the account holder, without dots or dashes. For
            Chilean accounts, the Chilean tax ID (RUT).
          example: '111111111'
        holder_name:
          type: string
          description: Name of the account holder, as registered at the bank.
          example: Jon Snow
        institution:
          $ref: '#/components/schemas/institution'
        name:
          type: string
          description: Display name of the account.
          example: Cuenta Corriente
        number:
          type: string
          description: Bank account number.
          example: '9530516286'
        official_name:
          type: string
          description: Official product name the bank gives to the account.
          example: Cuenta Corriente Moneda Local
        type:
          $ref: '#/components/schemas/account_type'
      required:
        - id
        - object
        - balance
        - currency
        - holder_id
        - holder_name
        - institution
        - name
        - number
        - official_name
        - type
    mode:
      type: string
      enum:
        - test
        - live
      description: >-
        Mode of the object. `live` objects use real institution data, `test`
        objects use fake data for integration testing.
      example: live
    balance:
      type: object
      description: >-
        Balance of the account, as reported by the institution. All amounts are
        in the smallest unit of the account's currency (CLP has no decimals, so
        amounts are in pesos).
      properties:
        available:
          type: integer
          description: Amount available to spend, including overdraft lines if any.
          example: 500000
        current:
          type: integer
          description: >-
            Amount of money owned by the account holder, without overdraft
            lines.
          example: 500000
        limit:
          type: integer
          description: Maximum amount available to spend, including credit lines.
          example: 500000
      required:
        - available
        - current
        - limit
    institution:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the institution.
          example: cl_banco_de_chile
        country:
          type: string
          description: ISO 3166-1 alpha-2 code of the country of the institution.
          example: cl
        name:
          type: string
          description: Name of the institution.
          example: Banco de Chile
      required:
        - id
        - country
        - name
    account_type:
      type: string
      enum:
        - checking_account
        - savings_account
        - sight_account
        - line_of_credit
        - credit_card
      description: Type of the account. Fintoc exposes RUT accounts as `sight_account`.
      example: checking_account
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````