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

# Subscriptions

> Read FlowIQ subscriptions, their delivery schedule and upcoming deliveries, and know which Shopify order belongs to which subscription.

FlowIQ runs subscriptions for Shopify stores: it charges the saved card on each delivery date and creates a normal Shopify order. This API lets your own systems (logistics, ERP, reporting) read those subscriptions and the deliveries still to come.

The API is read-only. Skipping, pausing, changing or cancelling a subscription is done in FlowIQ, by the customer in their portal, or over WhatsApp.

## Endpoints

| Method | Path | What it returns |
| - | - | - |
| `GET` | [`/v1/subscriptions`](https://docs.flowapt.com/flowiq-api-reference/endpoint/list-subscriptions) | Every subscription, filterable by status, customer and last change |
| `GET` | [`/v1/subscriptions/{id}`](https://docs.flowapt.com/flowiq-api-reference/endpoint/get-subscription) | One subscription with its full delivery schedule |
| `GET` | [`/v1/subscriptions/upcoming`](https://docs.flowapt.com/flowiq-api-reference/endpoint/upcoming-deliveries) | Deliveries scheduled in a date range, with address, items and estimated amount |
| `GET` | [`/v1/subscriptions/by-order/{order_id}`](https://docs.flowapt.com/flowiq-api-reference/endpoint/subscription-by-order) | The subscription a Shopify order belongs to |

Changes are pushed to you as [subscription webhooks](https://docs.flowapt.com/flowiq-api-reference/subscription-webhooks.md).

## Authentication

Use your organisation API key (Settings, API Keys) as a Bearer token. The key decides which store you read; you never pass an organisation id.

```bash theme={null}
curl "https://api.flowiq.live/v1/subscriptions?status=active" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY"
```

Limits: 240 requests per minute per key. Every response carries `organization_id`.

## Subscription orders in Shopify

Every order FlowIQ creates for a subscription is a normal Shopify order, so a system that already reads your Shopify orders receives them with no extra work. Each one is marked so you can tell it apart and place it in the subscription.

**Tags**

| Tag | On |
| - | - |
| `FlowIQ` | Every order FlowIQ creates |
| `FlowIQ Subscription` | Every subscription order |
| `FlowIQ First Order` | The first delivery of a subscription |
| `FlowIQ Recurring Order` | Every delivery after the first |

**Order attributes** (Shopify `note_attributes`, shown as "Additional details" on the order)

| Name | Example | Meaning |
| - | - | - |
| `flowiq_subscription_id` | `3f2c…` | The subscription's id in this API |
| `flowiq_delivery_number` | `3` | Which delivery of the subscription this order is (1 = first) |
| `flowiq_delivery_rhythm` | `every 6 weeks` | How often the subscription delivers |
| `flowiq_next_delivery_date` | `2026-12-07` | The next scheduled delivery after this one (South African date). Absent when none is scheduled |
| `flowiq_subscriber_discount_percent` | `10` | The subscriber discount applied to this order, when the store uses one |
| `flowiq_delivery_fee` | `299.00` | The delivery charged on this order (`0.00` = free delivery), when the store charges delivery on subscriptions |

The order note reads `FlowIQ Subscription Order`. To go from a Shopify order to its subscription, use [`/v1/subscriptions/by-order/{order_id}`](https://docs.flowapt.com/flowiq-api-reference/endpoint/subscription-by-order).

## The subscription object

```json theme={null}
{
  "id": "3f2c6a1e-8b0d-4c55-9f7e-1d2a3b4c5d6e",
  "test": false,
  "status": "active",
  "created_at": "2026-10-26T08:00:01+00:00",
  "updated_at": "2026-10-26T08:00:05+00:00",
  "customer": {
    "contact_id": "9b8a7c6d-…",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "27820000000",
    "shopify_customer_id": "7712345678901"
  },
  "rhythm": { "label": "every 6 weeks", "interval_value": 6, "interval_unit": "weeks" },
  "items": [
    { "variant_id": "44112233445566", "sku": "LL-MWL-15", "title": "Men's Weight Loss 15 pack", "quantity": 1, "unit_price": "1650.00" }
  ],
  "recurring_amount": "1650.00",
  "currency": "ZAR",
  "discount_ladder": {
    "steps": [
      { "from_delivery": 1, "percent": 7.5 },
      { "from_delivery": 2, "percent": 10 },
      { "from_delivery": 3, "percent": 15 }
    ],
    "next_delivery_percent": 10
  },
  "delivery_fee": { "amount": "299.00", "free_over": null },
  "shipping_address": { "address1": "1 Main Road", "city": "Gqeberha", "zip": "6001", "country": "South Africa", "phone": "+27820000000" },
  "next_delivery": { "delivery_number": 2, "date": "2026-12-07", "scheduled_for": "2026-12-07T08:00:02+00:00", "estimated_total": "1784.00" },
  "deliveries": { "completed": 1, "scheduled": 11, "skipped": 0, "paused": 0, "failed": 0 },
  "paused_at": null,
  "resume_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "card_on_file": "CONSENTED"
}
```

| Field | Notes |
| - | - |
| `test` | `true` for a test subscription (mock data to build an integration against: never charged, no Shopify orders). Leave them out with `?test=exclude`, or ignore anything with `test: true` |
| `status` | `active`, `paused` or `cancelled` |
| `recurring_amount` | Price of the items per delivery before any subscriber discount, excluding delivery |
| `discount_ladder` | `null` when the store has no subscriber discount. Each delivery gets the step for its place among paid deliveries |
| `delivery_fee` | `null` when the store charges no delivery on subscriptions. `free_over` is the order value above which delivery is free, when switched on |
| `next_delivery` | The next delivery that will be charged; `null` when nothing is scheduled (paused, cancelled, or no dates left) |
| `card_on_file` | Status of the customer's saved card; a delivery cannot be charged without a consented card |

New fields may be added to any object. Existing fields are never renamed or removed.

## The delivery object

Returned in a subscription's `schedule` and by [upcoming deliveries](https://docs.flowapt.com/flowiq-api-reference/endpoint/upcoming-deliveries.md).

| Field | Notes |
| - | - |
| `test` | `true` when the delivery belongs to a test subscription |
| `delivery_number` | 1 for the first delivery, then 2, 3… |
| `date` | Delivery date in South Africa, `YYYY-MM-DD` |
| `status` | `scheduled`, `paused`, `skipped`, `pending` (being charged), `processing`, `completed`, `failed`, `cancelled` |
| `items` | `variant_id`, `sku`, `title`, `quantity`, `unit_price` |
| `shipping_address` | Where this delivery goes |
| `shopify_order_id`, `shopify_order_name` | Set once the delivery has been charged and its Shopify order created |
| `charged_amount` | What was charged, once charged |
| `estimate` | For deliveries still to come: `goods`, `discount_percent`, `discount`, `delivery_fee`, `total` |
| `failure_reason` | Why a charge failed, on `failed` deliveries |

> [!NOTE]
>
> `estimate` is what the delivery would cost if it were charged today. A price change in Shopify, or an edit to the subscription before the date, changes it; the charge itself is always priced at the moment it runs.

## Test subscriptions

To build and test an integration before real subscribers exist, FlowIQ can load test subscriptions into your store's account. They behave like real ones: deliveries move on their dates, the subscriber discount and delivery fee are applied, and pausing, skipping or cancelling them sends the same webhooks. They never charge a card, never create a Shopify order (completed deliveries carry a `TEST-…` order reference instead) and never message anyone. Every object carries `"test": true`. Ask Flowapt to load or remove them.

## Errors

| Status | When |
| - | - |
| `400` | A parameter is invalid (the body says which) |
| `401` | Missing, invalid, revoked or expired API key |
| `403` | The key has no read permission |
| `404` | No such subscription, or the order is not a FlowIQ subscription order, in your organisation |
| `429` | More than 240 requests in a minute |

```json theme={null}
{ "error": "Not found", "message": "No subscription with this id in your organization" }
```


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