CheckoutWC Addon: Shipping Method Order Bump Rule

Adds a "Shipping Method (Checkout)" display condition to CheckoutWC Order Bumps: show or hide a bump based on the shipping method the customer has chosen at checkout.

Built and verified against CheckoutWC 10.3.3. Background on the rule engine and the extension technique: checkout-for-woocommerce-10-3-3/docs/order-bump-rules.md (§7).

Install

Copy this folder to wp-content/plugins/ and activate. Requires WooCommerce + CheckoutWC (with Order Bumps, i.e. a premium plan).

Usage

1. Edit an Order Bump → Display Conditions panel → add a rule.
2. Choose Shipping Method (Checkout) from the rule dropdown.
3. Pick a condition:
   • Is one of the entered methods — bump shows only while a listed method is chosen.
   • Is none of the entered methods — bump hides while a listed method is chosen.
4. Enter a comma-separated list of methods. Each entry may be (case-insensitive):
   • an instance ID — flat_rate:2 (most precise; shown in the field's help text),
   • a method type — flat_rate, free_shipping, local_pickup (matches every instance of that type),
   • the label shown at checkout — e.g. Express.

Multiple rule rows are AND-ed, like all CheckoutWC rules. For "method A or method B", put both in one row's list: flat_rate:1, flat_rate:4.

Multi-package carts: the rule matches against the chosen method of any package.

How it works

CheckoutWC's RulesProcessor has no extension hook and hides bumps whose rules contain unknown rule types, so this addon:

• Admin: injects the rule definition into the rule builder's catalog at runtime (webpack chunk push against webpackChunkcheckout_for_woocommerce; the catalog module is located by content, so CheckoutWC updates don't break on module-ID changes). The editor saves rows into the normal cfw_ob_rules meta.
• Everywhere else: strips its rows from cfw_ob_rules reads (get_post_metadata filter) so core's evaluator never sees them, and evaluates them itself via the cfw_display_bump and cfw_is_cart_bump_valid filters — covering all display locations (including the After Checkout Submit modal), cart revalidation, and cleanup of auto-added bumps.

Stripping is the default and is only skipped where the full rules array is genuinely needed: real wp-admin screens (not admin-ajax), the bump editor's own REST routes (/wp/v2/cfw_order_bumps with context=edit or write methods), cron, and WP-CLI. This matters because CheckoutWC evaluates bumps in more contexts than plain page loads: its checkout actions are registered on both wc-ajax and wp_ajax_woocommerce_* (admin-ajax.php, where is_admin() is true), and the After Checkout Submit modal list is recomputed inside those AJAX refreshes — v1.0.0 skipped stripping there, which made that modal's bumps disappear. The chosen-method lookup also falls back to the posted shipping_method field when the session doesn't carry it (e.g. during the place-order submission).

No CheckoutWC files are modified.

Troubleshooting: modal bump not appearing

Work through these in order — the first three are CheckoutWC gates unrelated to this addon:

1. Does the modal show with the shipping rule removed? If not, the problem is upstream of this addon:
   • Maximum After Checkout Submit Modal Bumps (CheckoutWC Order Bumps settings) — default is 1; 0 disables the modal entirely, and if another complete_order bump sorts earlier (menu order), it takes the only slot.
   • The cart must need payment (free carts skip the modal list).
   • All of core's own gates apply: bump published, offer product purchasable/in stock, offer product not already in the cart, bump not already in the cart.
2. Hard-refresh the checkout page after changing bump config — the initial list is localized into the page.
3. Change the shipping method once (or trigger any checkout update) and then click Place Order — the synced list updates on checkout refresh events.
4. Enable debugging (below) and reproduce. In the WooCommerce log, look for the bump ID in wc-ajax:update_checkout entries: a rule-row fail shows the exact identifiers compared against your configured targets; no entry at all means core hid the bump before this addon's rule ran (enable CheckoutWC's debug log and check the checkout-wc source). In the browser console (debug on), each checkout refresh logs synced after_checkout_bumps with the current list — your bump's ID should appear there once the matching method is selected.

Debugging

Enable debug logging with any of:

• define( 'CFW_OBSMR_DEBUG', true ); in wp-config.php,
• CheckoutWC → Settings → Advanced → Enable Debug Log (the addon piggybacks on it),
• add_filter( 'cfw_obsmr_debug_enabled', '__return_true' );

Entries are written to the WooCommerce log — WooCommerce → Status → Logs, source cfw-ob-shipping-method-rule. Each line is prefixed with the request context (frontend, wc-ajax:update_checkout, admin-ajax:..., rest:/checkoutwc/v1/..., admin, cron, cli), and covers every decision point:

• when rule rows are stripped from a rules read (and how many),
• each rule evaluation: operator, configured targets, the chosen-method identifiers actually resolved, and pass/fail,
• when a bump is hidden (cfw_display_bump, with location) or invalidated (cfw_is_cart_bump_valid),
• why no chosen method could be resolved (no session, nothing posted),
• misconfigured rules (empty targets, unknown operator),
• UI injection on the bump editor screen.

Logging is deduplicated and capped per request, so it's safe to leave on while reproducing an issue. To diagnose "bump not showing": reproduce, then check the log for the bump's ID — you'll see either a rule-row fail with the exact identifiers it compared, or nothing, which means the bump was hidden by CheckoutWC's own gates before this addon's rule ran (enable CheckoutWC's debug log and check the checkout-wc source for those).

Behavior notes & limitations

• Outside checkout (e.g. Side Cart on shop pages before shipping is calculated) no method is chosen: "is one of" hides the bump, "is none of" shows it.
• After Checkout Submit modal: CheckoutWC computes a fresh modal bump list (after_checkout_bumps) in every checkout refresh, but its front-end never copies that key into the client data store — the modal reads the list evaluated at initial page load. For rules that change mid-checkout (shipping method is the prime example) the modal would therefore never react to the shopper's selection. This addon closes that core gap: it syncs the refreshed list into the client store on every cfw_pre_updated_checkout event, for all rule types. By place-order time the modal list reflects the shipping method actually selected.
• Switching methods at checkout: the bump list updates when CheckoutWC refreshes the checkout (which happens on shipping method change). A bump already added to the cart is removed on the next cart update if the rule no longer passes — same as native rules.
• Auto-add bumps: CheckoutWC's auto-add check doesn't run display filters, so an auto-add bump may be added ignoring this rule — but the revalidation hook removes it in the same request. Net effect is correct; avoid pairing this rule with auto-add if you care about the transient add/remove.
• Trust Badges rule builder is not extended (order bumps only).
• Deactivating this addon while bumps still contain Shipping Method rules: those bumps become hidden on the front end (core fails closed on unknown rules), and opening such a bump in the editor breaks its Display Conditions panel (core bug — unguarded catalog lookup). Delete the Shipping Method rules from your bumps before deactivating permanently.
• If a future CheckoutWC build changes its bundle internals, the rule stops appearing in the editor dropdown (fails soft, console warning) — existing rules keep working on the front end. Re-verify after major CheckoutWC updates.