> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/v1/subscriptions/

> Retorna uma lista paginada de assinaturas da organização

Retorna todas as assinaturas da organização, com suporte a filtros por cliente, produto, status ativo e desconto.

## Autenticação

> [!NOTE]
>
> Requer um token de acesso válido (`CHARGEFY_ACCESS_TOKEN`) no header `Authorization`. Escopos necessários: `web:read`, `web:write` ou `subscriptions:read`.

## Parâmetros de Query

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `page` | `integer` | Não | Número da página (default: 1) |
| `limit` | `integer` | Não | Itens por página (default: 10) |
| `organization_id` | `string` ou `string[]` | Não | Filtrar por ID da organização |
| `customer_id` | `string` ou `string[]` | Não | Filtrar por ID do cliente |
| `product_id` | `string` ou `string[]` | Não | Filtrar por ID do produto |
| `discount_id` | `string` ou `string[]` | Não | Filtrar por ID do desconto |
| `external_customer_id` | `string` ou `string[]` | Não | Filtrar por ID externo do cliente |
| `status` | `string` ou `string[]` | Não | Filtrar por status exato da assinatura (repetível). Valores: `active`, `trialing`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`. Quando presente, o parâmetro `active` é ignorado |
| `active` | `boolean` | Não | Filtrar por status ativo (`true` ou `false`). Ignorado quando `status` é fornecido |
| `sorting` | `string[]` | Não | Ordenação. Valores: `started_at`, `-started_at`, `ended_at`, `-ended_at`, `status`, `-status`, `current_period_end`, `-current_period_end` |

## Campos da Resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `items` | `array` | Lista de assinaturas |
| `items[].id` | `string` | ID da assinatura |
| `items[].status` | `string` | Status atual da assinatura |
| `items[].customer_id` | `string` | ID do cliente |
| `items[].product_id` | `string` | ID do produto |
| `items[].current_period_start` | `datetime` | Início do período atual |
| `items[].current_period_end` | `datetime` | Fim do período atual |
| `items[].cancel_at_period_end` | `boolean` | Se será cancelada ao fim do período |
| `pagination` | `object` | Informações de paginação |
| `pagination.total_count` | `integer` | Total de registros |
| `pagination.max_page` | `integer` | Número máximo de páginas |

## Exemplo de Requisição

```bash cURL theme={null}
curl -X GET "https://api.chargefy.io/api/v1/subscriptions/?active=true&limit=20" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const subscriptions = await chargefy.subscriptions.list({
  active: true,
  limit: 20,
});
```

## Exemplo de Resposta

```json theme={null}
{
  "items": [
    {
      "id": "sub_1a2b3c4d",
      "status": "active",
      "customer_id": "cus_9x8y7z",
      "product_id": "prod_abc123",
      "product_price_id": "price_def456",
      "current_period_start": "2026-03-01T00:00:00Z",
      "current_period_end": "2026-04-01T00:00:00Z",
      "cancel_at_period_end": false,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 42,
    "max_page": 3
  }
}
```


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