Subscription billing

What this area controls

Subscription billing is where an owner or staff member with subscription billing permission reviews the lab's active plan, compares available packages, manages saved renewal cards, and downloads subscription invoices. It is different from the cashier finance pages. Cashier pages handle patient and order money. Subscription billing handles the lab's own SaaS plan and the payment methods used to keep the workspace active.

Use this area when the lab needs to upgrade, downgrade, confirm what a plan includes, check when the next renewal will happen, or download an invoice for accounting. Because plan access can affect modules such as inventory, automation, website builder, lab-to-lab work, permissions, and AI assistance, review plan changes with the people who run those workflows before switching packages.

Plan cards and feature lists

The Subscription Management page shows the available plans in equal-height cards so owners can compare them without one long plan pushing the layout out of balance. Each card shows the plan name, badge, monthly price, yearly price, description, a short preview of included features, and the action label. The current plan is marked clearly. A selected plan is highlighted before you confirm the change.

Use the monthly/yearly selector above the plan cards before choosing a plan. Monthly billing renews each month. Yearly billing uses the yearly plan amount and renews for a full year after the first aligned renewal. If you came from the public pricing page, the selected billing cycle is carried into registration so the first subscription record starts with the intended interval.

Plans may include many features, so each card only shows a short preview. Use Show full feature list to open the complete list for that plan. This is the safest way to compare plans because a plan may include features that are not visible in the preview, especially the higher tiers. Read the full list before training staff on a new module or promising a feature to a branch manager.

After selecting a different plan, use Review selected change. This first action never changes the subscription. It prepares a mandatory review with the current and new terms, exact amount due now, new recurring amount, unused-period credit, credit applied now or carried forward, effective time, removed and added modules, every changed quota, current measured usage, retained-data behavior, grace period, and rollback terms.

Read the review with the people who own the affected workflows. A red quota row means current measured usage is already above the new limit. Existing records remain retained, but new usage in that quota is blocked after the downgrade. Select the review acknowledgment only after checking every section, then use Confirm reviewed plan change. Reviews expire after 15 minutes and are invalidated if the subscription, pricing, plan entitlements, quota configuration, or measured usage changes. The reviewed amounts and terms are authenticated and checked again inside the final transaction, so the system cannot silently apply terms that differ from the review. If payment is required, Kashef keeps the current plan active and sends you to checkout; access changes only after payment succeeds. A checkout for a plan change that has since been cancelled or superseded is rejected and must be prepared again from Subscription Management.

Only staff with Subscription Billing: Manage permission can change the plan, billing interval, renewal default, or cancellation schedule. Staff with view permission can inspect the current subscription, cards, quotas, and invoices without changing billing state.

Billing driver and simulator safety

The local and automated-test environments use a clearly labelled payment simulator. The simulator accepts only the approval and decline numbers shown on the checkout page. It does not contact a payment provider and does not charge real money. Never enter a real card number in simulator mode.

Production defaults to disabled subscription checkout until a real payment driver is implemented and configured. When billing is disabled, Kashef rejects paid checkout and paid plan changes instead of recording a fake success. Scheduled renewals also stop without creating fabricated successful payments. This is a release safety control, not a payment-provider integration.

Proration, credits, and plan changes

Kashef calculates plan changes against the current paid period. A new paid subscription that starts during the month is charged only for the days left until the first day of the next billing period. After that aligned date, normal monthly or yearly renewals take over.

Upgrades usually create a checkout payment for the remaining-period difference between the current plan and the selected plan. The existing plan stays active while checkout is pending, so staff do not lose access just because the owner opened an upgrade flow. When checkout succeeds, the new plan becomes active and the payment invoice records the billing scenario, billing interval, period start, period end, and any credit applied.

Downgrades or no-charge changes activate immediately after final confirmation and have no grace period. The review lists the exact modules and quota reductions before that happens. Changing a plan never deletes existing laboratory records: data in a restricted module stays retained, but the module becomes unavailable until the lab returns to an eligible plan. Over-quota records remain retained while new usage is blocked.

If the current plan has unused value, Kashef records that amount as credit on the new subscription. The review separates unused-period credit, credit applied to the current change, and credit carried forward. Renewal billing applies carried credit before charging the default card. If it fully covers the next renewal, the system can record a zero-amount successful renewal and keep any remaining credit. There is no one-click rollback; an authorized billing manager can select the previous plan again, and Kashef recalculates pricing and credit at that time.

Changing from monthly to yearly is handled as an interval change. During the current paid period, Kashef calculates the amount due or credit using the remaining days. The next aligned renewal then uses the yearly amount and extends the subscription for a yearly period.

Current subscription and next payment

The current subscription snapshot summarizes the active plan, description, amount, and status. The billing period card shows when the subscription started, when it renews, and the latest payment reference. The next payment card shows the expected amount, currency, due date, billing interval, and status.

The displayed status is lifecycle-aware rather than a copy of the stored provider state. If an Active record has passed its paid-period end, the page shows Renewal processing instead of stale Active, explains the temporary processing window, and shows the last renewal attempt, attempt status/reference, billing provider, and next automatic retry. A failed attempt appears as Past Due and tells the billing owner to update the default payment method. A period-end cancellation waiting for the worker appears as Cancellation processing.

Owners should review the next payment card before changing plans, changing billing interval, or cancelling. It gives accounting staff a quick answer to the most common renewal questions: how much will be charged, when it is expected, and whether the subscription is active, incomplete, cancelled, or waiting for checkout.

If the subscription is not active yet, the due date may show that payment is expected after activation. That usually means checkout has not been completed or the lab is moving between plans. Complete checkout or review the latest subscription payment before assuming the plan is fully active.

Renewal processing

Kashef scans for due subscription renewals every day at 00:05. The application scheduler is configured with this daily cadence, not a first-of-month scan. This daily catch-up prevents one missed scheduler window from leaving subscriptions stale for an entire month. Each subscription is processed separately, which keeps a failure in one lab from blocking other labs. When an enabled billing driver is available, the worker looks for the default saved payment method, creates a subscription payment record, and advances the billing period after a successful renewal. When billing is disabled, the worker does not fabricate a payment or advance the billing period.

An on-time renewal keeps the existing billing anchor. If a subscription is so overdue that advancing one normal period would still leave it expired, one successful catch-up payment starts a new future billing period from the recovery time. The invoice metadata records the previous period end and identifies the payment as a catch-up renewal, avoiding repeated charges for historical months after scheduler downtime.

If no default saved card exists and the subscription has an amount due, the worker records a failed payment and marks the subscription as past due. Past-due status tells owners and billing staff that the workspace needs attention before the next renewal attempt. Add or mark a default payment method, then retry the renewal through the normal billing process.

If the subscription has credit from a downgrade or interval change, the renewal applies that credit before charging the card. The payment metadata keeps the billing scenario and period details so downloaded invoices remain understandable later.

Saved payment methods

Saved payment methods are provider-created card references used for subscription renewals. Kashef stores display metadata such as cardholder name, brand, last four digits, expiry month, expiry year, default flag, and an internal provider reference. Full card numbers and CVC values are entered only during checkout and are not stored in the saved payment method page. Provider reference values are not shown to lab staff.

The Subscription Management page shows a quick saved-card summary. Use Manage payment methods to open the full payment methods page. Saved cards cannot be created or edited manually because a valid provider reference must come from an approved checkout. From the list, authorized staff can mark a card as default for renewals or remove a card that should no longer be used. Only one method is default at a time. When a new default is selected, the previous default is cleared transactionally.

Use the default card for the card your accounting team expects to be charged during renewal. If a card expires or its details change, complete checkout with the replacement card and save it; do not edit stored card metadata. Removing a default card automatically promotes the most recently used remaining card. If no card remains, the next paid renewal cannot proceed.

Subscription payments

Subscription Payments lists payment records, including the payment reference, plan, status, amount, masked card metadata, paid date, and creation date. Successful payments, failed attempts, pending records, and refunds can all appear depending on the payment flow. This list is scoped to the current lab company, so one tenant cannot see another tenant's subscription payments.

For a successful payment, use Download paid invoice to download the accounting PDF. For pending, failed, or refunded records, use Download payment record to download an audit record that is explicitly marked as not being proof of payment. Both documents include lab identity, branch context, payment reference, recorded date, localized payment status and plan, billing period, paid date, amount, provider, and masked card details. They never expose the provider payment-method token.

If a payment was created but the subscription did not activate, check the payment status first. A failed payment is useful evidence, but it is not a paid invoice. Complete checkout again with an approved saved card or a new card before relying on the plan access.

Cancellation timing

Cancellation is scheduled to the end of the current paid period when the subscription is active. This protects the lab from losing access in the middle of a period it has already paid for. The subscription remains active until the period end date, then the daily renewal worker cancels it instead of charging the card.

If there is no active paid period, cancellation can happen immediately. Before scheduling cancellation, download any invoices your accountant needs and confirm whether the lab should keep access through the remaining paid days.

Practical operating checks

Before changing a plan, confirm which branches and teams depend on features that may be affected. Before cancelling, export or review any subscription invoices your accountant needs. Before the renewal date, confirm the default saved card, expiry, and next payment amount. After a successful payment, open Subscription Payments and download the paid invoice if your accounting process requires it.

When a staff member reports that a page disappeared after a plan change, check subscription status, selected plan, feature list, role permissions, branch assignment, and direct permission overrides. Subscription billing and permissions work together. A user needs both a plan that includes the feature and a role that grants access to the page.