Subscriptions

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`	Every subscription, filterable by status, customer and last change
`GET`	`/v1/subscriptions/{id}`	One subscription with its full delivery schedule
`GET`	`/v1/subscriptions/upcoming`	Deliveries scheduled in a date range, with address, items and estimated amount
`GET`	`/v1/subscriptions/by-order/{order_id}`	The subscription a Shopify order belongs to

Changes are pushed to you as subscription webhooks.

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.

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

The subscription object

{
  "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.

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

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

{ "error": "Not found", "message": "No subscription with this id in your organization" }

Get Started

WhatsApp

Instagram

Webhooks

Reporting & AI

Subscriptions

Endpoints

Authentication

Subscription orders in Shopify

The subscription object

The delivery object

Test subscriptions

Errors

​Endpoints

​Authentication

​Subscription orders in Shopify

​The subscription object

​The delivery object

​Test subscriptions

​Errors

Endpoints

Authentication

Subscription orders in Shopify

The subscription object

The delivery object

Test subscriptions

Errors