Claude Skill

wc-coupon-types-rules

Implement, extend, or audit WooCommerce coupon types, persisted coupon CRUD, eligibility rules, inclusions/exclusions, stacking, usage limits, and order lifecycle behavior. Covers the complete custom discount-type contract (`woocommerce_coupon_discount_types`, product-vs-cart cla

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download Lonsdale201-wp-agent-skills-woocommerce_wc-coupon-types-rules-8820ff3.zip · 12 KB

Install

skills CLI npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/woocommerce/wc-coupon-types-rules
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart
Git git clone https://github.com/Lonsdale201/wp-agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole lonsdale201/wp-agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

WooCommerce coupon types and rules

Keep coupon definition, eligibility, calculation, and usage accounting separate. Let WC_Discounts allocate discounts and let Woo totals calculate tax; do not rewrite cart item prices or totals to imitate a coupon.

Choose the coupon model

Need Model
Merchant-managed reusable code, native limits/reporting Persisted WC_Coupon (shop_coupon)
Generated code resolved from your own entitlement/table/service Use wc-coupon-dynamic for a virtual coupon
A new mathematical discount behavior visible in the type selector Custom coupon type from this skill
Surcharge or positive adjustment Use the Woo fee API, not a negative/creative coupon
Silent customer-specific product price Use a pricing rule only when it should not be represented as a coupon/order coupon line

Create persisted coupons with CRUD

Register custom types before loading or setting them. HPOS does not move coupons into order tables; they remain shop_coupon objects, but integrations should still use WC_Coupon CRUD.

$code = wc_format_coupon_code( 'PARTNER-2026' );

if ( wc_get_coupon_id_by_code( $code ) ) {
	throw new RuntimeException( 'Coupon code already exists.' );
}

$coupon = new WC_Coupon();
$coupon->set_code( $code );
$coupon->set_status( 'publish' );
$coupon->set_discount_type( 'percent' ); // Set before amount validation.
$coupon->set_amount( '15' );
$coupon->set_product_ids( array( 101, 102 ) );
$coupon->set_excluded_product_ids( array( 103 ) );
$coupon->set_exclude_sale_items( true );
$coupon->set_minimum_amount( '50' ); // Set before maximum.
$coupon->set_maximum_amount( '500' );
$coupon->set_usage_limit( 100 );
$coupon->set_usage_limit_per_user( 1 );
$coupon->set_date_expires( '2026-12-31 23:59:59' );
$coupon->save();

Use arrays of IDs and real booleans. Coupon-code comparison is case-insensitive; use wc_is_same_coupon() where available instead of raw ===.

The existence check is not an atomic uniqueness guarantee. Serialize concurrent creation in the integration's own job/idempotency mechanism; do not assume a unique database constraint on coupon codes.

Register a complete custom type

A functional type needs at least three layers. A label alone only makes the slug visible and acceptable to set_discount_type().

const MYPLUGIN_COUPON_TYPE = 'myplugin_member_percent';

// 1. Register globally: admin selector, WC_Coupon validation, and REST enum.
add_filter( 'woocommerce_coupon_discount_types', function ( array $types ): array {
	$types[ MYPLUGIN_COUPON_TYPE ] = __( 'Member percentage', 'myplugin' );
	return $types;
} );

// 2. Choose exactly one eligibility family. This is product-style.
add_filter( 'woocommerce_product_coupon_types', function ( array $types ): array {
	$types[] = MYPLUGIN_COUPON_TYPE;
	return array_values( array_unique( $types ) );
} );

// 3. Return a per-unit discount amount for the custom branch.
add_filter(
	'woocommerce_coupon_get_discount_amount',
	function ( $discount, $discounting_amount, $cart_item, $single, $coupon ) {
		if ( ! $coupon instanceof WC_Coupon || ! $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ) {
			return $discount;
		}

		$price = max( 0.0, (float) $discounting_amount );
		$rate  = min( 100.0, max( 0.0, (float) $coupon->get_amount() ) );

		return min( $price, $price * $rate / 100 );
	},
	10,
	5
);

For the custom branch, Woo calls get_discount_amount() per unit with $single = true, then multiplies by the applicable quantity. Return the discount, not the final price and not the entire line discount. The same filter also fires for core types, so always return the original value unless the exact custom slug matches.

Product-style versus cart-style

Choose exactly one:

// Product-style: inclusions/exclusions decide which items receive a discount.
add_filter( 'woocommerce_product_coupon_types', $register_type );

// Cart-style eligibility: a prohibited item invalidates the whole coupon.
add_filter( 'woocommerce_cart_coupon_types', $register_type );

Classification controls eligibility, not the custom type's math branch. A custom cart-style type still reaches apply_coupon_custom() rather than inheriting fixed_cart calculation. If the slug is in neither list, an unrestricted coupon normally validates but finds zero applicable items; native exclusions can instead reject it under the non-product path. Putting it in both makes rule semantics ambiguous and can cause cart validity to bypass per-item selection.

Custom types sort before built-in types by default. Define stacking order deliberately when it affects the result:

add_filter( 'woocommerce_coupon_sort', function ( $sort, WC_Coupon $coupon ) {
	return $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ? 2 : $sort; // Percent-like position.
}, 10, 2 );

Test both values of woocommerce_calc_discounts_sequentially.

Use native rules before custom rules

Rule WC_Coupon API
Include products/variations or parents set_product_ids()
Exclude products/variations or parents set_excluded_product_ids()
Include/exclude product categories set_product_categories(), set_excluded_product_categories()
Exclude sale items set_exclude_sale_items()
Cart subtotal window set_minimum_amount(), set_maximum_amount()
Allowed billing emails, including wildcard matching at validation set_email_restrictions()
Cannot normally stack set_individual_use()
Maximum qualifying quantity set_limit_usage_to_x_items()
Global/per-customer usage set_usage_limit(), set_usage_limit_per_user()
Expiry/free-shipping flag set_date_expires(), set_free_shipping()

free_shipping does not manufacture a rate; configure a compatible free-shipping method. Product restrictions behave differently according to product/cart classification, so regression-test mixed eligible and excluded carts.

Add deterministic custom rules

Use the narrowest hook:

add_filter(
	'woocommerce_coupon_is_valid',
	function ( bool $valid, WC_Coupon $coupon, WC_Discounts $discounts ): bool {
		if ( ! $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ) {
			return $valid;
		}

		return $valid && myplugin_customer_is_member( $discounts->get_object() );
	},
	10,
	3
);
  • woocommerce_coupon_is_valid: coupon/order-wide eligibility after native validation.
  • woocommerce_coupon_is_valid_for_product: per-item eligibility; signature is valid, product, coupon, values.
  • woocommerce_coupon_is_valid_for_cart: low-level cart-family applicability; prefer the final validity filter for ordinary whole-coupon rules, because forcing this true can bypass per-item selection.
  • woocommerce_coupon_get_items_to_apply: final item list; prefer removing items, because adding previously rejected items can bypass restrictions.
  • woocommerce_coupon_get_apply_quantity: cap qualifying quantity without changing cart quantity.
  • woocommerce_coupon_error: presentation only, not authorization.

Woo 11.1 adds six woocommerce_coupon_is_valid_for_* restriction filters, each receiving (valid, coupon, discounts). Unlike woocommerce_coupon_validate_* rejection predicates, true means valid. See the reference table before overriding native restrictions: later validators and per-product allocation still apply.

Validation runs many times in classic checkout, Blocks/Store API, order creation, and recalculation. Make it side-effect free, bounded, and usable with either WC_Cart or WC_Order. Avoid network requests in calculation/validation; prefetch/cache authoritative state or fail closed with a short timeout outside the hot calculation loop.

Do not base historical order recalculation on mutable membership tiers, time, external prices, or the current session. Store custom checkout facts as separate coupon-line metadata through woocommerce_checkout_create_order_coupon_item; never extend Woo's coupon_info JSON format. Load references/coupon-contract.md for hook signatures, order snapshots, admin fields, usage holds, and the complete validation matrix.

Respect core usage accounting

Persisted coupon usage is not just usage_count:

  • checkout tentatively holds global and per-user slots to reduce concurrent over-redemption;
  • pending, processing, on-hold, and completed orders count as usage;
  • cancelled, failed, and trashed orders release/reduce usage;
  • _used_by records customer ID or guest billing email;
  • the order's recorded-usage flag makes status retries idempotent.

Do not increment counts from validation, woocommerce_applied_coupon, or every payment webhook. A refund alone does not necessarily change the order into an invalid usage status, so define the merchant's refund/restoration policy explicitly.

Apply and auto-apply through Woo

if ( WC()->cart && ! WC()->cart->has_discount( $code ) ) {
	WC()->cart->apply_coupon( $code );
}

Guard repeated hooks because carts recalculate frequently. Use remove_coupon() when eligibility disappears. Do not mutate WC()->cart->applied_coupons directly, and do not assume classic form handlers cover Store API requests.

For an existing order, use $order->apply_coupon( $coupon_or_code ) and inspect WP_Error; it recalculates coupon/item/tax totals and usage state. Never add only a WC_Order_Item_Coupon row and assume the product totals were discounted.

Reject zero-allocation monetary applications before mutation

WC_Discounts takes product lines from an order. Fees and shipping are outside that allocation. On the tested pending fee-only order, both unrestricted percent and fixed_cart coupons returned success, left the total unchanged, and consumed usage. A valid coupon is not proof of a realized discount.

For an integration that promises a monetary discount, reject orders without eligible product lines before apply_coupon() or external entitlement reservation. If a preflight uses WC_Discounts, inspect its actual per-code allocation as well as validation; an existing discount/stacking policy can still affect the final amount. After applying, inspect the matching coupon line and product totals. Handle an unexpected zero result through an explicit rollback/error policy using Woo APIs, not direct counter edits. Free-shipping-only and deliberately zero-value coupons need their own policy.

Model a sale of a service as a genuine, non-stock-managed product when that matches the business meaning. Do not suppress stock handling on an entire mixed order to make a synthetic product line work. Do not turn fees into negative rows to imitate native coupon restrictions.

Historical recalculate_coupons() deliberately disables coupon-wide validation. Product allocation/calculation filters still matter; restore immutable policy before the first replay. For virtual coupons, use the scoped filter in wc-coupon-dynamic, not a snapshot repair after apply_coupon() returns.

Compatibility and security checklist

  1. Register the type on every frontend, REST, CLI, cron, and admin request before coupon hydration.
  2. Namespace the slug; preserve other plugins' filter values.
  3. Test product and variation inclusion/exclusion, categories, sale items, empty/free items, quantities, min/max, email, guest/user, expiry, and timezone. Include an unclassified-type regression: no restrictions yields zero allocation, while exclusions can reject it earlier.
  4. Test tax-inclusive/exclusive prices, multiple tax classes, currency decimals, rounding, and discounts larger than the item.
  5. Test stacking, individual-use behavior, both sequential settings, and deterministic sort.
  6. Test classic cart/checkout, Cart and Checkout Blocks, Store API, REST v3 coupon CRUD, admin order application/recalculation, refunds, cancellations, and plugin deactivation.
  7. Keep custom rule secrets and customer entitlements server-side; error text must not leak hidden eligibility data.
  8. Define migration/uninstall behavior: persisted custom-type coupons become unloadable or recalculate incorrectly when registration/calculation disappears.

Cross-references

  • Use wc-coupon-dynamic for virtual/non-shop_coupon codes and external usage accounting.
  • Use wc-cart-checkout-classic for classic cart state and order-item transfer.
  • Use wc-order-lifecycle-and-items for order status and refund side effects.

References

  • Disposable CLI smoke example
  • Verified source paths:
    • wp-content/plugins/woocommerce/includes/class-wc-coupon.php
    • wp-content/plugins/woocommerce/includes/class-wc-discounts.php
    • wp-content/plugins/woocommerce/includes/class-wc-cart.php
    • wp-content/plugins/woocommerce/includes/class-wc-cart-totals.php
    • wp-content/plugins/woocommerce/includes/abstracts/abstract-wc-order.php
    • wp-content/plugins/woocommerce/includes/wc-coupon-functions.php
    • wp-content/plugins/woocommerce/includes/wc-order-functions.php
    • wp-content/plugins/woocommerce/includes/data-stores/class-wc-coupon-data-store-cpt.php
    • wp-content/plugins/woocommerce/src/StoreApi/Utilities/CartController.php
Files (wp-agent-skills)
  • agents
    • openai.yaml 251 B
      Loading…
  • references
    • coupon-contract.md 17.9 KB
      Loading…
  • SKILL.md 14 KB
    ---
    name: wc-coupon-types-rules
    description: Implement, extend, or audit WooCommerce coupon types, persisted coupon CRUD, eligibility rules, inclusions/exclusions, stacking, usage limits, and order lifecycle behavior. Covers the complete custom discount-type contract (`woocommerce_coupon_discount_types`, product-vs-cart classification, calculation, and sort order), `WC_Coupon` setters, `WC_Discounts`, native product/category/sale/email/spend restrictions, custom validation hooks, admin fields, Store API and REST compatibility, concurrency holds, order snapshots, refunds/cancellations, taxes, and deterministic recalculation. Use when a plugin adds a coupon type or rule engine, changes which products/users qualify, creates coupons programmatically, auto-applies coupons, or produces incorrect/zero/duplicated discounts.
    metadata:
      wp-skills-author: "Soczó Kristóf"
      wp-skills-contact: "mailto:lonsdale201@hotmail.com"
      wp-skills-plugin: "woocommerce"
      wp-skills-plugin-version-tested: "11.1.1"
      wp-skills-php-min: "7.4"
      wp-skills-last-updated: "2026-09-21"
    ---
    
    # WooCommerce coupon types and rules
    
    Keep coupon definition, eligibility, calculation, and usage accounting separate. Let `WC_Discounts` allocate discounts and let Woo totals calculate tax; do not rewrite cart item prices or totals to imitate a coupon.
    
    ## Choose the coupon model
    
    | Need | Model |
    |---|---|
    | Merchant-managed reusable code, native limits/reporting | Persisted `WC_Coupon` (`shop_coupon`) |
    | Generated code resolved from your own entitlement/table/service | Use `wc-coupon-dynamic` for a virtual coupon |
    | A new mathematical discount behavior visible in the type selector | Custom coupon type from this skill |
    | Surcharge or positive adjustment | Use the Woo fee API, not a negative/creative coupon |
    | Silent customer-specific product price | Use a pricing rule only when it should not be represented as a coupon/order coupon line |
    
    ## Create persisted coupons with CRUD
    
    Register custom types before loading or setting them. HPOS does not move coupons into order tables; they remain `shop_coupon` objects, but integrations should still use `WC_Coupon` CRUD.
    
    ```php
    $code = wc_format_coupon_code( 'PARTNER-2026' );
    
    if ( wc_get_coupon_id_by_code( $code ) ) {
    	throw new RuntimeException( 'Coupon code already exists.' );
    }
    
    $coupon = new WC_Coupon();
    $coupon->set_code( $code );
    $coupon->set_status( 'publish' );
    $coupon->set_discount_type( 'percent' ); // Set before amount validation.
    $coupon->set_amount( '15' );
    $coupon->set_product_ids( array( 101, 102 ) );
    $coupon->set_excluded_product_ids( array( 103 ) );
    $coupon->set_exclude_sale_items( true );
    $coupon->set_minimum_amount( '50' ); // Set before maximum.
    $coupon->set_maximum_amount( '500' );
    $coupon->set_usage_limit( 100 );
    $coupon->set_usage_limit_per_user( 1 );
    $coupon->set_date_expires( '2026-12-31 23:59:59' );
    $coupon->save();
    ```
    
    Use arrays of IDs and real booleans. Coupon-code comparison is case-insensitive; use `wc_is_same_coupon()` where available instead of raw `===`.
    
    The existence check is not an atomic uniqueness guarantee. Serialize concurrent creation in the integration's own job/idempotency mechanism; do not assume a unique database constraint on coupon codes.
    
    ## Register a complete custom type
    
    A functional type needs at least three layers. A label alone only makes the slug visible and acceptable to `set_discount_type()`.
    
    ```php
    const MYPLUGIN_COUPON_TYPE = 'myplugin_member_percent';
    
    // 1. Register globally: admin selector, WC_Coupon validation, and REST enum.
    add_filter( 'woocommerce_coupon_discount_types', function ( array $types ): array {
    	$types[ MYPLUGIN_COUPON_TYPE ] = __( 'Member percentage', 'myplugin' );
    	return $types;
    } );
    
    // 2. Choose exactly one eligibility family. This is product-style.
    add_filter( 'woocommerce_product_coupon_types', function ( array $types ): array {
    	$types[] = MYPLUGIN_COUPON_TYPE;
    	return array_values( array_unique( $types ) );
    } );
    
    // 3. Return a per-unit discount amount for the custom branch.
    add_filter(
    	'woocommerce_coupon_get_discount_amount',
    	function ( $discount, $discounting_amount, $cart_item, $single, $coupon ) {
    		if ( ! $coupon instanceof WC_Coupon || ! $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ) {
    			return $discount;
    		}
    
    		$price = max( 0.0, (float) $discounting_amount );
    		$rate  = min( 100.0, max( 0.0, (float) $coupon->get_amount() ) );
    
    		return min( $price, $price * $rate / 100 );
    	},
    	10,
    	5
    );
    ```
    
    For the custom branch, Woo calls `get_discount_amount()` per unit with `$single = true`, then multiplies by the applicable quantity. Return the discount, not the final price and not the entire line discount. The same filter also fires for core types, so always return the original value unless the exact custom slug matches.
    
    ### Product-style versus cart-style
    
    Choose exactly one:
    
    ```php
    // Product-style: inclusions/exclusions decide which items receive a discount.
    add_filter( 'woocommerce_product_coupon_types', $register_type );
    
    // Cart-style eligibility: a prohibited item invalidates the whole coupon.
    add_filter( 'woocommerce_cart_coupon_types', $register_type );
    ```
    
    Classification controls eligibility, not the custom type's math branch. A custom cart-style type still reaches `apply_coupon_custom()` rather than inheriting `fixed_cart` calculation. If the slug is in neither list, an unrestricted coupon normally validates but finds zero applicable items; native exclusions can instead reject it under the non-product path. Putting it in both makes rule semantics ambiguous and can cause cart validity to bypass per-item selection.
    
    Custom types sort before built-in types by default. Define stacking order deliberately when it affects the result:
    
    ```php
    add_filter( 'woocommerce_coupon_sort', function ( $sort, WC_Coupon $coupon ) {
    	return $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ? 2 : $sort; // Percent-like position.
    }, 10, 2 );
    ```
    
    Test both values of `woocommerce_calc_discounts_sequentially`.
    
    ## Use native rules before custom rules
    
    | Rule | `WC_Coupon` API |
    |---|---|
    | Include products/variations or parents | `set_product_ids()` |
    | Exclude products/variations or parents | `set_excluded_product_ids()` |
    | Include/exclude product categories | `set_product_categories()`, `set_excluded_product_categories()` |
    | Exclude sale items | `set_exclude_sale_items()` |
    | Cart subtotal window | `set_minimum_amount()`, `set_maximum_amount()` |
    | Allowed billing emails, including wildcard matching at validation | `set_email_restrictions()` |
    | Cannot normally stack | `set_individual_use()` |
    | Maximum qualifying quantity | `set_limit_usage_to_x_items()` |
    | Global/per-customer usage | `set_usage_limit()`, `set_usage_limit_per_user()` |
    | Expiry/free-shipping flag | `set_date_expires()`, `set_free_shipping()` |
    
    `free_shipping` does not manufacture a rate; configure a compatible free-shipping method. Product restrictions behave differently according to product/cart classification, so regression-test mixed eligible and excluded carts.
    
    ## Add deterministic custom rules
    
    Use the narrowest hook:
    
    ```php
    add_filter(
    	'woocommerce_coupon_is_valid',
    	function ( bool $valid, WC_Coupon $coupon, WC_Discounts $discounts ): bool {
    		if ( ! $coupon->is_type( MYPLUGIN_COUPON_TYPE ) ) {
    			return $valid;
    		}
    
    		return $valid && myplugin_customer_is_member( $discounts->get_object() );
    	},
    	10,
    	3
    );
    ```
    
    - `woocommerce_coupon_is_valid`: coupon/order-wide eligibility after native validation.
    - `woocommerce_coupon_is_valid_for_product`: per-item eligibility; signature is valid, product, coupon, values.
    - `woocommerce_coupon_is_valid_for_cart`: low-level cart-family applicability; prefer the final validity filter for ordinary whole-coupon rules, because forcing this true can bypass per-item selection.
    - `woocommerce_coupon_get_items_to_apply`: final item list; prefer removing items, because adding previously rejected items can bypass restrictions.
    - `woocommerce_coupon_get_apply_quantity`: cap qualifying quantity without changing cart quantity.
    - `woocommerce_coupon_error`: presentation only, not authorization.
    
    Woo 11.1 adds six `woocommerce_coupon_is_valid_for_*` restriction filters, each receiving `(valid, coupon, discounts)`. Unlike `woocommerce_coupon_validate_*` rejection predicates, **true means valid**. See the reference table before overriding native restrictions: later validators and per-product allocation still apply.
    
    Validation runs many times in classic checkout, Blocks/Store API, order creation, and recalculation. Make it side-effect free, bounded, and usable with either `WC_Cart` or `WC_Order`. Avoid network requests in calculation/validation; prefetch/cache authoritative state or fail closed with a short timeout outside the hot calculation loop.
    
    Do not base historical order recalculation on mutable membership tiers, time, external prices, or the current session. Store custom checkout facts as separate coupon-line metadata through `woocommerce_checkout_create_order_coupon_item`; never extend Woo's `coupon_info` JSON format. Load [references/coupon-contract.md](references/coupon-contract.md) for hook signatures, order snapshots, admin fields, usage holds, and the complete validation matrix.
    
    ## Respect core usage accounting
    
    Persisted coupon usage is not just `usage_count`:
    
    - checkout tentatively holds global and per-user slots to reduce concurrent over-redemption;
    - pending, processing, on-hold, and completed orders count as usage;
    - cancelled, failed, and trashed orders release/reduce usage;
    - `_used_by` records customer ID or guest billing email;
    - the order's recorded-usage flag makes status retries idempotent.
    
    Do not increment counts from validation, `woocommerce_applied_coupon`, or every payment webhook. A refund alone does not necessarily change the order into an invalid usage status, so define the merchant's refund/restoration policy explicitly.
    
    ## Apply and auto-apply through Woo
    
    ```php
    if ( WC()->cart && ! WC()->cart->has_discount( $code ) ) {
    	WC()->cart->apply_coupon( $code );
    }
    ```
    
    Guard repeated hooks because carts recalculate frequently. Use `remove_coupon()` when eligibility disappears. Do not mutate `WC()->cart->applied_coupons` directly, and do not assume classic form handlers cover Store API requests.
    
    For an existing order, use `$order->apply_coupon( $coupon_or_code )` and inspect `WP_Error`; it recalculates coupon/item/tax totals and usage state. Never add only a `WC_Order_Item_Coupon` row and assume the product totals were discounted.
    
    ### Reject zero-allocation monetary applications before mutation
    
    `WC_Discounts` takes product lines from an order. Fees and shipping are outside that allocation. On the tested pending fee-only order, both unrestricted `percent` and `fixed_cart` coupons returned success, left the total unchanged, and consumed usage. A valid coupon is not proof of a realized discount.
    
    For an integration that promises a monetary discount, reject orders without eligible product lines **before** `apply_coupon()` or external entitlement reservation. If a preflight uses `WC_Discounts`, inspect its actual per-code allocation as well as validation; an existing discount/stacking policy can still affect the final amount. After applying, inspect the matching coupon line and product totals. Handle an unexpected zero result through an explicit rollback/error policy using Woo APIs, not direct counter edits. Free-shipping-only and deliberately zero-value coupons need their own policy.
    
    Model a sale of a service as a genuine, non-stock-managed product when that matches the business meaning. Do not suppress stock handling on an entire mixed order to make a synthetic product line work. Do not turn fees into negative rows to imitate native coupon restrictions.
    
    Historical `recalculate_coupons()` deliberately disables coupon-wide validation. Product allocation/calculation filters still matter; restore immutable policy before the first replay. For virtual coupons, use the scoped filter in `wc-coupon-dynamic`, not a snapshot repair after `apply_coupon()` returns.
    
    ## Compatibility and security checklist
    
    1. Register the type on every frontend, REST, CLI, cron, and admin request before coupon hydration.
    2. Namespace the slug; preserve other plugins' filter values.
    3. Test product and variation inclusion/exclusion, categories, sale items, empty/free items, quantities, min/max, email, guest/user, expiry, and timezone. Include an unclassified-type regression: no restrictions yields zero allocation, while exclusions can reject it earlier.
    4. Test tax-inclusive/exclusive prices, multiple tax classes, currency decimals, rounding, and discounts larger than the item.
    5. Test stacking, individual-use behavior, both sequential settings, and deterministic sort.
    6. Test classic cart/checkout, Cart and Checkout Blocks, Store API, REST v3 coupon CRUD, admin order application/recalculation, refunds, cancellations, and plugin deactivation.
    7. Keep custom rule secrets and customer entitlements server-side; error text must not leak hidden eligibility data.
    8. Define migration/uninstall behavior: persisted custom-type coupons become unloadable or recalculate incorrectly when registration/calculation disappears.
    
    ## Cross-references
    
    - Use `wc-coupon-dynamic` for virtual/non-`shop_coupon` codes and external usage accounting.
    - Use `wc-cart-checkout-classic` for classic cart state and order-item transfer.
    - Use `wc-order-lifecycle-and-items` for order status and refund side effects.
    
    ## References
    
    - [Disposable CLI smoke example](../wcs-upgrade-compatibility/examples/woo-skills-smoke/woo-skills-smoke.php)
    - Verified source paths:
      - `wp-content/plugins/woocommerce/includes/class-wc-coupon.php`
      - `wp-content/plugins/woocommerce/includes/class-wc-discounts.php`
      - `wp-content/plugins/woocommerce/includes/class-wc-cart.php`
      - `wp-content/plugins/woocommerce/includes/class-wc-cart-totals.php`
      - `wp-content/plugins/woocommerce/includes/abstracts/abstract-wc-order.php`
      - `wp-content/plugins/woocommerce/includes/wc-coupon-functions.php`
      - `wp-content/plugins/woocommerce/includes/wc-order-functions.php`
      - `wp-content/plugins/woocommerce/includes/data-stores/class-wc-coupon-data-store-cpt.php`
      - `wp-content/plugins/woocommerce/src/StoreApi/Utilities/CartController.php`
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.