Skip to main content

WooCommerce Integration

The \Suma\WooCommerce class (inc/class-woocommerce.php) is the central hub for all WooCommerce customizations in the theme. With 760+ lines, it registers 50+ hooks and filters covering checkout, cart, products, orders, emails, and payment method integrations.

Initialization​

// Loaded by class-theme.php
new \Suma\WooCommerce();

The constructor registers all hooks immediately on instantiation.

Checkout Customizations​

Field Modifications​

// Remove billing fields not needed for precious metals
add_filter( 'woocommerce_checkout_fields', [ $this, 'modify_checkout_fields' ] );

// Customize default address field labels/requirements
add_filter( 'woocommerce_default_address_fields', [ $this, 'modify_address_fields' ] );

// Modify form field HTML classes and attributes
add_filter( 'woocommerce_form_field_args', [ $this, 'modify_form_field_args' ] );

AvaTax Address Validation​

AvaTax address validation is disabled at the checkout level to prevent friction:

// Disable AvaTax address validation UI at checkout
// (AvaTax still calculates taxes server-side)
add_filter( 'wc_avatax_show_checkout_address_validation', '__return_false' );

Metal Trading Pause Guard​

The checkout/cart flow includes a metal-trading pause guard via \Suma\Cart\Cart_Notices (inc/cart/class-cart-notices.php). If trading is paused for configured metals, customers are blocked from completing checkout until violating items are removed.

// ACF option flags read by Cart_Notices
pause_silver_in_checkout
pause_gold_in_checkout
pause_plat_in_checkout

Behavior details:

  • Cart shows a dynamic warning listing violating products.
  • Checkout route guard redirects back to cart when paused products are present.
  • Messaging supports single or combined paused-metal states (including platinum).

Cart & Pricing​

// Custom cart pricing display (shows premiums, spot price breakdown)
add_action( 'woocommerce_cart_pricing', [ $this, 'render_cart_pricing' ] );

// Maximum quantity limits per product
add_filter( 'woocommerce_quantity_input_max', [ $this, 'quantity_input_max' ], 10, 2 );

// Sale validation (ensure prices aren't negative after spot price changes)
add_filter( 'woocommerce_product_is_on_sale', [ $this, 'validate_sale_price' ], 10, 2 );

Product Display​

// Product card rendering (used with custom Elementor product grid widget)
add_action( 'suma_render_product', [ $this, 'render_product_card' ] );

// Product availability text (e.g., "Ships within 3-5 business days")
add_filter( 'woocommerce_get_availability', [ $this, 'custom_availability_text' ], 10, 2 );

// Rating display on product forms
add_action( 'add_to_cart_form_rating', [ $this, 'display_product_rating' ] );

Cryptocurrency Payment Integration​

The theme registers custom display blocks for CryptoWoo payment instructions. Customers receive specific guidance for each supported cryptocurrency:

// Solana (SOL)
add_action( 'cw_display_extra_details_payment_SOL', [ $this, 'display_solana_payment_details' ] );

// Bitcoin (BTC)
add_action( 'cw_display_extra_details_payment_BTC', [ $this, 'display_bitcoin_payment_details' ] );

// Ethereum (ETH)
add_action( 'cw_display_extra_details_payment_ETH', [ $this, 'display_ethereum_payment_details' ] );

// Bitcoin Cash (BCH)
add_action( 'cw_display_extra_details_payment_BCH', [ $this, 'display_bch_payment_details' ] );

// Litecoin (LTC)
add_action( 'cw_display_extra_details_payment_LTC', [ $this, 'display_litecoin_payment_details' ] );

Order Status Hooks​

// Monitor all order status changes
add_action( 'woocommerce_order_status_changed', [ $this, 'on_order_status_changed' ], 10, 4 );

// Override processing order count in menu (exclude ACH pending orders)
add_filter( 'woocommerce_include_processing_order_count_in_menu', [ $this, 'exclude_pending_ach_from_menu_count' ] );

Email Customization​

// Custom email footer branding
add_action( 'woocommerce_email_footer', [ $this, 'custom_email_footer' ] );

// Modify email settings registration
add_filter( 'woocommerce_email_settings', [ $this, 'filter_email_settings' ] );

My Account Customizations​

// Add custom actions to My Account → Orders table
add_filter( 'woocommerce_my_account_my_orders_actions', [ $this, 'add_custom_order_actions' ], 10, 2 );

Script and Style Management​

The theme dequeues default WooCommerce scripts and styles and replaces them with optimized theme versions:

add_action( 'wp_enqueue_scripts', [ $this, 'manage_wc_scripts' ] );

// Inside manage_wc_scripts():
wp_dequeue_style( 'woocommerce-general' );
wp_dequeue_style( 'woocommerce-layout' );
wp_dequeue_style( 'woocommerce-smallscreen' );
// ... enqueue theme CSS instead

This allows full control over WooCommerce's front-end appearance without needing to override every CSS class.

add_filter( 'woocommerce_breadcrumb_defaults', function( array $defaults ) : array {
    $defaults['delimiter'] = ' › ';
    return $defaults;
} );

Wishlist Integration (YITH)​

// Customize YITH Wishlist button text
add_filter( 'yith_wcwl_button_label', [ $this, 'wishlist_button_label' ] );

Performance: Heartbeat API​

The WordPress Heartbeat API (admin AJAX polling) is stopped on the front-end to prevent unnecessary Lambda invocations on the serverless stack:

add_action( 'init', function() : void {
    wp_deregister_script( 'heartbeat' );
} );

Shortcodes Registered​

ShortcodeMethodOutput
[wc-account-link]wc_account_link()Styled link to My Account page
[wc-account-title]wc_account_title()Current My Account sub-page title
[wc-cart-icon]wc_cart_icon()Cart icon SVG with item count badge
[wc-product-detail]wc_product_detail()Inline product detail display
[wc-recent-orders]wc_recent_orders()Recent orders list for logged-in users

Deposits Plugin Integration​

The woocommerce-deposits plugin (partial payments) is integrated for the bank wire deposit flow. Custom hooks coordinate between the deposit gateway, the WooCommerce Deposits plugin, and the order status management:

  • Deposit amount = 5% of order total
  • Collected via scottsdale-deposit-gateway (PayPal CC)
  • Remaining balance tracked via the Deposits plugin's partial payment system

Smart Coupons Integration​

woocommerce-smart-coupons integrations ensure:

  • Discount timing aligns with AvaTax tax calculation (tax applies before or after discount based on coupon type)
  • Gift certificate redemption works correctly with precious metals pricing

Known Edge Cases​

ScenarioHandling
Spot price changes while item is in cartCart re-validates pricing on order submission
Out-of-stock product added to cart (reserved stock held by another session)reserved-stock-pro handles this with session-based locking
Crypto payment confirmation during price update windowPrice locked at time of order placement (not re-calculated after submission)
International shipping to restricted countriesWooCommerce shipping zone blocking; not enforced at PHP level
Metal trading paused in Scottsdale CP (including platinum)Cart notice + checkout redirect guard prevent order completion until violating items are removed