> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/exploring-features/subscriptions-and-orders.md).

# Subscriptions & Orders

If you sell through a subscription or recurring-fill commerce model, your billing system already knows which patients are subscribed, what's on order, and when the next fill is due. MDI doesn't replace that system — actual charging still happens in your own commerce stack. What MDI gives you is a way to sync that state into the platform so staff and patients see billing and order context alongside the clinical Encounter, instead of two disconnected views of the same patient. That unified view is what the `Subscription` and `Scheduled Order` resources are for.

### Subscription

A `Subscription` represents recurring e-commerce billing state, kept in sync from your system, distinct from a one-time order. It's billing state only — creating or updating a Subscription doesn't trigger a new Encounter or any clinical review on its own. An active Subscription just tells MDI "this patient is on a recurring plan," so that context is visible wherever the patient's record is viewed.

This is the resource-level counterpart to the patient journeys described in [Refills & Follow-Up](/partner/key-concepts/refills-and-follow-up.md): whether a given fill needs a new Encounter still depends on refills remaining and your clinical policy, not on Subscription status.

### Scheduled Order

`Scheduled Orders` represent one-time or recurring fill orders tied to a Subscription. Unlike the Subscription itself, a Scheduled Order can be edited — by your integration or by a clinician — before it's approved.

#### Approval details

Each order carries `approval_date` and `approval_by` fields, but only once it's actually approved or pre-approved while in Upcoming or Scheduled status. If an order fails and gets resubmitted, these fields aren't updated — they always reflect the original approval, not resubmission attempts.

Three actions govern how an order moves through approval:

<table><thead><tr><th width="176.4189453125">Action</th><th>What it does</th><th>Resulting status</th></tr></thead><tbody><tr><td>Approve</td><td>Approves the order immediately</td><td>Ready</td></tr><tr><td>Pre-approve</td><td>Approves the order, but holds it until its <code>effective_date</code> arrives</td><td>Scheduled</td></tr><tr><td>Delete approval</td><td>Removes an existing approval from the order</td><td>Reverts prior status</td></tr></tbody></table>

In the Clinicians App, an approved Scheduled Order shows a visible approved label and checkmark on its order details, so staff can tell at a glance whether an upcoming fill is already cleared.

{% hint style="warning" %}
**Note:** As of a September 2026 platform release, the order status previously called `draft` is now called `upcoming`. This is a breaking rename, not an additive change — if your integration reads or filters on the `draft` status value, update it to `upcoming` before that release reaches your environment.
{% endhint %}

### Where this shows up

Subscription and Scheduled Order data surfaces in two places:

* **Clinicians App** — staff reviewing an Encounter can see the patient's subscription and order context alongside their clinical history, and can edit or approve Scheduled Orders directly.
* **Patient Portal** — patients get visibility into their own subscription and upcoming orders next to their care history, rather than having to check a separate storefront account.

Both surfaces read the same synced data, so keeping your Subscription and Scheduled Order records current is what keeps staff and patient views accurate.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mdintegrations.com/partner/exploring-features/subscriptions-and-orders.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.