=== Milardovich Extra Coupon Features ===
Contributors: milardovich
Tags: coupons, discounts, discount rules, auto apply, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A discount rules engine for WooCommerce that shows you exactly why every coupon did or did not apply.

== Description ==

Most coupon plugins let you build a rule and then leave you guessing when it does not fire. **Milardovich Extra Coupon Features** gives you a condition engine with real AND/OR logic, deterministic priority when several offers compete, and a trace for every decision it makes.

A full walkthrough of what it does, with screenshots, is at [milardovich.com.ar/extra-coupon-features](https://milardovich.com.ar/extra-coupon-features/).

= What it does =

* **Condition groups with AND/OR**, nestable, across cart, customer, purchase history, checkout context and time.
* **Auto-apply with explicit priority and exclusivity groups.** When two automatic coupons compete, the winner is the one you configured, and it is the same winner on every recalculation. No race conditions.
* **Coupon queueing.** A customer who enters a code before the cart qualifies keeps it; the coupon applies itself the moment the cart does qualify.
* **Percentage discounts with a maximum cap.** "20% off, up to $50", which is what a finance person actually signs off on.
* **URL coupons.** `?apply_coupon=SUMMER20`, comma separated for several codes, combinable with `add-to-cart`, and the parameters are stripped on redirect so nothing accumulates and nothing is added twice.
* **Rule trace.** Every condition reports what it expected, what it found and whether it passed. Never paywalled: observability is the reason to trust the plugin.
* **Rule tester.** Build a synthetic cart in the admin and watch every published coupon evaluate against it, before the promotion goes live.
* **Cart status for shop managers.** A per-coupon panel on the cart page, visible only to users who can manage WooCommerce, answering "why is my coupon not applying" in place.
* **Event log.** Applied, auto-applied, rejected, queued, silently removed and superseded, each with its reason and the cart signature that produced it.
* **Silent removal.** An automatic coupon that stops qualifying is removed without a scary error, and a coupon the customer removed by hand is not re-added behind their back.
* **Buy X Get Y**, across specific products, sets, categories or anything in the cart, repeating or once per order, with the reward free or discounted — and the reward quantity recomputed from the trigger every time, so it can never run away with your stock.
* **Tiered pricing**, fixed price per item, and limiting a discount to the cheapest items, the dearest, every nth or the nth onwards.
* **Store credit** on an append-only ledger: the balance is the sum of its history, never a number that gets edited. Partial redemption, expiry, adjustments that require a note, and refund-to-credit.
* **Gift cards** sold as products, with denominations or a customer-entered amount, a recipient, a message and scheduled delivery. A card keeps its remaining balance by default; tick **one use** when issuing it and it is spent in a single order instead.
* **Liability reporting**: outstanding balance, aging, issuance and redemption by month, breakage, and a CSV of the ledger for your accountant.
* **Bulk generation** from a template coupon, CSV import and export, and lifecycle campaigns for signup, first order, nth order, birthdays, win-backs and abandoned carts.
* **Reporting** per coupon and per campaign: redemptions, discount cost, revenue and average order value.
* **Anti-abuse** limits by IP, by email and inside a rolling window, plus blocked email domains — counted from paid orders, so a guest checkout with a fresh address does not get around them.
* **Migration** from Advanced Coupons and from Soft79's Extended Coupon Features, with a preview that tells you what it could not map before you commit.
* **Classic cart and Cart/Checkout Blocks.** The rules hang off the totals calculation both go through, and the Store API carries the offer data for Blocks.
* **HPOS compatible.**

= Documentation =

The feature tour, the condition catalogue and the developer API are documented at [milardovich.com.ar/extra-coupon-features](https://milardovich.com.ar/extra-coupon-features/).

= For developers =

Every condition and outcome is a registered type using the same public interface the built-ins use.

`
add_action( 'mecf_register_conditions', function ( $registry ) {
    $registry->register( 'crm_segment', [
        'label'    => __( 'CRM segment', 'my-plugin' ),
        'group'    => 'customer',
        'fields'   => [ 'segment' => [ 'type' => 'text', 'label' => 'Segment' ] ],
        'evaluate' => function ( $args, $context ) {
            $segment = my_crm_lookup( $context->get_customer_id() );
            return [
                'passed'   => $segment === $args['segment'],
                'expected' => $args['segment'],
                'actual'   => $segment,
            ];
        },
    ] );
} );
`

Filters: `mecf_can_apply_coupon` (veto an application), `mecf_resolve_conflicts` (override which competing coupon wins), `mecf_eligible_offers` and `mecf_upcoming_offers` (the offer list on the cart), `mecf_history_order_statuses` and `mecf_history_order_limit` (which past orders the history conditions read), `mecf_convert_amount` (final say on currency conversion), `mecf_outcome_field_groups` (extra settings on the coupon screen), `mecf_birthday_meta_key` (where the store keeps birthdays), `mecf_giftcard_email_subject` (the subject line of the gift card email).
Actions: `mecf_register_conditions` and `mecf_register_outcomes` (add your own types), `mecf_credit_entry_added`, `mecf_giftcard_issued`, `mecf_coupons_generated`, `mecf_campaign_fired` (notifications after the write, for pushing into a CRM or an audit trail).

React to a coupon decision with `mecf_coupon_event` ( `$event, $code, $data` ), which fires for every one — applied, auto-applied, queued, removed, silently removed, rejected and suppressed — or with the per-outcome `mecf_coupon_applied`, `mecf_coupon_queued`, `mecf_coupon_removed` and so on ( `$code, $data` ). `$data` carries the coupon id, the reason the customer was shown, the customer and session, the cart signature and the evaluation trace. Both fire even when the event log is switched off, so an integration never depends on a diagnostic setting.

`
add_action( 'mecf_coupon_applied', function ( $code, $data ) {
    my_analytics_track( 'coupon_applied', [ 'code' => $code, 'customer' => $data['customer_id'] ] );
}, 10, 2 );
`
Helper: `mecf_trace_coupon( 'SUMMER20' )` returns the full decision, including the trace.
REST: `mecf/v1/rules`, `mecf/v1/trace`, `mecf/v1/events`, `mecf/v1/conditions`, `mecf/v1/credit/{id}`, `mecf/v1/giftcards`, `mecf/v1/liability`, `mecf/v1/stats`.
WP-CLI: `wp mecf rule list|get|test`, `wp mecf credit`, `wp mecf giftcard`, `wp mecf generate`, `wp mecf import`, `wp mecf events`, `wp mecf diagnostics`.

= Trademarks =

This plugin is an independent project by Sergio Milardovich. It is not affiliated with, endorsed by or sponsored by Automattic, WooCommerce, Rymera Web Co (Advanced Coupons) or Soft79. WooCommerce is a trademark of Automattic Inc. Those names appear here only to describe what this plugin works with and which plugins it can import from.

== Installation ==

1. Upload the `milardovich-extra-coupon-features` folder to `/wp-content/plugins/`, or install through the Plugins screen.
2. Activate the plugin.
3. Edit any coupon and open the **Rules & trace** tab to add conditions, priority or auto-apply.
4. Use **Coupon Features → Rule Tester** to check a promotion against a simulated cart before publishing it.

== Frequently Asked Questions ==

= Do I have to use the rules engine for every coupon? =

No. A coupon with no conditions behaves exactly like a standard WooCommerce coupon. The condition builder only unfolds when you ask for it.

= Why did my coupon not apply? =

Open the cart while logged in as a shop manager and expand the coupon status panel, or run the same cart through **Coupon Features → Rule Tester**. Both show every condition with the expected and the actual value.

= Does it work with the Cart and Checkout Blocks? =

Yes. Auto-apply, silent removal and rule enforcement hook into the totals calculation that both the classic cart and the Store API go through, and the eligible offer data is exposed on the Store API cart response.

= Does it work with page caching? =

The rules run server side on every totals calculation, so cached page markup can show a stale coupon list. Exclude the cart and checkout pages from full-page caching; the Diagnostics screen warns you when a known caching plugin is active.

= Where is the discount amount configured? =

In the native WooCommerce **General** tab, along with the discount type. This plugin adds its own types — Buy X Get Y, tiered, fixed price per item — to that same list rather than offering a second one, and its tab holds only the extra settings each type needs. Invoices, WooCommerce Analytics and accounting integrations all see a normal coupon.

= Is store credit applied before or after tax? =

Whichever you choose in the settings. Which one is correct depends on your jurisdiction and on whether the credit was sold or given away, so the plugin asks rather than guessing.

= What happens to my data if I delete the plugin? =

Rules, the event log, campaigns, abandoned carts and the reporting cache are dropped, along with every setting and scheduled job. The store credit ledger and the gift card table are deliberately kept: both are outstanding liabilities, and deleting a plugin is not the same as writing off money your customers have already paid for or been promised. They are `wp_mecf_credit_ledger` and `wp_mecf_giftcards` if you have settled those balances and want them gone.

= If a customer does not spend a whole gift card, what happens to the rest? =

It stays on the card. The balance is the sum of the card's history, so a $100 card spent $30 at a time is worth $70, then $40, then $10, and only reaches "spent" at zero. Nothing expires it early and a repeated checkout callback cannot double-spend it.

The exception is deliberate: tick **one use** when you issue a card and it behaves like a paper voucher instead — whatever is not spent on that order is written off. The write-off is its own ledger entry marked `forfeit`, next to the redemption, so the history shows what was spent and what was given up separately, and it counts towards breakage rather than vanishing. If that order is later cancelled or fails, the forfeited remainder comes back with the rest of it.

Leave the box clear unless you have a reason not to. A card sold for cash is the customer's money, and in most places writing off the change is not yours to do.

= Can I move over from another coupon plugin? =

Yes, from Advanced Coupons and from Soft79's Extended Coupon Features. Preview the migration first: anything with no equivalent here is listed rather than quietly dropped, and nothing is deleted from the plugin you are leaving.

== Screenshots ==

1. The dashboard. What applied, what was rejected and why, across the last thirty days.
2. The rule tester. A synthetic cart evaluated against every published coupon, condition by condition, with the expected value beside the actual one. Nothing here touches a real cart.
3. The "Rules & trace" tab on the coupon screen: apply automatically, priority, exclusivity group, a percentage capped at a maximum, and condition groups with real AND/OR nesting.
4. The cart. Offers the customer can still apply, what they are short of for the ones they cannot, and the automatic coupons already in the totals.
5. The same cart seen by a shop manager: every coupon with the reason it did or did not apply, and where each discount landed line by line.
6. Store credit on an append-only ledger: outstanding liability, balances by customer, and the history behind them.
7. Coupon reports. Redemptions, discount cost and revenue next to each other, per coupon and per campaign.

== Changelog ==

= 1.0.0 =
* Engine: condition groups with AND/OR, deterministic priority and exclusivity, coupon queueing, capped percentage discounts, URL coupons with QR codes.
* Discount types: Buy X Get Y, tiered breaks, fixed price per item, and limit-to strategies.
* Value instruments: store credit on an append-only ledger, gift cards with an optional one-use mode, refund-to-credit, liability reporting.
* Growth: bulk generation, CSV import and export, lifecycle campaigns, coupon and campaign reporting, anti-abuse limits.
* Migration importers for Advanced Coupons and Soft79.
* Observability throughout: rule trace, rule tester, diagnostics, event log, REST API and WP-CLI.
