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

# Listar clientes

> Lista os compradores da loja, um por e-mail, com o que cada um já comprou. É a mesma base da página de clientes do painel.
<Note>Os totais desta listagem são recalculados em segundo plano, então uma compra dos últimos minutos pode ainda não estar somada aqui. Para o número exato de um comprador, use [Obter cliente](/api-reference/clientes/obter-cliente), que agrega na hora.</Note>
O `total_spent` desta rota é líquido, já sem a taxa do gateway, e conta todo pedido que saiu de pendente, inclusive reembolsado. É o número certo para "quanto este cliente rendeu", e o número errado para "quanto ele pagou".



## OpenAPI

````yaml /openapi/customers.yaml get /app/customer
openapi: 3.1.0
info:
  title: CentralCart API
  version: 1.0.0
  description: >-
    Consultas sobre os compradores da loja. Os endpoints aqui usam o escopo
    `customers:read` da chave de API.
servers:
  - url: https://api.centralcart.io/v1
    description: Produção
security:
  - bearerAuth: []
paths:
  /app/customer:
    get:
      tags:
        - Clientes
      summary: Listar clientes
      description: >-
        Lista os compradores da loja, um por e-mail, com o que cada um já
        comprou. É a mesma base da página de clientes do painel.

        <Note>Os totais desta listagem são recalculados em segundo plano, então
        uma compra dos últimos minutos pode ainda não estar somada aqui. Para o
        número exato de um comprador, use [Obter
        cliente](/api-reference/clientes/obter-cliente), que agrega na
        hora.</Note>

        O `total_spent` desta rota é líquido, já sem a taxa do gateway, e conta
        todo pedido que saiu de pendente, inclusive reembolsado. É o número
        certo para "quanto este cliente rendeu", e o número errado para "quanto
        ele pagou".
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          required: false
          description: 'Página da listagem (padrão: 1)'
          schema:
            type: number
        - name: limit
          in: query
          required: false
          description: 'Clientes por página, até 50 (padrão: 15)'
          schema:
            type: number
        - name: search
          in: query
          required: false
          description: >-
            Busca por nome ou e-mail. Com `@` o e-mail precisa bater inteiro;
            sem `@` procura o trecho no nome e no começo do e-mail.
          schema:
            type: string
        - name: email
          in: query
          required: false
          description: Filtra por um e-mail exato
          schema:
            type: string
        - name: order_by
          in: query
          required: false
          description: >-
            Ordenação no formato `coluna:asc|desc`. Colunas aceitas:
            `last_order_date`, `first_order_date`, `total_spent` e
            `orders_count`. Padrão: `last_order_date:desc`
          schema:
            type: string
      responses:
        '200':
          description: Clientes da loja
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  meta:
                    type: object
              example:
                data:
                  - name: Oliver Souza
                    email: oliver@exemplo.com
                    client_identifier: OliverMC
                    orders_count: 4
                    total_spent: 178.4
                    first_order_at: '2026-02-11T14:02:00.000-03:00'
                    last_order_at: '2026-08-19T09:31:00.000-03:00'
                    is_banned: false
                meta:
                  total: 1
                  per_page: 15
                  current_page: 1
                  last_page: 1
        '400':
          description: Coluna de ordenação inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                errors:
                  - message: >-
                      Ordenação inválida. Use uma destas colunas:
                      last_order_date, first_order_date, total_spent,
                      orders_count.
components:
  schemas:
    Customer:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        client_identifier:
          type: string
          nullable: true
          description: Identificador do último pedido, como o nick em lojas de Minecraft
        orders_count:
          type: number
          description: Pedidos que saíram de pendente, inclusive reembolsados
        total_spent:
          type: number
          description: Soma líquida, já sem a taxa do gateway
        first_order_at:
          type: string
          nullable: true
        last_order_at:
          type: string
          nullable: true
        is_banned:
          type: boolean
          description: Se o e-mail está banido da loja
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              ref:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token de API gerado no painel da CentralCart.

````