Subscription Entitlement and Billing Reconciliation for AFH Software

Subscription billing in adult family home software should keep public pricing, admin configuration, checkout, invoices, and in-app access synchronized without blocking resident care because a webhook arrived late. Billing state and product entitlement are related but separate records that must reconcile visibly.

This guide covers software and business operations, not tax, accounting, payment, or legal advice. It was reviewed on August 8, 2026. Operators should define pricing authority, contracts, grace periods, refunds, data access, and continuity policy for the service.

Store pricing as managed configuration

Create versioned pricing records containing:

• Plan and display name
• Price and currency
• Billing interval
• Effective start and optional end
• Free or paid status
• Included facilities, users, or capabilities
• Trial and grace rules
• Payment-provider price reference
• Public visibility
• Approver and change reason

Do not hardcode the amount independently on the landing page, settings page, and checkout. They should read the same published version.

Future pricing can be staged without changing existing subscriptions until its effective rule applies.

Synchronize public pricing and billing access

When platform billing access is disabled and the service is free, the landing page should say Free and hide paid checkout language. When billing is enabled, display the admin-configured amount and interval.

The facility Subscription tab should show the same plan version, price, status, and next action. Avoid stale cached marketing content after an admin change.

Record the pricing version used when a user begins checkout so later changes do not alter an in-flight agreement silently.

Separate subscription state from entitlements

Model payment-provider subscription status and application entitlement independently:

• Subscription: trialing, active, past due, paused, canceled, incomplete, or ended
• Entitlement: permitted capabilities, facility count, role limits, and effective interval

Map provider states to entitlement through versioned policy. Do not scatter checks such as status === active across pages.

Resident record access and export rights also depend on facility roles, not only payment.

Preserve care continuity

Define what happens when payment fails, the subscription is canceled, or billing integration is unavailable. Avoid abruptly blocking caregivers from medication and resident records needed for current care.

Possible stages include notice, grace period, restricted administrative changes, read-only archive access, export availability, and final closure according to policy and contract.

Never delete resident records because a payment is late. Retention, confidentiality, and authorized access continue under their governing rules.

Make checkout idempotent

Give each checkout attempt a stable request ID. Repeated clicks or network retries should return the existing checkout session rather than create multiple subscriptions.

Bind it to facility owner, tenant, pricing version, plan, and intended action. Reject reuse with changed payload.

The API idempotency guide explains fingerprints, atomic reservation, and durable receipts; the same engineering pattern applies outside medication.

Do not trust a browser success redirect as proof of payment. Verify provider state on the server.

Verify billing webhooks

Validate signature, timestamp, account, event ID, and payload before processing. Deduplicate events and preserve the provider event ledger.

Apply a state machine so late or repeated events do not move a subscription backward incorrectly. Separate transport acknowledgement from completed entitlement processing.

If an event references an unknown tenant or customer mapping, quarantine it for reconciliation. Never guess the facility from payer email alone.

Map customers and facilities explicitly

Store provider customer, subscription, invoice, and price references under the platform tenant. One owner may manage several facilities under one portfolio or separate subscriptions; make the model explicit.

Do not give Facility Beta entitlement because its owner paid for Alpha unless the configured plan covers the portfolio.

Transfers, ownership changes, and merged accounts need controlled mapping changes with audit and effective dates.

Handle free-to-paid transitions

When the platform changes from free to paid:

• Publish the effective pricing version
• Notify facility owners
• Explain included capabilities and date
• Provide checkout or acknowledgment workflow
• Define existing-facility treatment
• Test landing, settings, admin, and email consistency
• Preserve care access through the transition policy

Do not flip a global boolean that immediately locks active caregivers. Pricing policy, entitlement policy, and communication must move together.

Handle paid-to-free transitions

When returning to free access, stop new paid checkout, update public and in-app pricing, and define cancellation, proration, credit, or end-of-period behavior with the payment provider.

Do not show “Free” publicly while existing customers continue being billed without clear treatment. Reconcile every active subscription and notify affected owners.

Keep invoice and payment history even when current entitlement no longer requires payment.

Support trials, grace, and coupons carefully

Store trial and discount terms with source, eligibility, start, end, and provider reference. Calculate display and checkout from the same rule.

A coupon should change price, not facility role authorization. A trial ending should create notices and entitlement transitions according to policy without deleting data.

Prevent repeated trial creation through new checkout sessions for the same tenant when policy does not allow it.

Make the facility subscription page clear

Use tabs or sections for:

• Current plan and price
• Entitlements
• Billing status and next date
• Payment method through secure provider UI
• Invoices and receipts
• Facility coverage
• Grace or action required
• Cancellation and data-access consequences

Avoid cluttered cards and ambiguous “active” labels. State whether active refers to payment, entitlement, or both.

Do not expose another facility's invoices to a manager without portfolio billing permission.

Design admin pricing controls

Administrators should preview landing-page wording, settings display, checkout price, existing subscriber effect, and effective date before publishing.

Require strong authentication and audit old and new values, approver, reason, schedule, and rollback. A draft price is not public.

Prevent deletion of a price version referenced by a subscription or invoice. Mark it retired for new sales while preserving historical display.

Reconcile provider and application state

Run regular comparisons for:

• Active provider subscriptions without tenant mapping
• Entitled tenants without expected subscription
• Plan or price mismatch
• Duplicate subscriptions
• Past-due status without applied policy
• Canceled subscription still granting paid capability
• Free-platform mode with active charges
• Paid-platform mode with stale public “Free” content
• Webhook events stuck before processing
• Invoices absent from the facility view

Assign owner and priority. Do not let the dashboard show zero exceptions because the webhook queue stopped.

Protect billing information

Use payment-provider hosted fields or pages so the application does not handle raw card data unnecessarily. Restrict billing roles and require step-up for sensitive changes.

Keep resident data out of payment metadata, invoice descriptions, webhook logs, and billing support tickets. Tenant and facility references should be opaque.

Audit checkout, plan changes, cancellation, refunds or credits, invoice downloads, pricing publication, and support overrides.

Test pricing and entitlement cases

Treat provider events as untrusted, repeatable input

Stripe's webhook documentation explains that integrations should verify signatures, handle duplicate events, process asynchronously, and not depend on event ordering. The same safeguards apply when another billing provider is used. Store the provider event ID and relevant object version before changing an AFH entitlement, acknowledge valid deliveries promptly, and let an idempotent worker calculate the resulting subscription state. Never grant a facility plan from a browser success page or an unsigned request.

Reconciliation must remain independent of webhooks. On a schedule, compare provider customers, subscriptions, invoices, cancellations, and covered facility identifiers with the application's pricing version and entitlement ledger. Route mismatches to an operations queue with the current evidence and a safe proposed action. A missing event should not silently leave premium access forever, and an out-of-order cancellation should not erase a newer renewal. Keep medication records, MAR history, exports required for continuity, and facility ownership data separate from commercial feature switches so that a billing correction never corrupts care documentation.

Use a payment test environment and synthetic facilities:

1. Free mode on landing and settings.
2. Admin publishes a paid price.
3. Checkout double-click creates one session.
4. Success redirect arrives before webhook.
5. Webhook repeats and arrives out of order.
6. Payment fails and grace starts.
7. Grace expires under continuity policy.
8. Subscription cancels at period end.
9. Owner manages two facilities under one plan.
10. Wrong facility mapping is denied.
11. Price changes for new customers only.
12. Paid platform returns to free.
13. Active charges are found during free reconciliation.
14. Role removal blocks invoice access.
15. Billing provider outage preserves current safe state.
16. Landing, checkout, invoice, and settings display match.

Inspect provider records, application entitlements, public pages, notifications, invoices, and audit events.

Frequently asked questions

Should the subscription amount be hardcoded?

No. Store versioned admin-managed pricing and use the published version across landing, settings, and checkout.

Does a successful checkout redirect grant access?

No. Verify server-side provider state and process it through the entitlement policy.

Should failed payment block medication access immediately?

Define a care-continuity and contract policy with notice and grace. Do not delete records or create unsafe abrupt loss of current-care access.

Can one owner pay for several facilities?

Yes when the plan explicitly supports it. Map every covered facility and validate portfolio billing permissions.

What happens when pricing switches back to free?

Update public and in-app configuration, stop paid checkout, reconcile active charges, apply cancellation or credit policy, and notify customers.

Keep price, payment, and access synchronized

Reliable billing uses versioned pricing, shared public configuration, idempotent checkout, verified webhooks, explicit facility mapping, continuity policy, clear entitlements, and independent reconciliation.

Explore AFH Manager to test free and paid modes, admin pricing, checkout, multi-facility coverage, grace, cancellation, invoice access, and entitlement reconciliation with test subscriptions.