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

# Listar subcontas

> Lista as subcontas da loja, das mais recentes para as mais antigas, com o saldo de cada uma.


Retorna as subcontas da sua loja, das mais recentes para as mais antigas, com o saldo de cada uma.

> [card]
>
> Requer a permissão `SUB_ACCOUNT:READ`.

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](https://docs.abacatepay.com/pages/reference/introduction.md#paginação-e-filtro-por-data).

Para achar a subconta de um vendedor, filtre por `taxId` (CPF ou CNPJ, com ou sem máscara) ou por `externalId`. Cada item segue o formato da [Referência](https://docs.abacatepay.com/pages/sub-accounts/reference.md#estrutura).


## OpenAPI

````yaml GET /sub-accounts/list
openapi: 3.1.0
info:
  title: API AbacatePay
  description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
  version: 1.0.0
servers:
  - url: https://api.abacatepay.com/v2
    description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
  /sub-accounts/list:
    get:
      summary: Listar subcontas
      description: >
        Lista as subcontas da loja, das mais recentes para as mais antigas, com
        o saldo de cada uma.
      parameters:
        - $ref: '#/components/parameters/QueryAfter'
        - $ref: '#/components/parameters/QueryBefore'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryStartDate'
        - $ref: '#/components/parameters/QueryEndDate'
        - name: taxId
          in: query
          description: Filtrar pelo CPF ou CNPJ do titular, com ou sem máscara.
          required: false
          schema:
            type: string
            example: '11144477735'
        - name: externalId
          in: query
          description: Filtrar pelo identificador no seu sistema.
          required: false
          schema:
            type: string
            example: vendedor-42
      responses:
        '200':
          description: Lista de subcontas.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubAccount'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
      security:
        - bearerAuth: []
components:
  parameters:
    QueryAfter:
      name: after
      in: query
      description: >-
        Cursor para buscar itens após este ponto (use o `publicId` retornado em
        `pagination.next`).
      required: false
      schema:
        type: string
    QueryBefore:
      name: before
      in: query
      description: >-
        Cursor para buscar itens antes deste ponto (use o `publicId` retornado
        em `pagination.before`).
      required: false
      schema:
        type: string
    QueryLimit:
      name: limit
      in: query
      description: Quantidade de itens por página (1-100).
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
        example: 100
    QueryStartDate:
      name: startDate
      in: query
      description: >
        Filtra registros criados a partir desta data (inclusive). Formato
        `YYYY-MM-DD`. O intervalo é interpretado no fuso horário
        `America/Sao_Paulo` (00:00 do dia inicial).
      required: false
      schema:
        type: string
        format: date
        example: '2026-01-01'
    QueryEndDate:
      name: endDate
      in: query
      description: >
        Filtra registros criados até esta data (inclusive). Formato
        `YYYY-MM-DD`. O intervalo é interpretado no fuso horário
        `America/Sao_Paulo` (23:59:59.999 do dia final).
      required: false
      schema:
        type: string
        format: date
        example: '2026-01-31'
  schemas:
    SubAccount:
      type: object
      description: Subconta de um vendedor, com o saldo atual.
      properties:
        id:
          type: string
          description: ID único da subconta.
          example: sacc_9f8Kq2LmX4vTzR7pWn3bYc1H
        name:
          type: string
          description: Nome do titular.
          example: João da Silva
        taxId:
          type: string
          description: CPF ou CNPJ do titular, só dígitos.
          example: '11144477735'
        externalId:
          type: string
          nullable: true
          description: Identificador no seu sistema.
          example: vendedor-42
        balance:
          type: object
          description: Saldo da subconta em centavos.
          properties:
            available:
              type: integer
              description: Disponível para saque.
              example: 7000
            blocked:
              type: integer
              description: Retido.
              example: 0
        devMode:
          type: boolean
          description: Indica se a subconta foi criada em ambiente de testes.
          example: false
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            loja: centro
        createdAt:
          type: string
          format: date-time
          example: '2026-10-26T14:22:10.381Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-10-26T14:22:10.381Z'
    Success:
      type: boolean
      description: Se a requisição obteve sucesso ou não.
      example: true
    PaginationCursor:
      type: object
      description: Informações de paginação baseada em cursor.
      required:
        - hasMore
        - next
        - before
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
          description: Indica se existe uma próxima página.
        next:
          type: string
          nullable: true
          description: Cursor da próxima página (usar em `after`). `null` na última página.
        before:
          type: string
          nullable: true
          description: >-
            Cursor da página anterior (usar em `before`). `null` na primeira
            página.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Todas as requisições devem incluir sua chave de API no header
        Authorization usando o formato `Bearer <abacatepay-api-key>`. Sem esse
        header a requisição será rejeitada.


        Saiba mais sobre como criar e usar chaves de API na [documentação de
        autenticação](/pages/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.