Coupon Management

Coupons allow healthcare providers to offer promotional discounts on services, products and packages, run campaigns, and manage sponsored/funded treatments. Mazecare's Coupon module integrates directly with active payment providers (such as Stripe Connect) to automatically synchronize discount codes and apply them during patient-facing online checkouts.

This guide walks you through accessing the coupon menu, creating and configuring coupons, understanding sync behavior, and how coupons are validated on the patient checkout portal.

Accessing the Coupons Menu

To manage coupons, navigate to the Operations dashboard:

1. Log in to the Mazecare OS provider dashboard.
2. In the left navigation sidebar, click on Operations (represented by the Factory icon or via URL /operations).
3. Click on the Coupons sub-module card (represented by the Ticket icon or via URL /operations/coupons).

Coupon Table

The Coupon Table acts as the central dashboard for all active and historical coupons in your clinic network.

The table displays the following key information for each coupon:

• Name: The internal descriptive name of the promotion (e.g., Summer Wellness Campaign 2026).
• Code: The exact alphanumeric text the patient enters at checkout (e.g., SUMMER26).
• Discount: The value and structure of the discount (e.g., 15% Off or Fixed $20.00 USD).
• Redeemed Count: The number of times the coupon has been applied to successfully completed checkouts.
• Validity: The active date range of the promotion (Start Date to End Date).

From this table, you can:

• Use the search bar at the top-left to query coupons by Name or Code.
• Click New Coupon at the top-right to open the creation wizard.
• Click on any row to open the Coupon Details page, or select rows and click Delete to retire active coupons.

Creating a New Coupon

Click the New Coupon button to open the creation form modal.

!WARNING Restrictions: To maintain accounting integrity and prevent payment reconciliation issues, most fields cannot be changed once the coupon has been saved.

Explanation of Fields

The Two-Step Synchronization Wizard

Upon clicking Confirm, the system runs an automated setup wizard:

1. Creating Coupon: Saves the coupon data securely in the Mazecare database.
2. Syncing to Payment Providers: Mazecare queries all active payment integrations (e.g., Stripe Connect) and registers the coupon details directly on their platforms. This ensures checkout sessions generated via payment links or web widgets recognize the discount code.
3. Success Checklist: Displays a checklist showing which providers have synced successfully. If any sync fails, it alerts the administrator to resolve configuration conflicts.

Coupon Details View

Clicking a coupon row in the table opens the comprehensive detail view. Here, clinic administrators can manage the lifecycle, assign funding, and verify integration sync health.

Editable vs. Read-Only Fields

To prevent downstream billing discrepancies:

• Editable: Name, Description, Funded By can be modified.
• Read-Only: Coupon Code, Discount Type, and Discount Amount/Percentage remain locked.

Funding Entity Association

The Funded By field allows linking the coupon to a specific Doctor or Branch entity in the clinic network. This designates which balance sheet absorbs the promotional cost, which is crucial for accounting logs, reporting modules, and revenue split workflows.

Payment Provider Sync Panel

At the bottom of the details page, the Payment Provider Sync Status panel displays the synchronization state with external payment gateways (e.g., Stripe Connect):

• Lists all connected accounts, their sync status (e.g., SYNCED, FAILED, PENDING), and the external gateway Coupon ID.
• If a sync failed due to network issues or API restrictions, it displays a detailed error message and provides a Retry button.
• If the coupon expiration date has passed, a warning banner is shown, and sync buttons are deactivated since expired coupons cannot be updated on the gateways.

Patient Checkout Integration

During checkout on the patient booking app, coupons are validated on-the-fly when applied.

Coupon Validation Rules

The patient portal applies the following rules in sequence before recalculating the cart total:

1. Existence: The code must match an existing coupon registered under the clinic's tenant.
2. Active Status: The coupon must not be soft-deleted or marked as inactive.
3. Date Validity: The current time (UTC) must fall within the coupon's start and end date window (if configured).
4. Redemption Limits: The coupon's current redeemedCount must be strictly less than its maxRedemptionCount.
5. Gateway Verification: The coupon must have a status of SYNCED on the payment provider configured for the checkout channel. Unsynchronized coupons are blocked.
6. Item Applicability: If the coupon lists specific applicableItemIds, the patient's selected service offering must match one of those IDs. Otherwise, a "not applicable to this service" error is thrown.
7. Currency Alignment: For fixed discount coupons, the coupon must contain a discount amount defined in the currency matching the checkout order (e.g., a HKD checkout cannot accept a coupon configured only with USD amount).