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

# List Subscriptions

> Paginate your subscriptions, newest first, filtered by status or by customer.

Returns your subscriptions, newest first. Each item has the shape documented on [Get Subscription](/api-reference/recurring-payments/get-subscription).

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/v2/subscriptions?status=active&client_id=customer-9f3a&page=1&page_size=20' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>'
  ```
</RequestExample>

### Query Parameters

<ParamField query="status" type="string">
  Keep only one status: `incomplete`, `incomplete_expired`, `active`, `past_due`, `unpaid` or `canceled`.
</ParamField>

<ParamField query="client_id" type="string">
  Keep only the subscriptions created with this `client_id`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Items per page, maximum `100`.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "count": 42,
    "next": "https://developers.flouci.com/api/v2/subscriptions?client_id=customer-9f3a&page=2&page_size=20&status=active",
    "previous": null,
    "results": [
      {
        "subscription_id": "s7Qm3kLpTq2e9hZx0bYw1A",
        "status": "active",
        "payment_method": "flouci",
        "amount": 15000,
        "currency": "TND",
        "interval": "month",
        "interval_count": 1,
        "name": "Gold plan",
        "description": "",
        "client_id": "customer-9f3a",
        "developer_tracking_id": "sub-2026-000418",
        "is_test": false,
        "created_at": "2026-09-30T14:02:11+01:00",
        "activated_at": "2026-09-30T14:05:48+01:00",
        "current_period_start": "2026-09-30T14:05:48+01:00",
        "current_period_end": "2026-10-30T00:00:00+01:00",
        "next_charge_at": "2026-10-30T09:00:00+01:00",
        "cycles_completed": 1,
        "max_cycles": null,
        "cancel_at_period_end": false,
        "canceled_at": null,
        "cancellation_initiator": null,
        "cancellation_reason": null,
        "latest_charge": {
          "payment_id": "AgCKuBm0S5uLPghBo571MQ",
          "status": "SUCCESS",
          "type": "flouci",
          "billing_reason": "subscription_create",
          "attempt": 0,
          "period_start": "2026-09-30",
          "period_end": null,
          "amount": 15000,
          "fee": 150,
          "tva": 28,
          "created_at": "2026-09-30T14:02:11+01:00",
          "paid_at": "2026-09-30T14:05:48+01:00"
        }
      }
    ],
    "name": "developers",
    "code": 0,
    "version": "v2"
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="count" type="integer" required>
  Total number of subscriptions matching the filters.
</ResponseField>

<ResponseField name="next" type="string | null">
  URL of the next page, or `null` on the last page.
</ResponseField>

<ResponseField name="previous" type="string | null">
  URL of the previous page, or `null` on the first page.
</ResponseField>

<ResponseField name="results" type="array" required>
  Subscriptions, newest first. Same shape as [Get Subscription](/api-reference/recurring-payments/get-subscription#response-fields).
</ResponseField>

<Tip>
  To reconcile your own records, list with `status=past_due` once a day: those are the customers whose renewal failed and whose access you may want to restrict.
</Tip>


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