Refill Flow

This guide explains how patient refill orders work from a Customer Support and clinic operations point of view. It covers when a patient can request a refill, how the refill order is created, how it is linked to the original order, how payment works, and how refill orders relate to intake, Beluga, and fulfillment.

What a Refill Order Is

A refill order is a new order created from a previous paid order.

It is not:

a subscription cycle order
an automatic subscription renewal
an edit to the original order
a pharmacy fulfillment refill by itself

The refill flow creates a separate order and invoice for the selected product. The new refill order is linked back to the original order for visibility.

Where Patients Request Refills

Patients request refills from:

Patient Portal -> Orders

When an order is refill-eligible, the patient can click:

Request Refill

The refill modal shows:

original order number
refillable product options from that order
saved payment methods
total charged today
Pay & Request Refill

Refill Eligibility

An order can show refill options only when:

the order belongs to the patient
the original order is paid
the original order status is refill-eligible
the selected product still exists on the original order
the selected product is still active
the patient has a saved payment method for the active gateway

Eligible order statuses include:

AWAITING_FULFILLMENT
AWAITING_REQUIREMENTS
AWAITING_REQUISITION
AWAITING_RESULTS
AWAITING_SCRIPT
AWAITING_SHIPMENT
PROCESSING
SHIPPED
COMPLETED

Not eligible examples:

unpaid orders
canceled orders
refunded orders
rejected orders
orders where the product is inactive

What Happens When Patient Requests a Refill

Patient opens a refill-eligible order.
Patient selects a product from that order.
Patient selects a saved payment method.
App creates a new refill order.
App creates a new invoice.
App immediately attempts payment.
If payment succeeds, invoice is marked paid.
Order status is recalculated based on product/intake/Beluga requirements.
If the order is ready for script, the app may auto-submit to Beluga.
Intake pending workflows may fire if the refill requires intake.

How Refill Orders Are Labeled

Refill orders are marked with order metadata.

Important labels:

source: PATIENT_PORTAL
sourceContext: PATIENT_REFILL
refillOfOrderId
refillOfOrderNumber
refillProductId

In EMR order details, staff should see a refill notice:

Patient refill order
original order link/number
note that it was created from the patient portal refill flow

This helps CS distinguish refill orders from subscription cycle orders.

Refill Order vs Subscription Order

Refill orders are not created by the subscription processor.

Refill order:

created by patient action in the patient portal
linked to an original order
source context is PATIENT_REFILL
charges immediately using selected saved payment method

Subscription cycle order:

created automatically by subscription billing
linked to a subscription
source context is SUBSCRIPTION_CYCLE
uses subscription billing cadence and cycle number

If a patient says "I was charged for my subscription" but the order is marked PATIENT_REFILL, explain that this was a refill request from the patient portal, not an automatic subscription cycle.

Payment Behavior

The refill charge is attempted immediately.

If payment succeeds:

payment record is created as successful
invoice is marked PAID
order gets chargedAt
order metadata shows refill charge completed
order status is recalculated

If payment fails:

refill order and invoice still exist
payment record is created as failed
patient receives an error that the gateway declined the transaction
invoice remains available for retry/payment handling

CS should not create a duplicate refill order just because payment failed. Check the newly created refill invoice first.

Refill Price and Quantity

The refill price uses the current active product price, not necessarily the original historical order price.

Current behavior:

refill quantity is 1
refill unit price comes from the current product price
original order quantity is shown to the patient for context

CS should verify current product price before explaining a refill charge.

Intake Relationship

A refill order may still require intake.

After a successful refill payment, the app recalculates the order status:

if intake is required or missing, order can go to AWAITING_REQUIREMENTS
if requirements are satisfied, order can go to AWAITING_SCRIPT
if no intake/medical requirements apply, it may move further through normal order status logic

Intake pending workflows may fire for refill orders.

CS explanation:

Your refill request was received and paid. If the medical team needs updated intake information, your order may wait in requirements until that is completed.

Beluga Relationship

If the refill order becomes ready for script, the app may auto-submit it to Beluga.

Auto-submit trigger:

patient_refill_payment_succeeded

Beluga submission can still be blocked by:

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

If Beluga submission fails, staff should fix the issue and retry from EMR tools.

Fulfillment Relationship

A refill request does not automatically mean product should ship immediately.

Before fulfillment, confirm:

refill payment succeeded
order status is appropriate
intake is complete if required
Beluga/medical review is complete if required
prescription boundary has been reached for medication orders
pharmacy/fulfillment integration is ready

Do not submit Belmar/LifeFile, DispensePro, or pharmacy fulfillment only because a refill order was created or paid. Medication fulfillment should wait for prescription confirmation, such as the Beluga RX_WRITTEN webhook when applicable.

What CS Should Check

Before advising the patient, check:

original order number
whether original order was paid
whether original order status is refill-eligible
selected refill product
current product active status
current product price
refill order number
refill invoice status
payment status
refill order status
Beluga submit status/error, if any
whether intake is required

Common Patient Questions

Why do I not see a refill button?

The original order may not be eligible for refill. Common reasons include unpaid order, canceled/refunded/rejected order, inactive product, or no refillable product on the order.

Why is my refill price different from my original order?

Refill pricing uses the current product price. If pricing has changed since the original order, the refill charge may be different.

I paid for a refill. Why has it not shipped?

Payment is only one step. The refill may still require intake, medical review, prescription confirmation, or fulfillment processing.

Is this the same as my subscription renewal?

No. A patient refill order is separate from subscription billing. Subscription cycle orders are created automatically by the subscription processor. Refill orders are created only when the patient requests a refill from the Orders page.

My refill payment failed. Should I request another refill?

No. A refill order and invoice may already have been created. CS should check the refill invoice before advising another request.

Troubleshooting

Patient cannot request refill

Check:

original order belongs to patient
original order is paid
original order status is eligible
product is active
patient has saved payment method for the active gateway

Refill button appears but payment fails

Check:

payment method belongs to patient
payment method gateway matches active organization gateway
gateway decline message
refill invoice status
whether a failed payment record exists

Refill order created but not moving forward

Check:

invoice paid status
order status
intake required status
Beluga submit status/error
product questionnaire mapping
drug/pharmacy configuration

Refill order is confused with subscription renewal

Check source context:

PATIENT_REFILL means patient-requested refill
SUBSCRIPTION_CYCLE means automatic subscription billing cycle

Refill order is moving to fulfillment too early

Escalate if:

medication refill has not received prescription confirmation
Beluga/RX status is missing
intake is missing or needs correction
order is being sent to pharmacy only because refill payment succeeded

CS Escalation Checklist

Escalate to admin/development or medical operations when:

patient was charged but refill order did not update correctly
refill invoice exists but patient was told to create another refill
refill order is missing original order link
refill product/price looks wrong
Beluga submit failed after refill payment
refill is moving to fulfillment before prescription confirmation
active product/refill eligibility looks incorrect

Include these details when escalating:

patient name/email
original order number
refill order number
refill product name
refill invoice status
payment status/gateway error
current refill order status
Beluga submit status/error, if any
whether patient sees the refill button