> ## 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 subscription intents

> Lists the subscription intents of your organization for the `live` or `test` mode of the API key used. Results are paginated. `widget_token` is always `null` outside creation.

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


## OpenAPI

````yaml reference/fintoc-api.json GET /subscription_intents
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v1
security: []
paths:
  /subscription_intents:
    get:
      tags:
        - Subscription intents
      summary: List subscription intents
      description: >-
        Lists the subscription intents of your organization for the `live` or
        `test` mode of the API key used. Results are paginated. `widget_token`
        is always `null` outside creation.
      operationId: subscription-intents-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 subscription intents
            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 subscription intents
            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 subscription intents per page. Defaults to `30`. The
            maximum is `300`.
      responses:
        '200':
          description: List of subscription intents 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 subscription intents across all pages.
          content:
            application/json:
              examples:
                subscription_intents_list:
                  value:
                    - id: si_mceqLoFwfBVHi3q4
                      object: subscription_intent
                      business_profile: null
                      created_at: '2023-03-08T15:24:11Z'
                      customer_email: payer@example.com
                      mode: live
                      public_error: null
                      reference_id: ABC12345
                      status: created
                      subscription: null
                      widget_token: null
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/subscriptions_subscription_intent'
        '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_intent:
      type: object
      description: >-
        Represents the flow a payer goes through to authorize a subscription at
        their bank. A successful subscription intent produces a `Subscription`.
      properties:
        id:
          type: string
          description: Unique identifier of the subscription intent.
          example: si_mceqLoFwfBVHi3q4
        object:
          const: subscription_intent
          description: Type of the object. Always `subscription_intent`.
        business_profile:
          description: >-
            Information shown to the payer in the widget. `null` when not
            provided on creation.
          anyOf:
            - type: 'null'
            - type: object
              properties:
                name:
                  type: string
                  description: Name displayed to the payer as the subscription's recipient.
                  example: Hooli
              required:
                - name
        created_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp, in UTC, of when the subscription intent was
            created.
          example: '2023-03-08T15:24:11Z'
        customer_email:
          type:
            - string
            - 'null'
          description: >-
            Email address of the payer. Fintoc sends the subscription receipt to
            this address when the subscription intent succeeds.
          example: payer@example.com
        mode:
          $ref: '#/components/schemas/mode'
        public_error:
          type:
            - string
            - 'null'
          enum:
            - null
            - login_invalid_credentials
            - login_credentials_locked
            - authorization_timeout
            - mfa_authorization_timeout
            - mfa_unavailable
            - bank_connection_error
            - bank_not_available
            - password_change_required
            - request_timeout
            - subscription_intent_expired
            - account_type_not_permitted
            - internal_error
            - user_left
          description: >-
            Error code describing why the subscription intent did not succeed.
            `null` unless `status` is `failed` or `rejected`.
          example: login_invalid_credentials
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            Identifier the payer's bank uses to display the subscription on the
            bank's portal. `null` when not provided on creation.
          example: ABC12345
        status:
          type: string
          enum:
            - created
            - in_progress
            - succeeded
            - failed
            - rejected
          description: >-
            Status of the subscription intent. One of `created` (waiting for the
            payer to start the authorization), `in_progress` (the payer is
            authorizing the subscription at their bank), `succeeded` (the payer
            authorized the subscription), `failed` (the authorization failed or
            expired), or `rejected` (the payer's bank rejected the
            subscription).
          example: succeeded
        subscription:
          description: >-
            `Subscription` created when the subscription intent succeeds. `null`
            in every other status.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/subscriptions_subscription'
        widget_token:
          type:
            - string
            - 'null'
          description: >-
            Token used to open the widget so the payer can authorize the
            subscription. Only returned when the subscription intent is created;
            `null` in every other response.
          example: si_mceqLoFwfBVHi3q4_sec_a8Mw9bnHzgVRCMTSDgrJpvkN
      required:
        - id
        - object
        - business_profile
        - created_at
        - customer_email
        - mode
        - public_error
        - reference_id
        - status
        - subscription
        - widget_token
    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
    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
    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
    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
    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

````