Order Flow

This guide explains how orders are created and move through the app from a Customer Support and clinic operations point of view. It focuses on checkout orders, manually created EMR orders, subscription cycle orders, phase-based subscription orders, fulfillment timing, and how order status relates to intake and Beluga.

What an Order Represents

An order is the operational record for a charge/product event.

An order can represent:

a checkout purchase
the first payment for a subscription
a recurring subscription cycle
a manual CS/staff-created order
a payment-only recovery cycle
a payoff or switch-related order

Orders are separate from subscriptions. A subscription is the recurring agreement. Orders are the individual billing/product events created under that agreement.

Main Ways Orders Are Created

Checkout Order

Created when the patient checks out from the public cart.

Checkout does this:

patient completes cart and payment
app creates order(s)
app creates invoice(s)
if the product is a subscription, app creates subscription(s)
order is linked to the subscription through order metadata
order status is recalculated based on intake/product requirements
if ready, Beluga auto-submit may run

Important: each subscription product in the cart gets its own order. Non-subscription items can share a separate order.

Manual EMR Order

Created by staff from the EMR.

Manual EMR order creation does this:

staff selects patient and items
app creates an order
app creates an invoice
order starts as PENDING
intake pending workflows may fire if the product requires intake
Beluga auto-submit is attempted in the background, but can be blocked if intake/configuration is missing

Important: a manual EMR order does not automatically create a subscription. If the patient needs a recurring subscription, confirm that a subscription record exists separately.

Subscription Cycle Order

Created by the subscription processor when a subscription is due for its next billing cycle.

Subscription processor does this:

finds active subscriptions with due nextBillingDate
advances the billing period
creates a new order and invoice
links the order to the subscription in metadata
includes cycle number and billing period dates
tries to auto-charge the saved payment method
if payment succeeds, recalculates order status
if payment fails or no payment method exists, moves the order into payment recovery

How Orders Are Linked to Subscriptions

Subscription-linked orders are connected through order metadata.

CS may see fields like:

subscriptionId
subscriptionIds
cycleNumber
billingInterval
billingIntervalCount
billingPeriodStart
billingPeriodEnd
autoChargeStatus
autoChargeMessage
recoveryStatus

Common source labels:

CHECKOUT / CHECKOUT_CART: first checkout order
SUBSCRIPTION / SUBSCRIPTION_CYCLE: recurring subscription cycle order
MANUAL / EMR_MANUAL: manually created EMR order
SUBSCRIPTION_SWITCH / SUBSCRIPTION_SWITCH_PAYOFF: switch payoff order
SUBSCRIPTION / SUBSCRIPTION_SWITCH_NEW: replacement subscription order after a switch

If an order is not showing as related to a subscription, check whether it has subscriptionId metadata.

Subscription Phase Orders

Subscription products can have phases/variants. Each phase can have:

price
duration cycles
cycle start flag
Beluga visit type
phase-specific questionnaire mapping

The subscription tracks:

currentPhaseIndex
cyclesInPhase

When a subscription cycle order is created, the order item is tied to the current phase/variant. After a successful payment, the subscription advances to the next phase when the current phase duration is complete.

Product Phase Examples

First Product Phase

Usually represents the product delivery/start phase.

Common behavior:

patient is charged
order may require intake
order may go to Beluga
fulfillment may happen after medical/prescription requirements are satisfied

Recovery / Payment-Only Phase

Usually represents financed balance recovery after the product was already shipped.

In product setup, this is commonly represented by:

belugaVisitType = none

Current app behavior:

if every item with a phase is payment-only (belugaVisitType = none), the paid order can be marked COMPLETED
no new Beluga visit should be submitted
no new consultation should be required
no new fulfillment/shipment should be created

CS explanation:

This order is a payment recovery cycle. It collects the remaining balance from a prior product shipment and should not create a new shipment.

Looping / Renewal Phase

If a phase is marked as the cycle start, the subscription can loop back to that phase after finite phases are exhausted.

CS should not manually change phase progress unless instructed by admin/development.

Order Statuses CS Will See

`PENDING`

Order was created but has not yet been fully processed.

Common for:

newly created manual EMR orders
subscription cycle orders before auto-charge processing completes

`AWAITING_PAYMENT`

Payment is needed.

Common causes:

patient invoice needs to be paid
saved card is missing
auto-charge failed
payment recovery is active

`AWAITING_REQUIREMENTS`

Order is waiting on intake or required information.

Common causes:

required intake form not submitted
intake sent back for correction
intake rejected but still visible as needing action
required Beluga lab method missing
Beluga visit is configured but no questionnaire mapping exists

`AWAITING_SCRIPT`

Order is ready for medical/prescription work.

Important: this does not mean the order should ship. It means intake/configuration requirements are satisfied and the order can move to Beluga/prescription review.

`AWAITING_FULFILLMENT`

Order has cleared enough requirements to move into fulfillment operations.

For medication orders, still confirm that the prescription boundary has been reached before shipment/pharmacy submission.

`AWAITING_SHIPMENT`

Fulfillment is in progress and the order is waiting for shipment.

`SHIPPED`

Order has shipped.

`COMPLETED`

Order is complete.

Payment-only subscription recovery cycles can become COMPLETED without shipment.

`REJECTED`

Order was medically or operationally rejected.

If intake is rejected, linked subscriptions may be canceled.

`CANCELLED`

Order was canceled.

`REFUNDED`

Order was refunded and is locked from normal status edits.

Fulfillment Rules

Do not assume a paid order should ship immediately.

Before fulfillment, check:

order status
whether the order is payment-only
whether intake is required and complete
whether medical review/prescription is complete
Beluga status, if applicable
pharmacy/fulfillment integration status

Payment-only recovery orders should not ship.

Medication orders should not be sent to pharmacy just because:

checkout succeeded
invoice payment succeeded
subscription cycle payment succeeded
intake was submitted
intake was approved
Beluga visit was created

For Beluga medication flows, downstream pharmacy submission should wait for prescription confirmation such as the RX_WRITTEN webhook.

Beluga Relationship

Beluga is used for medical/telehealth submission.

The app may auto-submit an order to Beluga when:

checkout payment succeeds and no intake is required
intake is completed and the order becomes ready
intake is approved and the order becomes ready
patient invoice/payment retry succeeds and the order becomes ready
subscription cycle payment succeeds and the order becomes ready
manual EMR order is created, though Beluga may reject/block submission if intake is missing

Beluga submission can be blocked by:

missing intake
intake needing correction
rejected intake
missing lab method answer/configuration
missing Beluga visit type
missing drug mapping or Beluga medId/DIN
missing pharmacy configuration

If Beluga submission fails, fix the configuration/intake issue first, then retry from EMR tools.

Manual CS Orders

When CS/staff creates an order manually:

the app creates an invoice
the order source is MANUAL
the source context is EMR_MANUAL
the order does not automatically create a subscription
intake pending workflows may fire
Beluga auto-submit may be attempted

CS should verify:

patient is correct
items/products are correct
invoice is correct
whether the order needs payment
whether the order needs intake
whether the order should be connected to a subscription

If the manual order is meant to be part of a subscription but no subscription link exists, escalate before treating it as a recurring subscription order.

Checkout Subscription Orders

When a subscription product is purchased at checkout:

app creates the order
app creates the invoice
app creates the subscription
order metadata stores subscriptionId
first order is cycle 1
billing period start/end are stored
subscription next billing date is calculated
subscription phase advances after the first paid cycle

The first checkout order may require intake and medical review before fulfillment.

Recurring Subscription Orders

When the subscription processor creates a recurring order:

order source is SUBSCRIPTION
source context is SUBSCRIPTION_CYCLE
order is linked to the subscription
cycle number is stored
current phase/variant is attached to the order item
invoice is created
auto-charge is attempted

If charge succeeds:

invoice is paid
order status is recalculated
subscription phase may advance
subscription switch/cancellation checks may run
Beluga may auto-submit if the order is ready for script

If charge fails:

order moves to AWAITING_PAYMENT
subscription may pause
recovery metadata is stored
patient may receive recovery notification
successful retry can reactivate the subscription

Payment Recovery Orders

Payment recovery applies when an order needs payment after a failed or skipped charge.

Recovery metadata may show:

recoveryStatus
retryCount
maxRetryCount
nextRetryAt
lastRetryAt
recoveryUrl

Common recovery statuses:

NEEDS_PAYMENT_METHOD
RETRY_SCHEDULED
RESOLVED
FAILED_FINAL

CS should direct patients to update/pay from the patient invoice or recovery flow. Do not duplicate the order unless instructed.

Common Patient Questions

Why do I see another order if I did not order again?

If you have a subscription, the system creates an order for each billing cycle. Some cycles may be payment-only recovery cycles and may not ship a new product.

Why was I charged but nothing shipped?

This may be a payment recovery cycle for a financed product. It collects the remaining balance from a prior shipment and does not create a new shipment.

Does paid mean shipped?

No. Payment is only one step. Some orders still need intake, medical review, prescription confirmation, or fulfillment processing.

Why is my order waiting on requirements?

The order is waiting on required intake or missing information before medical review can continue.

Why is my subscription paused?

The subscription may pause automatically after a failed recurring charge or missing payment method. It can resume when payment is recovered.

Troubleshooting

Order is not linked to a subscription

Check:

was it created through checkout as a subscription product?
was it created manually by CS?
does order metadata include subscriptionId?
does the patient have an active subscription record?

Manual EMR orders do not automatically create subscriptions.

Order was paid but is not fulfilled

Check:

order status
required intake status
Beluga submit status
prescription/RX status
whether order is payment-only recovery
pharmacy/fulfillment status

Subscription cycle order did not ship

Check:

current phase/variant
whether belugaVisitType = none
whether it is a recovery/payment-only phase
whether product was already shipped in an earlier phase

Payment-only phases should not ship.

Subscription order is stuck in AWAITING_PAYMENT

Check:

invoice status
auto-charge status/message
saved payment method
gateway used
recovery status
whether subscription is paused

Order is stuck in AWAITING_REQUIREMENTS

Check:

required intake forms
correction/rejection status
lab method answer/configuration
product questionnaire mapping

Beluga did not submit

Check:

order is not payment-only
order has Beluga visit type
required intake is complete
Beluga submit status/error
drug mapping and Beluga medId/DIN
pharmacy configuration

CS Escalation Checklist

Escalate to admin/development or medical operations when:

manual order should be tied to a subscription but is not
subscription cycle order has the wrong phase/product
payment-only recovery order is moving toward shipment
order shipped before prescription confirmation
order status does not match intake/payment state
subscription is paused but payment appears successful
duplicate orders were created for the same cycle
Beluga submit failed after requirements were satisfied

Include these details when escalating:

patient name/email
order number
subscription id, if any
product name
order source/source context
cycle number, if any
current order status
invoice/payment status
current phase/variant, if visible
Beluga submit status/error, if any
what the patient sees in portal