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

# List Subscriptions

> Lista subscriptions.

Lista subscriptions em ordem decrescente de criação. Por padrão, subscriptions
canceladas não aparecem; envie `status=canceled` ou `status=all` para incluí-las.

<ParamField query="customer" type="string">
  Filtra pelo customer (`cus_*`).
</ParamField>

<ParamField query="default_payment_method" type="string">
  Filtra pelo payment method padrão (`pm_*`).
</ParamField>

<ParamField query="status" type="string">
  Filtra por status: `incomplete`, `incomplete_expired`, `trialing`, `active`,
  `past_due`, `canceled`, `unpaid`, `paused` ou `all`.
</ParamField>

<ParamField query="created_at[gte]" type="string">
  Filtra subscriptions criadas a partir de uma data ISO 8601.
</ParamField>

<ParamField query="limit" type="integer">
  Quantidade de itens, de `1` a `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor para a próxima página.
</ParamField>

<ParamField query="ending_before" type="string">
  Cursor para a página anterior.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X GET "https://api.chargefy.io/v1/subscriptions?customer=cus_123&limit=10" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

<ResponseExample>
  ```json Response 200 theme={}
  {
    "object": "list",
    "data": [
      {
        "id": "sub_123",
        "object": "subscription",
        "billing_cycle_anchor": "2026-05-19T18:00:00Z",
        "billing_mode": {
          "type": "classic"
        },
        "cancel_at": null,
        "cancel_at_period_end": false,
        "canceled_at": null,
        "cancellation_details": {
          "comment": null,
          "feedback": null,
          "reason": null
        },
        "collection_method": "charge_automatically",
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "current_period_end": "2026-06-19T18:00:00Z",
        "current_period_start": "2026-05-19T18:00:00Z",
        "customer": "cus_123",
        "days_until_due": null,
        "default_payment_method": "pm_123",
        "ended_at": null,
        "items": {
          "object": "list",
          "data": [
            {
              "id": "si_123",
              "object": "subscription_item",
              "amount_discount": 0,
              "amount_subtotal": 9990,
              "amount_tax": 0,
              "amount_total": 9990,
              "created_at": "2026-05-19T18:00:00Z",
              "currency": "brl",
              "metadata": {},
              "position": 0,
              "price": "price_123",
              "price_data": null,
              "product": "prod_123",
              "quantity": 1,
              "recurring": {
                "interval": "month",
                "interval_count": 1
              },
              "subscription": "sub_123",
              "unit_amount": 9990,
              "updated_at": null
            }
          ],
          "has_more": false,
          "url": "/v1/subscription-items?subscription=sub_123"
        },
        "latest_invoice": "in_123",
        "livemode": true,
        "metadata": {},
        "next_billing_at": "2026-06-19T18:00:00Z",
        "pause_collection": null,
        "payment_settings": {},
        "pending_setup_intent": null,
        "pending_update": null,
        "start_date": "2026-05-19T18:00:00Z",
        "status": "active",
        "trial_end": null,
        "trial_settings": {
          "end_behavior": {
            "missing_payment_method": "create_invoice"
          }
        },
        "trial_start": null,
        "updated_at": "2026-05-19T18:01:02Z"
      }
    ],
    "has_more": false,
    "url": "/v1/subscriptions"
  }
  ```
</ResponseExample>