Developer filters and extension points

These filters are the supported extension contracts confirmed in the Purchase Planner source. Callbacks should be deterministic, fast, and free of writes or remote side effects because they run while the planner reads products, orders, coupons, or availability state.

leanmerce_purchase_planner_include_product is not present in the current source and is not a supported contract. Product exclusion is provided by leanmerce_purchase_planner_is_non_inventory_product.

leanmerce_purchase_planner_is_non_inventory_product

Purpose: classify gift cards, services, deposits, fees represented as products, or other items that should not be purchased. Runs: during product eligibility checks. Parameters: (bool $excluded, WC_Product $product). Return: boolean. Default: true when product meta _leanmerce_purchase_planner_exclude equals yes.

add_filter( 'leanmerce_purchase_planner_is_non_inventory_product', function ( bool $excluded, WC_Product $product ): bool {
    return $excluded || $product->is_virtual();
}, 10, 2 );

leanmerce_purchase_planner_include_order

Purpose: exclude an otherwise eligible WooCommerce order from sales evidence. Runs: after supported status and configured source exclusions, before line-item evidence is collected. Parameters: (bool $include, WC_Order $order). Return: boolean. Default: true.

add_filter( 'leanmerce_purchase_planner_include_order', function ( bool $include, WC_Order $order ): bool {
    return $include && 'training' !== $order->get_created_via();
}, 10, 2 );

leanmerce_purchase_planner_is_payment_coupon

Purpose: distinguish stored-value/payment instruments from promotional coupons. Runs: when coupon evidence is classified. Parameters: (bool $payment, WC_Coupon $coupon). Return: boolean. Default: true when coupon meta _leanmerce_purchase_planner_payment_coupon equals yes.

add_filter( 'leanmerce_purchase_planner_is_payment_coupon', function ( bool $payment, WC_Coupon $coupon ): bool {
    return $payment || str_starts_with( $coupon->get_code(), 'gift-' );
}, 10, 2 );

leanmerce_purchase_planner_purchase_state

Purpose: let a compatible inventory integration adapt the read-only purchase-state snapshot. Runs: after the default WooCommerce snapshot is built and before validation/planning. Parameters: (array $snapshot, WC_Product $product). Return: an array preserving valid state, stock, stock_owner, sale, backorders, and shared_stock values. Default: the WooCommerce-derived snapshot.

add_filter( 'leanmerce_purchase_planner_purchase_state', function ( array $snapshot, WC_Product $product ): array {
    if ( 'yes' === $product->get_meta( '_warehouse_blocked', true ) ) {
        $snapshot['state'] = 'blocked';
    }
    return $snapshot;
}, 10, 2 );

leanmerce_purchase_planner_default_brand_taxonomy

Purpose: choose the default product taxonomy shown as the brand selector. Runs: when the admin planner data is prepared. Parameter: (string $taxonomy). Return: a registered taxonomy attached to WooCommerce products. Default: product_brand when available, otherwise product_cat; an invalid return falls back to product_cat.

add_filter( 'leanmerce_purchase_planner_default_brand_taxonomy', function ( string $taxonomy ): string {
    return taxonomy_exists( 'pa_brand' ) ? 'pa_brand' : $taxonomy;
} );

Safety and verification

Do not mutate WooCommerce stock, create orders, call remote services, fabricate availability history, or write planner records inside these callbacks. Preserve return types and required snapshot keys. Test with HPOS enabled where applicable, a narrow SKU scope, representative order sources and coupons, and one complete plan. Verify the selection audit, relevant-order count, coupon classification, purchase state, warnings, and unchanged WooCommerce stock.