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

# List recurring invoices

> OAuth scope: `client_invoices.read`

Returns the organization's recurring invoices, most recently created first.




## OpenAPI

````yaml get /v2/recurring_invoices
openapi: 3.1.1
info:
  version: v2
  title: Qonto
servers:
  - url: https://thirdparty.qonto.com
    description: Production URL
  - url: https://thirdparty-sandbox.staging.qonto.co
    description: Sandbox URL
security:
  - OAuth:
      - organization.read
      - membership.read
      - membership.write
      - attachment.write
      - internal_transfer.write
      - payment.write
      - supplier_invoice.write
      - supplier_invoice.read
      - client_invoices.read
      - client_invoice.write
      - client.read
      - client.write
      - product.read
      - product.write
      - request_review.write
      - request_review.read
      - team.read
      - team.write
      - request_transfers.write
      - insurance_contract.read
      - insurance_contract.write
      - card.read
      - card.write
      - bank_account.write
      - beneficiary.trust
      - webhook
      - payment_link.write
      - payment_link.read
      - sepa_direct_debit.read
      - sepa_direct_debit.write
      - terminal.read
      - terminal.write
  - SecretKey: []
paths:
  /v2/recurring_invoices:
    get:
      tags:
        - Recurring Invoices
      summary: List recurring invoices
      description: >
        OAuth scope: `client_invoices.read`


        Returns the organization's recurring invoices, most recently created
        first.
      operationId: list_recurring_invoices
      parameters:
        - $ref: '#/components/parameters/X-Qonto-Staging-Token'
        - schema:
            type: string
          in: query
          name: filter[status]
          description: >-
            Filter by one or more statuses, comma-separated. One of:
            `scheduled`, `active`, `suspended`, `canceled`, `finished`. Invalid
            values return a `422`.
        - schema:
            type: string
          in: query
          name: filter[payment_method]
          description: >-
            Filter by one or more payment methods, comma-separated.
            `direct_debit` matches recurring invoices collected by SEPA direct
            debit. `credit_card`, `apple_pay`, `paypal`, `bank_transfer` and
            `ideal` match the methods in `payment_link`. A recurring invoice
            matches if it has any of the values. Unknown values match nothing.
        - schema:
            type: string
          in: query
          name: filter[client_id]
          description: >-
            Filter by one or more client ids, comma-separated. Ids that are not
            UUIDs return a `422`.
        - schema:
            type: string
            format: date
          in: query
          name: filter[next_invoice_date_from]
          description: >-
            Only return recurring invoices whose next invoice date is on or
            after this date, in `YYYY-MM-DD` format. A `suspended` recurring
            invoice can match even though its `next_invoice_date` is left out of
            the response.
        - schema:
            type: string
            format: date
          in: query
          name: filter[next_invoice_date_to]
          description: >-
            Only return recurring invoices whose next invoice date is on or
            before this date, in `YYYY-MM-DD` format.
        - schema:
            type: string
          in: query
          name: filter[invoice_id]
          description: >-
            Return the recurring invoices that generated one or more client
            invoices, as comma-separated client invoice ids. Ids that are not
            UUIDs return a `422`.
        - schema:
            type: integer
            default: 1
          in: query
          name: page
          description: >-
            Returned page (cf.
            [Pagination](https://docs.qonto.com/get-started/general/pagination#pagination)).
        - schema:
            type: integer
            default: 100
            maximum: 500
          in: query
          name: per_page
          description: >-
            Number of recurring invoices per page (cf.
            [Pagination](https://docs.qonto.com/get-started/general/pagination#pagination)).
      responses:
        '200':
          description: Returns a list of recurring invoices.
          content:
            application/json:
              schema:
                type: object
                required:
                  - recurring_invoices
                  - meta
                properties:
                  recurring_invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringInvoice'
                  meta:
                    type: object
                    required:
                      - current_page
                      - per_page
                      - total_pages
                      - total_count
                      - next_page
                      - previous_page
                    properties:
                      current_page:
                        type: integer
                        description: The current page.
                      per_page:
                        type: integer
                        description: The number of recurring invoices per page.
                      total_pages:
                        type: integer
                        description: The number of pages. `1` when there are no results.
                      total_count:
                        type: integer
                        description: The number of recurring invoices matching the filters.
                      next_page:
                        type:
                          - integer
                          - 'null'
                        description: The next page, or `null` on the last page.
                      previous_page:
                        type:
                          - integer
                          - 'null'
                        description: The previous page, or `null` on the first page.
        '400':
          $ref: '#/components/responses/400-Bad-request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '422':
          description: >-
            Returns an unprocessable entity error when a query parameter is
            invalid: `page` or `per_page` is not a number or is out of range, a
            filter value is invalid, a `filter[...]` key is unknown, or `page`
            is past the last page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/500-Internal-Server-Error'
      security:
        - OAuth:
            - client_invoices.read
        - SecretKey: []
components:
  parameters:
    X-Qonto-Staging-Token:
      name: X-Qonto-Staging-Token
      in: header
      description: >-
        Required only for Sandbox API requests; to get one, please sign up to
        the [Developer Portal](https://developers.qonto.com/).
      schema:
        type: string
  schemas:
    RecurringInvoice:
      type: object
      required:
        - id
        - status
        - client_id
        - start_date
        - frequency
        - payment_terms_days
        - invoice_status
        - purchase_order
        - terms_and_conditions
        - header
        - footer
        - currency
        - amount_due
        - bank_account
        - email_template
        - direct_debit_enabled
        - is_einvoice
        - items
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          example: 0198f2c1-8a3e-7c11-9f4d-2b6a7c8e9d01
        status:
          type: string
          enum:
            - scheduled
            - active
            - suspended
            - canceled
            - finished
          description: >-
            - `scheduled`: no invoice has been generated yet.

            - `active`: invoices are generated on each occurrence.

            - `suspended`: paused with `POST
            /v2/recurring_invoices/{id}/suspend`. No invoice is generated until
            it is reactivated.

            - `canceled`: stopped with `POST
            /v2/recurring_invoices/{id}/cancel`.

            - `finished`: `end_date` has passed. Set automatically.


            `canceled` and `finished` are final.
        client_id:
          type: string
          format: uuid
          description: The client this recurring invoice bills.
          example: 5c1f4e3a-9b7d-4a1e-8f2c-3d6b8a0e7f11
        client_name:
          type: string
          description: >-
            The client's name as of the last create or update of the recurring
            invoice. Absent when the client has no name.
          example: ACME SAS
        start_date:
          type: string
          format: date
          description: The date of the first occurrence.
          example: '2026-09-01'
        end_date:
          type: string
          format: date
          description: >-
            The date after which no further invoice is generated. Absent when
            the schedule has no end. Can only be set with `PUT
            /v2/recurring_invoices/{id}`.
        next_invoice_date:
          type: string
          format: date
          description: >-
            The next date on which an invoice is scheduled to be generated.
            Absent while `status` is `suspended`. It is not cleared when the
            recurring invoice is canceled or finished, so check `status` to know
            whether the schedule is still running.
          example: '2026-10-01'
        prev_invoice_date:
          type: string
          format: date
          description: >-
            The date the most recent invoice was generated. Only set on some
            older recurring invoices. Absent otherwise.
        frequency:
          type: object
          required:
            - value
            - recurrence
          properties:
            value:
              type: integer
              example: 1
            recurrence:
              type: string
              enum:
                - weekly
                - monthly
                - quarterly
                - yearly
              example: monthly
        payment_terms_days:
          type: integer
          description: Days between an occurrence's invoice date and its due date.
          example: 30
        invoice_status:
          type: string
          enum:
            - draft
            - unpaid
          description: The status each generated invoice is created as.
        purchase_order:
          type: string
          description: >-
            The purchase order reference printed on every generated invoice. An
            empty string when none is set. Can only be set with `PUT
            /v2/recurring_invoices/{id}`.
          example: PO-2026-042
        terms_and_conditions:
          type: string
          description: >-
            The terms and conditions printed on every generated invoice. An
            empty string when none are set. Can only be set with `PUT
            /v2/recurring_invoices/{id}`.
        header:
          type: string
          description: >-
            The header printed on every generated invoice. An empty string when
            none is set. Can only be set with `PUT /v2/recurring_invoices/{id}`.
        footer:
          type: string
          description: >-
            The footer printed on every generated invoice. An empty string when
            none is set. Can only be set with `PUT /v2/recurring_invoices/{id}`.
        currency:
          type: string
          description: ISO 4217 currency trigram.
          example: EUR
        amount_due:
          type: object
          description: The total amount each occurrence bills.
          required:
            - value
            - currency
          properties:
            value:
              type: string
              example: '120.00'
            currency:
              type: string
              example: EUR
        discount:
          type: object
          description: >-
            A discount covering the whole invoice, applied to every occurrence.
            Absent when none is set. Can only be set with `PUT
            /v2/recurring_invoices/{id}`.
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - percentage
                - absolute
            value:
              type: string
              description: >-
                The rate (for `percentage`, between `0` and `1`, with 4
                decimals) or amount (for `absolute`, with 2 decimals)
                discounted.
              example: '0.1000'
        bank_account:
          type: object
          description: The bank account generated invoices are paid to.
          properties:
            iban:
              type: string
              example: FR7630006000011234567890189
            bic:
              type: string
              example: QNTOFRP1XXX
        email_template:
          type: object
          nullable: true
          description: >-
            How each generated invoice is emailed to the client. `null` when no
            template is configured, which is only possible when `invoice_status`
            is `draft`.
          required:
            - send_to
            - copy_to_self
            - email_title
            - email_body
          properties:
            send_to:
              type: array
              items:
                type: string
                format: email
              example:
                - accounting@acme.com
            copy_to_self:
              type: boolean
            email_title:
              type: string
              example: Your invoice
            email_body:
              type: string
        payment_link:
          type: object
          description: >-
            The payment methods offered on each generated invoice. Absent when
            no payment method is enabled. Can only be set with `PUT
            /v2/recurring_invoices/{id}`.
          required:
            - methods
          properties:
            methods:
              type: array
              items:
                type: string
                enum:
                  - credit_card
                  - apple_pay
                  - paypal
                  - bank_transfer
                  - ideal
                example: credit_card
        payment_reporting:
          type: object
          description: Italian payment reporting details. Absent when none are set.
          properties:
            method:
              type: string
              example: MP01
            conditions:
              type: string
              example: TP01
        direct_debit_enabled:
          type: boolean
          description: >-
            Whether generated invoices are collected by SEPA direct debit. Set
            in the Qonto app only.
        is_einvoice:
          type: boolean
          description: >-
            Whether generated invoices are issued as electronic invoices. Set in
            the Qonto app only.
        items:
          type: array
          description: The line items billed on every occurrence.
          items:
            type: object
            required:
              - title
              - description
              - quantity
              - unit_price
              - vat_rate
            properties:
              title:
                type: string
                example: Consulting
              description:
                type: string
              quantity:
                type: string
                example: '1'
              unit:
                type: string
                example: hour
              unit_price:
                type: object
                required:
                  - value
                  - currency
                properties:
                  value:
                    type: string
                    example: '100.00'
                  currency:
                    type: string
                    example: EUR
              vat_rate:
                type: string
                example: '0.2'
              vat_exemption_code:
                type: string
              discount:
                type: object
                required:
                  - type
                  - value
                properties:
                  type:
                    type: string
                    enum:
                      - percentage
                      - absolute
                  value:
                    type: string
                    description: >-
                      The rate (for `percentage`, with 4 decimals) or amount
                      (for `absolute`, with 2 decimals) discounted.
                    example: '0.1000'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UnprocessableEntityError:
      type: object
      properties:
        status:
          type: string
          example: unprocessable entity
        code:
          type: string
          description: Error code.
          example: missing_key
        detail:
          type: string
          description: Human readable error that explains error `code`.
          example: property is missing
        message:
          type: string
          example: property id is missing
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property and the item in an array (if applicable) that
                causes the error.
              example: id
      required:
        - code
        - detail
    BadRequestResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BadRequestError'
      required:
        - errors
    UnauthorizedResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UnauthorizedError'
      required:
        - errors
    ForbiddenResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ForbiddenError'
      required:
        - errors
    BadRequestError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property in the request body that caused the error
                (optional).
            parameter:
              type: string
              description: The query parameter that caused the error (optional).
      required:
        - code
        - detail
      x-examples:
        Authorization field missing:
          code: bad_request
          detail: Authorization field missing
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Invalid credentials:
          code: unauthorized
          detail: Invalid credentials
    ForbiddenError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Insufficient permissions:
          code: forbidden
          detail: User does not have sufficient permissions for this action.
  responses:
    400-Bad-request:
      description: Returns a bad request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponseBody'
          examples:
            Authorization field missing:
              value:
                errors:
                  - code: bad_request
                    detail: Authorization field missing
    401-Unauthorized:
      description: Returns an unauthorized error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponseBody'
          examples:
            authorization_header_missing:
              value:
                errors:
                  - code: authorization_header_missing
                    detail: authorization header missing
            authorization_token_invalid:
              value:
                errors:
                  - code: authorization_token_invalid
                    detail: authorization token invalid
    403-Forbidden:
      description: Returns a forbidden error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponseBody'
          examples:
            Insufficient permissions:
              value:
                errors:
                  - code: forbidden
                    detail: User does not have sufficient permissions for this action.
    500-Internal-Server-Error:
      description: Returns an internal server error.
  securitySchemes:
    OAuth:
      type: oauth2
      description: >
        Bearer authorization header: `Bearer <token>`, where `<token>` is the
        access token received from the authorization server at the end of the
        [OAuth 2.0
        flow](/get-started/business-api/authentication/oauth/oauth-flow).
      flows:
        authorizationCode:
          refreshUrl: https://oauth.qonto.com/oauth2/token
          authorizationUrl: https://oauth.qonto.com/oauth2/auth
          scopes:
            attachment.read: Retrieve attachments
            attachment.write: Upload attachments and remove attachments from transactions
            bank_account.write: Create, update and close bank accounts
            beneficiary.trust: Trust SEPA beneficiaries
            card.read: Retrieve cards
            card.write: Create or update cards
            cash_flow_category.read: Retrieve cash flow categories
            cash_flow_category.write: >-
              Create, update and delete cash flow categories, and assign them to
              transactions
            client.read: Retrieve clients
            client.write: Create clients
            client_invoice.write: Create client invoices
            client_invoices.read: Retrieve client invoices and credit notes
            einvoicing.read: Retrieve e-invoicing settings
            embed_auth_link.write: Create Embed auth links
            insurance_contract.read: Retrieve insurance contracts
            insurance_contract.write: Create and update insurance contracts
            internal_transfer.write: >-
              Create internal transfers (between 2 Qonto accounts of the same
              organization)
            international_transfer.write: Create international transfers
            membership.read: Retrieve the authentified membership
            membership.write: Invite team members
            offline_access: Retrieve a refresh token
            organization.read: >-
              Retrieve organization, bank accounts, transactions, transfers,
              beneficiaries, labels, memberships, requests & statements
            payment.write: Create external transfers and untrust beneficiaries
            payment_link.read: >-
              Retrieve payment links, their payments, and the available payment
              methods
            payment_link.write: >-
              Connect to the payment links provider, create and deactivate
              payment links
            product.read: Retrieve products
            product.write: Create products
            request_cards.write: Create card requests
            request_review.write: Approve or decline requests
            request_transfers.write: Create transfer requests
            sepa_direct_debit.read: View SEPA Direct Debit payments
            sepa_direct_debit.write: Manage SEPA Direct Debit payments
            subscription.read: Retrieve the organization's current subscription plan
            supplier_invoice.read: Retrieve supplier invoices
            supplier_invoice.write: Create supplier invoices
            team.read: Retrieve teams
            team.write: Create teams
            terminal.read: View your payment terminals
            terminal.write: Configure your terminals and initiate payments
            user_organization.read: View the organizations the user has granted access to
            webhook: >-
              Receive a notification each time a particular event occurs in
              Qonto
          tokenUrl: https://oauth.qonto.com/oauth2/token
    SecretKey:
      type: apiKey
      description: cf. [API key](/get-started/business-api/authentication/api-key)
      name: Authorization
      in: header

````