🎁 wholesale

Schemes & Deals

Schemes & Deals is where you define promotional trade incentives for wholesale buyers — free-goods offers, order-value discounts and flat discounts — optionally restricted to a customer tier and a validity window. The page itself only manages the scheme definitions; nothing in the wholesale app currently calls the evaluation API automatically at order time.

📍 Menu path: Wholesale → Schemes & Deals

👤 Who uses it: All roles with the Billing feature enabled

Overview

Every scheme has one of three types: BUY_X_GET_Y (buy a minimum quantity of a trigger product, get a free quantity of another product), VOLUME_DISCOUNT (order total at or above a minimum value gets a percentage off), or FLAT_DISCOUNT (a flat percentage off, with no trigger condition).

A scheme can optionally be limited to one customer tier (STANDARD, RETAILER, DISTRIBUTOR, VIP) — leaving it blank applies the scheme to all tiers.

Valid From / Valid Until dates are optional; leaving either blank means the scheme has no start or no end boundary (shown as "∞" on the card).

Each scheme card has an Active/Off toggle that flips isActive without opening the edit modal — inactive schemes stay in the list (dimmed) rather than being deleted.

Product matching for BUY_X_GET_Y is by free-text product name typed into the form, not a product picker — there is no validation that the name matches an actual catalogue product.

Before You Start

You must have the Billing feature enabled on your plan.

Step-by-Step Guide

1 Create a Buy-X-Get-Y scheme

Open Wholesale → Schemes & Deals and click "New Scheme".
Enter a Scheme Name, leave Scheme Type as "BUY X GET Y".
Fill in Buy Product (trigger) and Min Quantity, then Free Product and Free Quantity.
Optionally restrict to a Customer Tier and set Valid From / Valid Until dates.
Click "Create".

💡 The trigger and free product fields are plain text — type the product name exactly as it should be matched later by the evaluate API.

2 Create a volume-discount or flat-discount scheme

Click "New Scheme" and change Scheme Type to "VOLUME DISCOUNT" or "FLAT DISCOUNT".
For Volume Discount, set Min Order Value and Discount %; for Flat Discount, set only Discount %.
Save the scheme.

3 Toggle a scheme on or off without deleting it

Click the "Active"/"Off" pill on the scheme card to flip it — no confirmation is needed.
An inactive scheme is shown dimmed with an "INACTIVE" tag but remains editable.

4 Edit or delete a scheme

Click the pencil icon on a scheme card to reopen the form pre-filled with its values.
Click the trash icon and confirm to permanently delete a scheme.

Every Field & Button, Explained

Field / Button	What it does
`Scheme Name`	Required. Free-text label shown on the scheme card, e.g. "Buy 10 get 1 free".
`Scheme Type`	BUY_X_GET_Y, VOLUME_DISCOUNT or FLAT_DISCOUNT — changes which of the fields below appear in the form.
`Buy Product (trigger) / Min Quantity`	BUY_X_GET_Y only. The product name and minimum quantity that must appear in an order to trigger the free goods.
`Free Product / Free Quantity`	BUY_X_GET_Y only. What is given free, and how much, per one occurrence of the trigger threshold being met.
`Min Order Value (₹)`	VOLUME_DISCOUNT only. The order subtotal threshold that unlocks the discount.
`Discount %`	Used by both VOLUME_DISCOUNT and FLAT_DISCOUNT — the percentage discount applied when the scheme matches.
`Customer Tier`	Optional. Restricts the scheme to one tier (STANDARD/RETAILER/DISTRIBUTOR/VIP); leave as "All Tiers" to apply to everyone.
`Valid From / Valid Until`	Optional date range. A blank Valid From or Valid Until means no lower/upper bound.
`Notes`	Optional free-text notes shown under the scheme summary line.
`Active toggle`	Pill button on each card; flips isActive between 1 and 0 without opening the edit form.

Tips & Best Practices

Because product names are free text, keep the spelling in Buy Product / Free Product identical to how you expect them to be matched — the evaluate API does a case-insensitive trim-and-compare, not a fuzzy match.
Use the Customer Tier filter to keep DISTRIBUTOR- or VIP-only schemes from showing up as available to STANDARD walk-in trade accounts.
Deactivating a scheme (rather than deleting it) preserves its configuration in case you want to re-run the same promotion next season.

Troubleshooting & FAQ

I set up a scheme but it never applies a discount or free item to an order.

This page only stores scheme definitions. The evaluation logic lives in a separate API, POST /wholesale/schemes/evaluate (evaluateSchemes in packages/pos-core/src/wholesale.js), which is not called by any order-entry or billing screen in the current build. Nothing in the wholesale app automatically checks an order against active schemes — benefits must currently be applied manually by staff, or the endpoint called directly by integrators.

A BUY_X_GET_Y scheme is not matching even though the customer bought enough of the trigger product.

Matching is done by exact (trimmed, case-insensitive) product-name string comparison between the scheme's Buy Product field and the order item's productName. If the product name in the order differs even slightly from what you typed when creating the scheme (extra spaces, a different SKU description), it will not match.

Can a scheme apply to only part of an order or stack with other schemes?

The evaluate function returns every matching scheme as a separate benefit in a flat list — there is no stacking logic, priority order, or exclusivity rule between schemes; each active scheme is evaluated independently.

I deleted a scheme by mistake.

Deletion is immediate and permanent after the confirm prompt — there is no undo, and no scheme-usage history is kept once a scheme is removed.

Does turning a scheme "Off" affect past orders?

No — schemes have no link back to WholesaleOrder rows. Activating/deactivating only changes whether the scheme would be returned by a future evaluate call; it has no effect on already-placed orders.