> ## 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](/api-reference/recurring-payments/webhooks) for renewals rather than polling.

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

### Path Parameters

<ParamField path="subscription_id" type="string" required>
  The `subscription_id` returned by Create Subscription.
</ParamField>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="subscription_id" type="string" required>
  Identifier of the subscription.
</ResponseField>

<ResponseField name="status" type="string" required>
  One of `incomplete`, `incomplete_expired`, `active`, `past_due`, `unpaid`, `canceled`. See [Statuses](/api-reference/recurring-payments/overview#statuses).
</ResponseField>

<ResponseField name="payment_method" type="string" required>
  `flouci` (wallet) today; `card` once card recurring is available.
</ResponseField>

<ResponseField name="amount" type="integer" required>
  Amount of each charge in millimes.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Always `TND`.
</ResponseField>

<ResponseField name="interval" type="string" required>
  `day`, `week`, `month` or `year`.
</ResponseField>

<ResponseField name="interval_count" type="integer" required>
  Number of `interval` units per cycle.
</ResponseField>

<ResponseField name="name" type="string" required>
  Plan name shown to the customer.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description; empty string when none was given.
</ResponseField>

<ResponseField name="client_id" type="string | null">
  Your customer identifier, if you sent one.
</ResponseField>

<ResponseField name="developer_tracking_id" type="string" required>
  Your reference for the subscription.
</ResponseField>

<ResponseField name="is_test" type="boolean" required>
  Whether the subscription was created with a test app.
</ResponseField>

<ResponseField name="created_at" type="timestamp" required>
  When the subscription was created.
</ResponseField>

<ResponseField name="activated_at" type="timestamp | null">
  When the first charge was paid — the anchor of the billing cycle. `null` while `incomplete`.
</ResponseField>

<ResponseField name="current_period_start" type="timestamp | null">
  Start of the period the customer has paid for.
</ResponseField>

<ResponseField name="current_period_end" type="timestamp | null">
  End (exclusive) of the paid period.
</ResponseField>

<ResponseField name="next_charge_at" type="timestamp | null">
  When the next renewal (or retry) is debited. `null` while a charge is in flight, and on terminal or `unpaid` subscriptions.
</ResponseField>

<ResponseField name="cycles_completed" type="integer" required>
  Number of paid cycles, first charge included.
</ResponseField>

<ResponseField name="max_cycles" type="integer | null">
  Total number of payments for an installment plan; `null` for an open-ended subscription.
</ResponseField>

<ResponseField name="cancel_at_period_end" type="boolean" required>
  `true` when a cancellation is scheduled for the end of the current period.
</ResponseField>

<ResponseField name="canceled_at" type="timestamp | null">
  When the subscription was canceled.
</ResponseField>

<ResponseField name="cancellation_initiator" type="string | null">
  Who canceled: `merchant`, `customer` or `system`.
</ResponseField>

<ResponseField name="cancellation_reason" type="string | null">
  Why: for example `completed` (`max_cycles` reached), `dunning_exhausted`, `customer_wallet_closed` or `at_period_end`.
</ResponseField>

<ResponseField name="latest_charge" type="object | null">
  The most recent charge, in the shape described on [List Charges](/api-reference/recurring-payments/list-charges).
</ResponseField>

<ResponseField name="payment_id" type="string">
  **Only while `status` is `incomplete`.** The first charge to pay.
</ResponseField>

<ResponseField name="checkout_url" type="string">
  **Only while `status` is `incomplete`.** The checkout to send the customer back to.
</ResponseField>

<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.
</Note>


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