Subscriptions & refills

A subscription turns a one-time order into ongoing supply: it arms a refill schedule, and on each cycle neolife drafts the next order automatically. What it does not do is auto-ship a drug — every refill is created provider-gated and still needs a licensed provider's approval before it can be filled.

The model#

A subscription carries a cadence (intervalDays), the product or protocol to refill, a quantity, and a nextFillAt timestamp for when the next fill is due. On its status:

Status	Behaviour
active	Generates a refill each cycle when nextFillAt comes due.
paused	Skipped — no refills are generated while paused.
cancelled	Skipped permanently.

Only active subscriptions whose nextFillAt has arrived produce a refill. Pausing or cancelling stops the schedule immediately; nothing already shipped is affected.

Each refill is provider-gated#

This is the important part. When a subscription comes due, neolife creates the refill as a new order in pending_approval — it does not submit anything to a pharmacy on its own. From there the refill flows through the exact same lifecycle as any first-time order: a licensed provider reviews it, approves (or rejects) it, and only an approved order is eligible for submission, routing, and tracking.

A subscription automates the logistics of reordering, never the clinical decision to dispense. There is no path where a refill ships without a provider signing off on that specific cycle. This is the same rule described in Orders & fulfillment — a subscription doesn't create an exception to it.

If the product on a refill has a follow-up questionnaire, that check-in is the telehealth touchpoint for the cycle: the patient is emailed a link to complete it, and the provider reviews the refill and the follow-up together before approving. See Intake for how questionnaires work.

Cadence and scheduling#

The schedule advances by exactly one intervalDays interval per cycle, anchored to the previous nextFillAt rather than to the moment the refill actually runs. Cadence therefore never drifts — a fill that generates a little late doesn't push every future fill later. If several cycles were missed, the schedule rolls forward to the next future slot rather than firing a burst of back-dated refills.

A refill is only generated once per cycle: if an open (non-terminal) order already exists for the subscription, that cycle is considered covered and no duplicate is created. Combined with idempotent submission downstream, a subscription cannot double-ship a cycle.

Pausing and cancelling#

Set a subscription to paused to hold supply — for a patient who wants to skip a cycle, or while a clinical question is resolved — and back to active to resume. cancelled ends the schedule for good. Because generation only ever looks at active subscriptions at their due time, a status change takes effect on the very next sweep; there's no in-flight refill to unwind unless one has already been drafted, in which case it sits in pending_approval and a provider can simply reject it.

Seeing what's coming up#

You can look ahead at subscriptions due to refill soon — useful for staffing provider review or reaching out to patients before their check-in. The window defaults to the next 7 days:

curl "https://api.neolife.health/v1/refills/upcoming?days=14" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

{
  "items": [
    {
      "id": "sub_9f2c…",
      "displayName": "Monthly compounded protocol",
      "nextFillAt": "2026-07-20T00:00:00.000Z",
      "intervalDays": 30,
      "status": "active"
    }
  ]
}

The response is PHI-minimal by design — it carries scheduling detail, not clinical history. As with everything on the rail, you hydrate fuller detail over authenticated GETs only when you need it (the PHI boundary).

In short#

• A subscription arms a schedule; it does not ship drugs.
• Every refill is a fresh pending_approval order that a provider must approve before it's filled.
• Approved refills flow through the same submit → route → track loop as any order.
• Cadence is drift-free; pausing or cancelling stops generation on the next cycle.