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

# Get Subscription

> Read the current state of a subscription, its billing period, its next charge and its latest charge.

Returns one subscription. Poll it after redirecting a customer to the checkout, or read it whenever you need the current period — but rely on [webhooks](https://docs.flouci.com/api-reference/recurring-payments/webhooks) for renewals rather than polling.

```bash cURL theme={null}
curl -X GET 'https://developers.flouci.com/api/v2/subscriptions/s7Qm3kLpTq2e9hZx0bYw1A' \
  -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>'
```

### Path Parameters

**subscription\_id** `string` *required*

The `subscription_id` returned by Create Subscription.

```json Active theme={null}
{
  "success": true,
  "result": {
    "subscription_id": "s7Qm3kLpTq2e9hZx0bYw1A",
    "status": "active",
    "payment_method": "flouci",
    "amount": 15000,
    "currency": "TND",
    "interval": "month",
    "interval_count": 1,
    "name": "Gold plan",
    "description": "Full access, billed monthly",
    "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"
}
```

```json Incomplete theme={null}
{
  "success": true,
  "result": {
    "subscription_id": "s7Qm3kLpTq2e9hZx0bYw1A",
    "status": "incomplete",
    "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": null,
    "current_period_start": null,
    "current_period_end": null,
    "next_charge_at": null,
    "cycles_completed": 0,
    "max_cycles": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancellation_initiator": null,
    "cancellation_reason": null,
    "latest_charge": {
      "payment_id": "AgCKuBm0S5uLPghBo571MQ",
      "status": "PENDING",
      "type": "NA",
      "billing_reason": "subscription_create",
      "attempt": 0,
      "period_start": "2026-09-30",
      "period_end": null,
      "amount": 15000,
      "fee": "",
      "tva": "",
      "created_at": "2026-09-30T14:02:11+01:00",
      "paid_at": null
    },
    "payment_id": "AgCKuBm0S5uLPghBo571MQ",
    "checkout_url": "https://checkout.flouci.com/company_name/AgCKuBm0S5uLPghBo571MQ"
  },
  "name": "developers",
  "code": 0,
  "version": "v2"
}
```

```json Error (404) theme={null}
{
  "success": false,
  "message": "subscription_not_found",
  "name": "developers",
  "code": 1,
  "version": "v2"
}
```

### Response Fields

**subscription\_id** `string` *required*

Identifier of the subscription.

**status** `string` *required*

One of `incomplete`, `incomplete_expired`, `active`, `past_due`, `unpaid`, `canceled`. See [Statuses](https://docs.flouci.com/api-reference/recurring-payments/overview#statuses).

**payment\_method** `string` *required*

`flouci` (wallet) today; `card` once card recurring is available.

**amount** `integer` *required*

Amount of each charge in millimes.

**currency** `string` *required*

Always `TND`.

**interval** `string` *required*

`day`, `week`, `month` or `year`.

**interval\_count** `integer` *required*

Number of `interval` units per cycle.

**name** `string` *required*

Plan name shown to the customer.

**description** `string`

Optional description; empty string when none was given.

**client\_id** `string | null`

Your customer identifier, if you sent one.

**developer\_tracking\_id** `string` *required*

Your reference for the subscription.

**is\_test** `boolean` *required*

Whether the subscription was created with a test app.

**created\_at** `timestamp` *required*

When the subscription was created.

**activated\_at** `timestamp | null`

When the first charge was paid — the anchor of the billing cycle. `null` while `incomplete`.

**current\_period\_start** `timestamp | null`

Start of the period the customer has paid for.

**current\_period\_end** `timestamp | null`

End (exclusive) of the paid period.

**next\_charge\_at** `timestamp | null`

When the next renewal (or retry) is debited. `null` while a charge is in flight, and on terminal or `unpaid` subscriptions.

**cycles\_completed** `integer` *required*

Number of paid cycles, first charge included.

**max\_cycles** `integer | null`

Total number of payments for an installment plan; `null` for an open-ended subscription.

**cancel\_at\_period\_end** `boolean` *required*

`true` when a cancellation is scheduled for the end of the current period.

**canceled\_at** `timestamp | null`

When the subscription was canceled.

**cancellation\_initiator** `string | null`

Who canceled: `merchant`, `customer` or `system`.

**cancellation\_reason** `string | null`

Why: for example `completed` (`max_cycles` reached), `dunning_exhausted`, `customer_wallet_closed` or `at_period_end`.

**latest\_charge** `object | null`

The most recent charge, in the shape described on [List Charges](https://docs.flouci.com/api-reference/recurring-payments/list-charges).

**payment\_id** `string`

**Only while `status` is `incomplete`.** The first charge to pay.

**checkout\_url** `string`

**Only while `status` is `incomplete`.** The checkout to send the customer back to.

> [!NOTE]
>
> A `subscription_id` that does not belong to your merchant returns `404 subscription_not_found` — never a 403 — so an identifier leaks nothing about other merchants.


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