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

# Listar Cobranças

> Liste as cobranças da sua conta com filtros de status, método, produto, período e cliente

## Visão Geral

Lista as cobranças da conta autenticada, da mais recente para a mais antiga por padrão. Útil para telas de conciliação e relatórios dentro do seu sistema.

<Note>
  A lista inclui **todas** as cobranças da conta, inclusive as de pedidos de produto físico — nessas, o campo `product` vem `null`, porque o pedido pode conter mais de um produto.
</Note>

## Headers

<ParamField header="Authorization" type="string" required>
  Sua chave de API (`Bearer sk_live_...`)
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Página desejada
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Itens por página, máximo 100
</ParamField>

<ParamField query="status" type="string">
  Filtra pelo status amigável: `pending`, `authorized`, `paid`, `failed`, `expired`, `canceled`, `refund_pending`, `refunded`, `chargeback`
</ParamField>

<ParamField query="paymentMethod" type="string">
  Filtra por método: `pix`, `boleto` ou `creditCard`
</ParamField>

<ParamField query="productId" type="string">
  Filtra pelo UUID do produto
</ParamField>

<ParamField query="createdAfter" type="string">
  Cobranças criadas a partir desta data (ISO-8601)
</ParamField>

<ParamField query="createdBefore" type="string">
  Cobranças criadas até esta data (ISO-8601)
</ParamField>

<ParamField query="search" type="string">
  Busca por nome, e-mail ou documento do cliente
</ParamField>

<ParamField query="sort" type="string" default="-createdAt">
  Ordenação: `createdAt`, `-createdAt`, `amount` ou `-amount`. O prefixo `-` indica ordem decrescente.
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://garu.com.br/api/v1/charges \
    -H "Authorization: Bearer sk_live_sua_chave_api" \
    -d status=paid \
    -d createdAfter=2026-07-01T00:00:00Z \
    -d limit=50
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    status: 'paid',
    createdAfter: '2026-07-01T00:00:00Z',
    limit: '50'
  });

  const response = await fetch(`https://garu.com.br/api/v1/charges?${params}`, {
    headers: { Authorization: `Bearer ${process.env.GARU_API_KEY}` }
  });

  const { data, totalCount } = await response.json();
  console.log(`${data.length} de ${totalCount} cobranças`);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://garu.com.br/api/v1/charges",
      headers={"Authorization": f"Bearer {os.environ['GARU_API_KEY']}"},
      params={
          "status": "paid",
          "createdAfter": "2026-07-01T00:00:00Z",
          "limit": 50,
      },
  )

  body = response.json()
  print(f"{len(body['data'])} de {body['totalCount']} cobranças")
  ```
</CodeGroup>

## Resposta de Sucesso (200 OK)

```json theme={null}
{
  "data": [
    {
      "uuid": "6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f",
      "status": "paid",
      "paymentMethod": "pix",
      "amount": 349.00,
      "chargedTotal": 349.00,
      "installments": 1,
      "product": {
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Curso de Marketing Digital"
      },
      "customer": {
        "name": "Maria Silva",
        "email": "maria@exemplo.com.br",
        "document": "***456789**"
      },
      "pix": { "code": "00020101021226840014br.gov.bcb.pix..." },
      "boleto": null,
      "card": null,
      "refund": null,
      "createdAt": "2026-07-22T14:03:11.000Z",
      "expiresAt": null
    }
  ],
  "count": 1,
  "totalCount": 137,
  "totalPages": 7
}
```

| Campo        | Significado                                 |
| ------------ | ------------------------------------------- |
| `count`      | Itens nesta página                          |
| `totalCount` | Total de cobranças que casam com os filtros |
| `totalPages` | Número de páginas com o `limit` informado   |

## Erros

| Código | Quando acontece                                              |
| ------ | ------------------------------------------------------------ |
| `400`  | `paymentMethod`, `sort` ou uma das datas em formato inválido |
| `401`  | Chave de API ausente ou inválida                             |