# Listar Assinaturas
`GET /v1/subscriptions`
**Área:** Assinaturas

**Scopes necessários:** `subscriptions/read`

Lista todas as assinaturas da conta com suporte a filtros por status, cliente, método de pagamento, produto e período.

Utilize o campo `lastKey` retornado na resposta para navegar entre as páginas.

Status possíveis: `PENDING`, `AWAITING_PAYMENT`, `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELED`, `INCOMPLETE`.

> Assinaturas com `interval: ONE_TIME` são excluídas automaticamente do resultado.

Case de uso:

_Como SaaS, quero listar todas as assinaturas ativas dos meus clientes para exibir no meu painel administrativo._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `lastKey` | **sim** | Cursor de paginação em base64 retornado na resposta anterior - optional |
| `startDate` | **sim** | Filtro por createdAt. ISO 8601 recomendado (ex: 2026-03-10T00:00:00.000Z). YYYY-MM-DD aceito - optional |
| `endDate` | **sim** | Filtro por createdAt. ISO 8601 com fim do dia (ex: 2026-03-10T23:59:59.999Z). YYYY-MM-DD pode excluir registros do mesmo dia com horário - optional |
| `status` | **sim** | Filtro por status (lista separada por vírgula): PENDING, AWAITING_PAYMENT, ACTIVE, TRIALING, PAST_DUE, PAUSED, CANCELED, INCOMPLETE - optional |
| `search` | **sim** | Busca por nome ou documento do cliente - optional |
| `document` | **sim** | Filtro por CPF ou CNPJ do cliente - optional |
| `paymentMethod` | **sim** | Filtro por método: CREDIT_CARD, PIX, BOLETO ou PIX_AUTOMATICO. Alias aceito: paymentType - optional |
| `priceId` | **sim** | Filtro por ID do preço - optional |
| `productId` | **sim** | Filtro por ID do produto - optional |
| `limit` | não | Quantidade de itens por página (default 15) - optional |

### Resposta 200 — 200

```json
{
  "items": [
    {
      "subscriptionId": "sub_xxx",
      "status": "ACTIVE",
      "interval": "MONTHLY",
      "billingDay": 15,
      "currentCycleNumber": 3,
      "currentCycleAmount": 99.9,
      "nextCycleChargeDate": "2024-02-15",
      "customer": {
        "customerId": "cus_xxx",
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "lastCharge": {
        "netAmount": 98.91,
        "status": "PAID"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "hasMore": true,
    "lastKey": "eyJ..."
  }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/get-listar-assinaturas
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json