WooCommerce coupon troubleshooting
When a coupon behaves strangely, find the layer that made the decision.
Promotion problems become easier to debug when native WooCommerce validity, PerkRule eligibility, automatic ownership and conflict resolution are treated as separate layers.
STEP 01
Check native WooCommerce validity first.
PerkRule does not override a coupon WooCommerce already considers invalid. Product restrictions, usage limits, expiry and native individual-use behavior remain authoritative.
START OUTSIDE PERKRULE
If WooCommerce says the coupon is invalid, PerkRule is intentionally not the first suspect.
Check the native coupon itself: publish status, expiration, minimum or maximum spend, product and category restrictions, usage limits, allowed emails, individual-use behavior and any native exclusions. PerkRule's validation integration receives WooCommerce's decision and returns immediately when native validity is already false. That design prevents an advanced rule match from accidentally turning a natively invalid coupon back into a valid one.
WHY ORDER MATTERS
Troubleshooting becomes much faster when you identify which layer owns the decision before changing configuration.
A common debugging mistake is to edit advanced rules when the actual problem is native expiry, or to change WooCommerce restrictions when the coupon is valid but loses later during PerkRule conflict resolution. Treat the system as layers. First prove native validity. Then prove PerkRule eligibility. Then, for automatic coupons, prove ownership/application state. Finally inspect selection policy. Each step narrows the problem instead of randomly toggling settings across several systems.
STEP 02
Then check PerkRule rule eligibility.
A coupon can be natively valid but unavailable because its PerkRule conditions do not match the current cart, customer, location, payment or shipping context.
ELIGIBILITY SNAPSHOT
A natively valid coupon can still fail because the current request facts do not satisfy its PerkRule rule tree.
Look at the facts the rule actually depends on: current subtotal and quantities, login state and roles, billing or shipping geography, selected payment and shipping methods, and other applied coupons. Some checkout facts do not exist until the shopper reaches a later step. PerkRule treats absent optional information as no-match rather than assuming a convenient value, so a promotion can legitimately be unavailable early and become eligible once the required fact exists.
INVALID IS NOT FALSE DATA
Malformed configuration and a legitimate no-match are different causes even though both safely prevent the promotion.
Unknown rules, invalid operators, malformed values, unsupported schemas or structurally invalid trees are safe failures. They should not be debugged by changing the customer's cart because the problem is the definition itself. The compiler and evaluator keep bounded diagnostic information for internal reasoning while the customer-facing validation message remains generic. Engineering diagnostics can therefore distinguish 'the rule evaluated and did not match' from 'the rule could not be trusted enough to evaluate'.
STEP 03
For Auto Apply, distinguish configuration from ownership.
A coupon configured for Auto Apply is not automatically owned by PerkRule. Ownership comes from a successful automatic mutation, which protects later manual customer actions.
CONFIGURED DOES NOT MEAN APPLIED
Auto Apply configuration only puts a coupon into the candidate policy; it does not prove PerkRule added the current cart entry.
A customer may manually enter a coupon whose metadata also says Auto Apply. That cart state must remain customer-owned. PerkRule records automatic ownership only after a successful automatic mutation. If an owned coupon is removed, ownership is cleared. So when diagnosing 'why didn't PerkRule remove this coupon?', first ask who actually applied the current instance rather than assuming the application-mode setting answers that question.
RECONCILIATION STATE
A coupon can be eligible and still remain absent because the desired automatic set changed after policy resolution.
Auto Apply does more than check one coupon in isolation. It discovers a bounded candidate set, validates candidates against the same current facts, protects existing manual state, applies priority and stacking policy, and only then computes a minimal mutation diff. A candidate that matched its own rules may still be excluded because another promotion is exclusive, belongs to the same conflict group, wins Best Deal, or conflicts with a protected individual-use coupon already in the cart.
STEP 04
Finally inspect conflict resolution.
An eligible automatic coupon can still lose to priority, exclusivity, a conflict group or Best Deal selection. Eligibility and selection are intentionally separate decisions.
ELIGIBLE ≠ SELECTED
Eligibility answers whether a promotion may participate; conflict resolution answers whether it survives beside the other eligible promotions.
Those are intentionally separate questions. A coupon can be natively valid and match every PerkRule condition yet still lose because another candidate has higher priority inside an incompatible relationship, because it is not the Best Deal winner, or because protected manual state prevents an automatic exclusive or individual-use promotion from entering the cart. Treating that as a rule failure sends debugging in the wrong direction.
READ THE PLAN
When several promotions interact, reconstruct the conflict set before touching individual rule definitions.
List the coupons that are eligible, note which ones are already applied manually, then inspect priority and stacking mode for the competing automatic candidates. For Best Deal, remember that comparison happens only inside the explicit group and uses native discount impact; it is not a global optimizer. If the selected set makes sense but the cart still differs afterward, the investigation has moved from policy into mutation or native WooCommerce application — a much smaller and more useful problem to isolate.
See the architecture behind these layers.
Engineering Notes explain why the product keeps validation, ownership and conflict planning separate.
Open EngineeringPerkRule support room
Real support works better when people can talk.
The PerkRule Discord will be the direct place for setup questions, bug reports, compatibility notes and release discussion. Useful answers should not disappear into private tickets — recurring problems can become documentation and Engineering Notes.
Discord opens around Product 001 release