Subscription Lifecycle Guide

This guide explains how subscriptions work from a Customer Support and clinic operations point of view. It covers how subscriptions are created, how billing cycles create orders, what subscription statuses mean, how phases work, what CS can see on the EMR Subscriptions page, and when subscription changes affect intake, Beluga, pharmacy, and fulfillment.

What a Subscription Is

A subscription is the recurring billing agreement for a patient.

It is separate from:

orders
invoices
payments
intake forms
Beluga visits
pharmacy fulfillment

The subscription controls when the next billing cycle should happen. Each billing cycle creates its own order and invoice.

Subscription Statuses

`ACTIVE`

The subscription is live and can be picked up by the billing processor when nextBillingDate is due.

`PAUSED`

Billing and phase changes are stopped.

Common reasons:

automatic renewal payment failed
no compatible saved payment method exists
staff manually paused the subscription
dose change flow paused the current subscription

`CANCELLED`

The subscription is stopped permanently.

Important:

cancelled subscriptions cannot be reactivated in the app
no future billing should happen
cancellation can clean up linked pending intake forms

`EXPIRED`

The subscription reached its endDate and the system marked it expired.

Main Ways Subscriptions Are Created

Checkout

When a patient buys a subscription product through checkout:

checkout creates an order
checkout creates an invoice/payment
app creates the subscription
first order is linked to the subscription
nextBillingDate is calculated
product phase/cycle information is initialized

The first order may still require intake, Beluga review, prescription confirmation, and pharmacy fulfillment before shipment.

EMR Manual Subscription

Staff can create a subscription from:

EMR -> Subscriptions -> New Subscription

Manual creation:

creates the subscription
creates the initial order and invoice
charges the selected or default payment method immediately
links the initial order to the subscription
fires subscription/order workflows

If the initial charge fails, the app rolls back the new subscription, order, invoice, and payment attempt instead of leaving a broken active subscription.

EMR Subscriptions Page

Go to:

EMR -> Subscriptions

The page is used to manage patient subscription plans.

CS can:

search by patient or subscription id
filter by status
filter by product
filter by product category
filter by current cycle
filter by created date range
view historical subscription metrics
view the payment recovery queue
manually process due billing
create a new subscription
open subscription details
pause, activate, or cancel subscriptions

Important page sections:

Historical Subscription Metrics
Payment Recovery Queue
subscription filters
subscription table
Process Due Billing
New Subscription

EMR Subscription Details

Open a subscription from:

EMR -> Subscriptions -> View
EMR -> Patient Profile -> Subscriptions -> View

The details view shows:

subscription id
patient
status
current cycle
next cycle
next billing date
current phase
current phase Beluga visit type
next upcoming phase
related orders
status history
created event
dose increase action for active subscriptions

If the subscription is cancelled, the detail view shows that no future billing or phase changes will occur.

If the subscription is paused, the detail view shows that billing and phase changes are stopped until reactivated.

Related Orders in Subscription Details

Subscription-linked orders are shown in the details view when their order metadata includes the subscription id.

Related orders may include:

initial subscription order
recurring cycle orders
payment recovery orders
dose change orders
switch replacement orders

Order metadata can include:

source
sourceContext
subscriptionId
cycleNumber
billingPeriodStart
billingPeriodEnd
autoChargeStatus
autoChargeMessage

Use related orders to understand what happened on each billing cycle.

Billing Cadence

Subscription cadence comes from:

interval
intervalCount

Examples:

monthly every 1
weekly every 1
days every 30

The processor calculates the next billing date by adding the interval/count to the current billing date.

Recurring Billing Flow

When the subscription processor runs:

it finds ACTIVE subscriptions with nextBillingDate due
it advances nextBillingDate
it creates a cycle order
it creates an invoice
it links the order to the subscription
it assigns the product default pharmacy to the order
it tries to charge a compatible saved payment method
it recalculates order status after payment
it advances the subscription phase after successful payment
it checks subscription switching/cancellation rules
it may submit to Beluga if the order becomes ready for script

The cycle order source is:

source: SUBSCRIPTION
sourceContext: SUBSCRIPTION_CYCLE

Payment Success

If the cycle charge succeeds:

invoice becomes PAID
order gets chargedAt
order status is recalculated
subscription phase may advance
switch requests may be refreshed/executed
Beluga may auto-submit if the order is ready for script
workflows may fire

Payment success does not automatically mean shipment. Medication orders may still need intake, Beluga review, RX_WRITTEN, and pharmacy fulfillment.

Payment Failure

If the cycle charge fails or no compatible payment method exists:

order moves to AWAITING_PAYMENT
recovery metadata is stored on the order
subscription may become PAUSED
payment recovery notifications/workflows may fire
patient can resolve payment through the patient portal

Common recovery statuses:

NEEDS_PAYMENT_METHOD
RETRY_SCHEDULED
RESOLVED
FAILED_FINAL

See payment-recovery-README.md for the full recovery guide.

Reactivating a Paused Subscription

Staff can reactivate a paused subscription from EMR.

If the old nextBillingDate is in the past, the app moves nextBillingDate to now when reactivating. This prevents the subscription from staying stuck with an overdue billing date.

CS should still check:

was the recovery invoice paid?
is there a compatible saved payment method?
should billing resume immediately?
is there an unresolved failed cycle order?

Do not reactivate only to bypass a failed payment. Resolve the recovery invoice when applicable.

Subscription Phases

Subscription products can have phases/variants.

Phase fields can include:

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

The subscription tracks:

currentPhaseIndex
cyclesInPhase

After successful paid cycles, the app advances the phase when the current phase duration is complete.

If the last phase is complete, the app may loop back to the phase marked cycleStart. If no cycle start phase exists, it stays on the last phase.

Recovery / Payment-Only Phases

A phase with:

belugaVisitType = none

is treated as payment-only/no-consultation behavior in current subscription logic.

CS explanation:

This cycle is collecting payment for the subscription balance and should not create a new consultation or shipment.

Payment-only phases may become complete without new fulfillment.

Intake and Beluga Relationship

Subscription cycle orders can still require intake or Beluga review depending on the product/phase.

After a successful cycle payment:

order status is recalculated
if intake is missing, order may wait in AWAITING_REQUIREMENTS
if ready for prescription review, order may move to AWAITING_SCRIPT
if ready for script, Beluga auto-submit may run

Do not tell a patient that a renewal will ship simply because the subscription charged.

Pharmacy and Fulfillment Relationship

Subscription billing is not pharmacy fulfillment.

Before fulfillment, confirm:

order was paid
intake is complete if required
Beluga/prescription review is complete if required
RX_WRITTEN exists for Beluga medication flows
product is not in a payment-only recovery phase
pharmacy routing is correct

See pharmacy-fulfillment-README.md for pharmacy routing details.

Dose Increase / Dose Change

Active subscriptions can show:

Request Dose Increase

In the current EMR flow:

staff selects a different active subscription product
app creates a dose-change order and invoice
app charges the patient immediately
app pauses the current subscription
order status is recalculated
intake pending workflows may fire
a new Beluga review may be needed for the new prescription

Important: the old subscription is paused during the dose-change process. CS should verify what should happen after medical approval, because the dose-change order and subscription lifecycle may require follow-up handling.

Subscription Switching

Subscription switching lets a patient move from one subscription product to another without mutating the old subscription in place.

Supported paths:

scheduled switch after recovery is complete
immediate payoff switch if the product allows payoff switching

Switching creates a replacement subscription only after the required payoff/recovery rules are satisfied. The old subscription is canceled only after the replacement subscription charge succeeds.

See subscription-switching-README.md for the full CS guide.

Cancellation Behavior

Staff can cancel from:

EMR -> Subscriptions
EMR -> Patient Profile -> Subscriptions

When canceled:

status becomes CANCELLED
cancelledAt is set
subscription cancellation workflow may fire
linked pending intake cleanup may run
no future billing should occur
subscription cannot be reactivated

CS should not cancel a subscription when the patient only needs a billing retry or intake correction.

Upcoming Renewal Workflows

The app can fire upcoming renewal workflows before the next billing date.

Trigger:

subscription.upcomingrenewal

Useful workflow data:

days until renewal
next billing date
subscription id
patient contact details

These workflows are for reminders. They do not create orders by themselves.

Workflow Triggers

Subscription-related workflows include:

subscription.created
subscription.cancelled
subscription.paused
subscription.activated
subscription.upcomingrenewal
subscription.order.created
payment.succeeded
payment.failed

These may be used for patient notifications, staff alerts, and operational follow-up.

What CS Should Check Before Advising a Patient

Check:

subscription status
current product
current phase
Beluga visit type for the current phase
current cycle
next billing date
related orders
latest invoice/payment status
payment recovery status
patient payment method
pending intake
Beluga submit status
switch request state, if any
cancellation/scheduled cancellation notes, if any

Common Patient Questions

Why was I charged again?

If the patient has an active subscription, each billing cycle creates a new order and invoice. Check the related order cycle number and billing period.

Why was I charged but nothing shipped?

The cycle may be a payment-only recovery phase, or the order may still need intake, medical review, prescription confirmation, or pharmacy processing.

Why is my subscription paused?

Most commonly, a renewal payment failed or no compatible payment method was available. Check the payment recovery queue and related order.

Can you restart my canceled subscription?

Canceled subscriptions cannot be reactivated in the app. A new subscription may need to be created if clinically and operationally appropriate.

Why does my subscription show paused after a dose increase request?

The dose-change flow pauses the current subscription while the new dose order goes through payment and medical review.

Troubleshooting

Subscription did not bill

Check:

status is ACTIVE
nextBillingDate is due
subscription is not cancelled/expired
payment processor cron ran
saved payment method exists
active gateway matches saved payment method
end date has not passed

Subscription billed but order is not moving

Check:

related order status
invoice/payment status
intake status
Beluga submit status
current phase/visit type
pharmacy/fulfillment status

Subscription is paused but patient says they paid

Check:

recovery invoice status
latest payment record
whether payment was for the correct invoice
whether subscription was reactivated
related order recovery status

Wrong phase or product appears on cycle order

Check:

product variants/phases
currentPhaseIndex
cyclesInPhase
phase duration cycles
cycle start flag
whether a manual change, switch, or dose change occurred

Escalate before manually correcting phase data.

Patient wants to cancel

Before canceling, check:

pending shipment
unpaid recovery invoice
pending switch request
pending dose change
pending intake/Beluga review
refund or billing policy

Cancel only when the subscription should stop permanently.

CS Escalation Checklist

Escalate to admin/development, billing, or medical operations when:

subscription status does not match payment/order state
subscription was paused but payment appears successful
subscription billed twice for the same cycle
related cycle order is missing
phase progression looks incorrect
payment-only phase moved toward fulfillment
canceled subscription appears to bill again
dose change paused a subscription but follow-up handling is unclear
switch request and subscription status disagree
patient was charged unexpectedly

Include these details when escalating:

patient name/email
subscription id
product name
subscription status
current phase
current cycle
next billing date
related order number
invoice/payment status
recovery status, if any
Beluga submit status, if any
switch/dose-change status, if any
screenshot or exact patient/staff-facing message