Advanced coupon rules without replacing WooCommerce.

WHY ONE SOURCE OF TRUTH

A coupon should not become two different objects depending on which screen is looking at it.

WooCommerce already owns coupon codes, amounts, usage limits, expiry, product restrictions, customer-facing descriptions and the final discount calculation. Duplicating those fields inside PerkRule would create synchronization problems: an edit in WooCommerce could disagree with an edit in the promotion plugin, third-party integrations could see different state, and uninstalling the plugin could leave the store with a second half-authoritative coupon model. PerkRule therefore extends the native coupon instead of replacing it.

WHAT PERKRULE ADDS

Only promotion concepts that WooCommerce does not already own are stored by PerkRule.

PerkRule metadata describes things such as application mode, advanced rule definitions, priority, stacking behavior, scheduling that goes beyond native expiry, and campaign configuration. Native description, enabled state and expiration deliberately stay native. That boundary is less glamorous than inventing a brand-new promotion entity, but it keeps the product compatible with the WooCommerce ecosystem and makes the failure mode much easier to reason about.

No parallel coupon database

Coupon data remains where WooCommerce and the wider ecosystem already expect it.

Advanced conditions around the coupon

Cart, customer, location, payment and shipping facts can decide when a native coupon is available.

WooCommerce still calculates the discount

PerkRule plans eligibility and conflicts without replacing native discount math.

CONFIGURATION ≠ OWNERSHIP

Marking a coupon Auto Apply does not give PerkRule permanent control over that coupon in the cart.

Auto Apply is only a policy saying that an eligible native coupon may be added automatically. Ownership begins only after PerkRule successfully performs that automatic mutation. If a customer manually applies the same coupon later, or an owned coupon is removed and subsequently re-applied by hand, the runtime must not confuse configuration with ownership and remove the customer's action on a later reconciliation pass.

MINIMAL MUTATION

Eligibility is decided first; WooCommerce receives only the final apply/remove difference.

PerkRule does not repeatedly throw coupons at the live cart to see what sticks. It discovers a bounded candidate set, validates rules, resolves conflicts and then compares the desired managed set with the current cart. Obsolete coupons that PerkRule explicitly owns can be removed, selected absent coupons can be applied, and everything else is left alone. The actual mutation still goes through WooCommerce public coupon APIs so native validation gets the final say.

PLAN BEFORE MUTATION

The resolver answers 'what should win?' before the cart is changed.

Once several promotions are eligible, applying them in discovery order would make results depend on incidental query order, hook timing or whatever happened to be in the cart first. PerkRule instead produces a deterministic selection plan using explicit priority and stacking policy. Equal priority has a stable tie-breaker, exclusivity is treated as a hard constraint, and compatible lower-priority promotions can remain selected rather than being discarded merely because a higher-priority coupon exists.

BEST DEAL IS BOUNDED

Best Deal is a winner inside an explicit group, not an exponential search through every coupon combination.

Trying every possible subset of promotions becomes computationally absurd very quickly. PerkRule limits Best Deal to bounded mutually exclusive groups and scores only the contested candidates that actually need comparison. Scoring uses WooCommerce totals behavior on an isolated cart clone, not speculative apply/remove calls on the shopper's live cart. If scoring cannot be completed safely, reconciliation stops before mutation rather than guessing a winner.

SERVER AUTHORITY

Classic checkout, Blocks and headless clients should ask the same promotion engine the same question.

Promotion eligibility belongs on the server because the server owns the cart and ultimately accepts the order. A separate browser-side rules engine would create multiple versions of truth: one for classic templates, another for Blocks, another for Store API consumers, and potentially another for a custom headless frontend. PerkRule keeps rule evaluation and coupon validation in the WooCommerce server lifecycle so presentation layers can adapt without reimplementing business rules.

COMPATIBILITY BOUNDARY

Presentation adapters may differ; promotion meaning must not.

Blocks, builders and headless storefronts can require different UI integration, notices or refresh behavior, but those adapters should not decide whether a coupon is valid. The architecture reserves separate integration boundaries while keeping the core framework-independent and server-authoritative. That makes compatibility work narrower: a new frontend surface should need an adapter around the same promotion decisions, not a second promotion engine that slowly drifts away from the first.