> ## 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 Assinaturas

> Consulte todas as assinaturas com filtros e paginação

## Visão Geral

Este endpoint retorna uma lista paginada de todas as assinaturas. Você pode filtrar por status, cliente, produto e buscar por nome ou email do cliente.

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://garu.com.br/api/subscriptions?status=active&page=1&limit=20" \
    -H "Authorization: Bearer sk_test_sua_chave"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://garu.com.br/api/subscriptions?status=active&page=1&limit=20',
    {
      headers: {
        'Authorization': `Bearer ${process.env.GARU_API_KEY}`
      }
    }
  );

  const { data, count, totalCount, totalPages } = await response.json();

  data.forEach(sub => {
    console.log(`${sub.customer.name}: ${sub.status}`);
  });
  ```

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

  url = "https://garu.com.br/api/subscriptions"
  headers = {
      "Authorization": f"Bearer {os.environ['GARU_API_KEY']}"
  }
  params = {
      "status": "active",
      "page": 1,
      "limit": 20
  }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()

  for sub in result['data']:
      print(f"{sub['customer']['name']}: {sub['status']}")
  ```
</CodeGroup>

## Parâmetros de Query

<ParamField query="page" type="integer" default="1">
  Número da página para paginação.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Quantidade de itens por página.
</ParamField>

<ParamField query="status" type="string">
  Filtrar por status: `pending`, `active`, `pending_cancellation`, `canceled`, `failed`.
</ParamField>

<ParamField query="customerId" type="integer">
  Filtrar por ID do cliente.
</ParamField>

<ParamField query="productId" type="integer">
  Filtrar por ID do produto.
</ParamField>

<ParamField query="search" type="string">
  Buscar por nome ou email do cliente.
</ParamField>

## Resposta de Sucesso

<ResponseField name="data" type="array">
  Lista de assinaturas.
</ResponseField>

<ResponseField name="count" type="number">
  Total de assinaturas retornadas nesta página.
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total de assinaturas que correspondem aos filtros.
</ResponseField>

<ResponseField name="page" type="number">
  Página atual.
</ResponseField>

<ResponseField name="totalPages" type="number">
  Total de páginas disponíveis.
</ResponseField>

### Exemplo de Resposta (200 OK)

```json theme={null}
{
  "data": [
    {
      "id": 100,
      "uuid": "sub_xyz789",
      "customerId": 50,
      "subscriptionPriceId": 456,
      "status": "active",
      "currentPeriodStart": "2024-02-15T00:00:00.000Z",
      "currentPeriodEnd": "2024-03-15T00:00:00.000Z",
      "trialEndsAt": null,
      "cancelAt": null,
      "lastPaymentAt": "2024-02-15T10:00:00.000Z",
      "nextPaymentAt": "2024-03-15T10:00:00.000Z",
      "customer": {
        "id": 50,
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "subscriptionPrice": {
        "id": 456,
        "name": "Plano Mensal",
        "unitAmount": 49.90,
        "billingInterval": "monthly"
      }
    },
    {
      "id": 101,
      "uuid": "sub_abc123",
      "customerId": 51,
      "subscriptionPriceId": 457,
      "status": "active",
      "currentPeriodStart": "2024-02-10T00:00:00.000Z",
      "currentPeriodEnd": "2025-02-10T00:00:00.000Z",
      "trialEndsAt": null,
      "cancelAt": null,
      "lastPaymentAt": "2024-02-10T10:00:00.000Z",
      "nextPaymentAt": "2025-02-10T10:00:00.000Z",
      "customer": {
        "id": 51,
        "name": "Maria Santos",
        "email": "maria@email.com"
      },
      "subscriptionPrice": {
        "id": 457,
        "name": "Plano Anual",
        "unitAmount": 479.00,
        "billingInterval": "yearly"
      }
    }
  ],
  "count": 2,
  "totalCount": 50,
  "page": 1,
  "totalPages": 25
}
```

## Status de Assinatura

| Status                 | Descrição                                 |
| ---------------------- | ----------------------------------------- |
| `pending`              | Aguardando primeiro pagamento             |
| `active`               | Assinatura ativa e em dia                 |
| `pending_cancellation` | Cancelamento agendado para fim do período |
| `canceled`             | Assinatura encerrada                      |
| `failed`               | Pagamento falhou após todas as tentativas |

## Paginação

Para percorrer todas as assinaturas:

```javascript theme={null}
async function listarTodasAssinaturas(status = 'active') {
  const assinaturas = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://garu.com.br/api/subscriptions?status=${status}&page=${page}&limit=50`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.GARU_API_KEY}`
        }
      }
    );

    const result = await response.json();
    assinaturas.push(...result.data);
    totalPages = result.totalPages;
    page++;
  } while (page <= totalPages);

  return assinaturas;
}
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Detalhes da Assinatura" icon="magnifying-glass" href="/api-reference/assinaturas/detalhes">
    Consulte os detalhes completos de uma assinatura
  </Card>

  <Card title="Gerenciar Assinaturas" icon="gear" href="/api-reference/assinaturas/gerenciar">
    Cancelar, pausar e retomar assinaturas
  </Card>
</CardGroup>