Packages: lifecycle, redemption and refunds

Define service packages, sell them to patients, redeem sessions at booking, and understand package statuses, expiry and refunds.

A package bundles a number of sessions of one or more services for a single price, for example "6 physiotherapy sessions" or "Annual health check: 1 consultation, 1 blood panel, 1 ECG". Patients pay once and use the sessions over a validity period. This page covers how administrators define packages, how front-desk staff sell and redeem them, and what happens when a package ends.

LeapHealthOS has no subscription or recurring-billing feature. A package is always a one-time purchase.

Before you begin

The Add package dialog shows the form your implementation team has published for the Service Catalog — Add / Edit Package placement. Until a form is published, the dialog shows "No Add package form is configured". See Clinical forms and placements.
Package types (for example "Physiotherapy" or "Wellness") come from Package Types in the Tenant Registry. They are labels for grouping and filtering; they do not change how a package behaves. See Tenant registry and vocabularies.
To sell packages from the Create Payment screen, your tenant needs an active package bill type in the Tenant Registry. See Bills, bill types and line items.

The Packages screen

Open SettingsPlatform ConfigurationPackages. The table shows:

Column	What it shows
Name	Package name.
Type	Package type.
Price	The selling price in rupees.
Composition	The number of included services and the total sessions, for example "3 items · 8 sessions".
Centres	The centres where the package can be bought and used.
Active patients	How many patients hold this package with status Active.
Status	Active or Inactive.

Use Search package name… and the Type filter (All types or one type) to narrow the list. Select Load more at the bottom to see more packages.

Creating a package

Open the dialog

Administrator

Settings > Platform Configuration > Packages

Select Add package.

Describe the package

Enter the package name, package type, description and price.

Set validity and sessions

Enter Validity (days) and Total sessions, then add one row per included service with the number of sessions for that service.

Choose centres

Add at least one centre. The package can be bought and redeemed only at these centres.

Save

Select Create package.

Expected result: "Package created" appears and the package is listed as Active.

Package fields

Field	Required	What it does
Package name	Yes	Shown in the package picker, booking and the bill.
Package type	Yes	Must be an active package type once your tenant has any.
Description	No	Free text.
Price (₹)	Yes	The selling price.
Validity (days)	No	Days the package stays usable, counted from the moment it is first paid for. Leave empty for no expiry.
Total sessions	No	A cap on sessions across all included services.
Centres	Yes	At least one centre. There is no "all centres" option; list each centre.
Included services	Yes	One row per service with Sessions (at least 1). Each service has its own session quota.
Shareable with family / Max family members	No	Saved, but family sharing does not work yet. See the limitation below.
Active (edit only)	No	Shown when editing.

Both limits apply: a booking can redeem a session only if the package has sessions left overall and that service still has sessions left in its own quota.

Check your first package

After you create or edit a package, check that the Price column shows the amount you expect. If it does not, ask your implementation team to review your published form.

Family sharing is not available

Shareable with family and Max family members are saved, and the package picker may label a package "family shareable", but no purchase links family members to the package and the member limit is never checked. Treat every package as usable only by the patient who bought it.

Editing and deactivating a package

Select the edit icon on a row to change a package, then Save changes. Selecting the deactivate icon asks for confirmation.

Changes apply to patients who already hold the package, not only to new buyers:

Changing the included services changes what existing holders can redeem.
Deactivating a package stops it being sold and stops existing holders from redeeming it. The confirmation says "Patients already holding it keep their purchase-time snapshot", but in practice their sessions cannot be used while the package is inactive. Reactivate it to let them redeem again.
Changing the centre list replaces the whole list.

Selling a package

Packages are sold from the Create Payment screen. See Creating a payment and collecting money for the full flow.

Start a payment for the patient

Front desk

Quick Create > New Payment

Enter the patient's mobile number, pick the patient and the centre.

Choose the Package bill type

Under Bill Types, select the package bill type. A package picker replaces the item list.

Pick the package

Search with Search packages… and select a package. Only active packages valid at the selected centre are shown. A bill can hold one package.

Collect payment

Select Collect Payment and record the payment.

Expected result: The package bill is issued. The package becomes Active as soon as any amount is paid.

When a doctor advises a package during a consultation, a task to bill it can open this screen with the package already selected. See Where tasks come from.

Rules LeapHealthOS checks when a package is billed:

The package must be active and valid at the bill's centre.
A patient cannot have two unpaid purchases of the same package at once.
The package line cannot be priced above the package's catalog price.

When the package starts

The patient's package starts at the moment the first payment is recorded, even a part payment. Validity is counted from that moment. A start date in the future is not possible.

If the package bill is cancelled before any payment, the pending package is cancelled with it.

Package statuses

Patient package statuses

From → To	Trigger	Actor	Condition	Side effects
Pending paymentActive	First payment recorded on the package bill	Front desk	Any amount paid	Validity starts now
Pending paymentCancelled	Package bill cancelled	System	Bill is unpaid
ActiveExhausted	Last session redeemed	System	Remaining sessions reach 0
ExhaustedActive	A redeemed session is returned	System	Appointment cancelled or no-show returned	Session count restored
ActiveExpired	Validity ends	System	Validity and grace days have passed	Optional refund of unused value
ActiveManually completed	Complete package	Staff (no screen yet)	A completion reason is given
ActiveCancelled	Cancel package	Staff (no screen yet)	A cancellation reason is given	Refund raised per policy

Pending paymentinitial: The package has been billed but nothing has been paid yet. It cannot be redeemed.
Active: Paid (fully or in part) and within validity. Sessions can be redeemed.
Exhausted: No sessions left. Becomes Active again if a session is returned.
Expiredterminal: The validity period ended (plus any grace days) while the package was Active.
Manually completedterminal: Closed early by staff with a reason. No refund.
Cancelledterminal: Cancelled by staff, or because its bill was cancelled. A refund may be raised.

Redeeming a session at booking

When you book a service for a patient who holds an applicable package, the Confirm & Pay step of the booking wizard shows REDEEM PACKAGE. A package is applicable when it is Active, not past its expiry date, has sessions left overall and for this service, is valid at the booking centre, and the package itself is still active.

Pick the package to use. The note reads "One session will be redeemed from this package. The booking fails if the package cannot cover this service." The visit is priced at ₹0 and discount is turned off. The summary shows Covered by the package name.
Each booking redeems one session.

Pay for this visit still redeems a package

Choosing Pay for this visit does not keep the patient's package untouched today. If the patient holds a package that covers the service, a session is still used from the package that expires soonest, and the visit is priced at ₹0. If a patient wants to pay for a visit instead of using their package, speak to your implementation team before booking.

Reserved and used sessions

A redeemed session is first reserved: it is taken off the remaining count straight away. It becomes used when the appointment is completed.

When a session comes back

Staff cannot return a session by hand. Sessions come back automatically:

What happens to the appointment	What happens to the session
Completed	Used. It does not come back.
Cancelled	Returned to the package. An Exhausted package becomes Active again.
No-show	Depends on a no-show setting with no screen yet, set by your implementation team: forfeit (the default) keeps it used; return gives it back. See Check-in, late arrival and no-show.

Completing, cancelling and expiring a package

No screen for completing or cancelling

Completing or cancelling a patient's package has no screen in LeapHealthOS yet, and there is no staff screen to view a patient's packages and session history. Ask your implementation team to complete or cancel a package.

Complete: closes an Active package early with a reason. No money is returned.
Cancel: closes an Active package with a reason and works out a refund using your package policy:
- Prorate unused (default): a full refund if no session was used; otherwise price × sessions left ÷ total sessions.
- Full if unused: a full refund only if no session was used.
- None: no refund.
Expire: Active packages past their validity are marked Expired automatically. Your notification rules can tell the patient when this happens. With grace days, the status change waits that many days, but the package cannot be redeemed after its expiry date. By default nothing is refunded on expiry; your policy can instead refund the unused value pro rata.

Any refund is capped at what the patient actually paid for the package. It is recorded on the package bill as a refund adjustment that waits for approval. See Adjustments, refunds and deposits.

The package policy (cancel refund rule, expiry refund rule and grace days) can differ per centre, but has no screen in System Settings yet; your implementation team sets it. See Billing and package settings reference.

Who can do what

Task	Who
Create, edit, activate or deactivate package definitions	Administrators, from the Packages screen in Settings.
Sell a package (create the bill and collect payment)	Staff who can create payments on the Payment screen.

packagessessionsredemptionrefundsexpiryfront desk