Filters Reference

This page is written for WooCommerce developers looking to extend or customize WooCommerce Product Bundles. It requires an advanced understanding of PHP and WordPress development.

Summary ↑ Back to top

This guide documents the most useful filter hooks available in Product Bundles. It is not an exhaustive reference of all available filters and does not include tutorials on how to achieve certain tasks. However, some filters are accompanied by links to snippets or mini-extensions that utilize them.

We recommend reading Data Structures and Storage and keeping the Functions Reference handy. Take time to familiarize yourself with the plugin architecture and the objects relevant to the hook you want to use.

Product Filters Summary ↑ Back to top

Name Description
woocommerce_bundled_item_*_quantities Group of filters that modify the default min/max quantities of bundled items used in price/availability calculations at the initialization phase of WC_Product_Bundle objects. Intended for plugins that introduce configuration/validation constraints to bundles.
woocommerce_bundle_requires_input Modifies the output of WC_Product_Bundle::requires_input, which indicates whether a product bundle has fields that require configuration in order to be added to the cart.
woocommerce_bundled_items Modifies the collection of bundled items available to a WC_Product_Bundle instance and returned by WC_Product_Bundle::get_bundled_items.
woocommerce_bundle_is_editable_in_cart Use this filter to control whether a Bundle added to the cart can be edited from the cart page.
woocommerce_bundle_cart_permalink_args Use this filter to change the arguments added to the permalink of a Bundle when editing its configuration from the cart.
woocommerce_bundled_item_discount_from_regular Use this filter to change the reference price used for calculating bundled item discounts.
woocommerce_sync_bundled_items_stock_status Database layer hook. Can be used to enable stock meta synchronization for bundled items, necessary if you need to reliably run bundled item stock_status and max_stock meta field queries.

Template Filters Summary ↑ Back to top

Name Description
woocommerce_bundled_item_is_optional_checked Filters the default checkbox state of optional bundled items.
woocommerce_bundled_item_classes Filters the html classes assigned to bundled item container elements in the single-product template.
woocommerce_bundled_product_quantity Modifies the default bundled product quantity value, which is equal to the minimum quantity by default.
woocommerce_bundles_optional_bundled_item_suffix Modifies the “optional” suffix appended to optional bundled items.
woocommerce_bundle_front_end_params Modifies the parameters passed to the single-product add-to-cart script.
woocommerce_force_show_bundled_dropdown-_variation_attribute_options Use this filter to always render the attribute options of bundled variable products in drop-down menus. By default, if a bundled variable product has only one active variation with well-defined attribute values, then its attribute selection drop-downs are hidden and replaced by pre-selected value descriptions.
woocommerce_bundle_show_bundled_product_attributes Controls whether to show the attributes of a bundled product in the single-product page of the bundle that contains it.

Cart Filters Summary ↑ Back to top

Name Description
woocommerce_bundled_item_add_to_cart_validation Applied when performing add-to-cart validation for bundle-type products, this filter can be used to run custom validation logic at bundled item level.
woocommerce_add_to_cart_bundle_validation Applied when performing add-to-cart validation for bundle-type products, this filter provides a last chance to modify a successful validation result.
woocommerce_bundled_item_has_bundled_weight Allows you to add the weight of a bundled item that is not Shipped Individually to the base weight of its physical container.
woocommerce_bundled_cart_item Use this filter to modify the cart item data of bundled products, which is re-applied on session load.
woocommerce_bundle_container_cart_item Use this filter to modify the cart item data of bundle containers, which is re-applied on session load.
woocommerce_bundled_item_cart_item_identifier Use this filter to add custom fields to the configuration data of a product bundle when it is added to the cart. Commonly used when adding custom configuration input fields to bundled products — e.g. Product Add-Ons fields.
woocommerce_bundled_item_cart_data Provides an opportunity to modify bundled/child cart item data by copying data already stored in the container/parent cart item. Commonly used to copy data previously added with the woocommerce_bundled_item_- cart_item_identifier filter.
woocommerce_add_bundled_cart_item_subtotals Modifies the way bundle subtotals appear in the cart.

Order Filters Summary ↑ Back to top

Name Description
woocommerce_add_bundled_order_item_subtotals Modifies the way bundle subtotals appear when displaying order details.
woocommerce_bundle_sku_from_order_item Alters the SKU of a product bundle object modified using the get_product_from_item method, based on a list of bundled products and quantities packaged in the bundle.

Admin Filters Summary ↑ Back to top

Name Description
woocommerce_bundles_process_bundled_item_admin_data Used to intercept and process custom posted fields associated with bundled item admin options. Any custom fields added here are saved as custom bundled item meta.
woocommerce_bundled_product_admin_html_tabs Used to create extra tabs to display custom bundled item admin options, in addition to the default Basic Settings and Advanced Settings tabs.

Product Filters ↑ Back to top

 

woocommerce_bundled_item_*_quantities

Description

Group of filters that modify the default min/max quantities of bundled items used in price/availability calculations at the initialization phase of WC_Product_Bundle objects. Intended for plugins that introduce configuration/validation constraints to bundles, to ensure an accurate display of bundle prices and/or availability.

woocommerce_bundled_item_optimal_price_quantities – Price-optimized quantities that satisfy one or more external constraints (min/max weight, min/max items count, etc) in addition to min/max item quantity.
woocommerce_bundled_item_worst_price_quantities – Price worst-case quantities that satisfy one or more external constraints (min/max weight, min/max items count, etc) in addition to min/max item quantity.
woocommerce_bundled_item_required_quantities – Price-optimized quantities that satisfy one or more external constraints (min/max weight, min/max items count, etc) in addition to min/max item quantity, with max item quantities capped by availability.

Max quantities are always assumed to be a superset of their Min counterparts, a safe assumption for most non-compound constraint problems related to quantities (min/max item count, min/max weight, min/max from categories). Some constraint problems might not follow this pattern — e.g., compound constraint problems.

Arguments

array $quantities_array – Array of min/max bundled item quantities to use. Quantities are first indexed by the string values min and max and then by bundled item ID.
WC_Product_Bundle $bundle – The product bundle object.

Example

The use of these filters is demonstrated in the Min/Max Items Mini-Extension.


 

woocommerce_bundle_requires_input

Description

Modifies the output of WC_Product_Bundle::requires_input, which indicates whether a product bundle has fields that require configuration in order to be added to the cart.

Arguments

array $quantities_array – Array of min/max bundled item quantities to use. Quantities are first indexed by the string values min and max and then by bundled item ID.
WC_Product_Bundle $bundle – Product bundle object.

Example

The filter is used by the Min/Max Items Mini-Extension. In this case, the minimum bundled item quantities are modified in order to satisfy the low-boundary total item count constraint in the cheapest possible way.


 

woocommerce_bundled_items

Description

Modifies the collection of bundled items available to a WC_Product_Bundle instance and returned by WC_Product_Bundle::get_bundled_items.

Arguments

array $bundled_items – Array of WC_Bundled_Item objects associated with the bundle, indexed by bundled item ID.
WC_Product_Bundle $bundle – Product bundle object.


 

woocommerce_bundle_is_editable_in_cart

Description

Use this filter to control whether a Bundle that has been added to the cart can be edited from the cart page.

Arguments

array $is_editable_in_cart – Indicates whether the bundle can be edited from the cart page.
WC_Product_Bundle $bundle – Product bundle object.
array|false $cart_item – Container cart item associated with the bundle when WC_Product_Bundle::is_editable_in_cart is called in cart context.


 

woocommerce_bundle_cart_permalink_args

Description

Use this filter to modify the arguments added to the permalink of a Bundle when editing its configuration from the cart.

Arguments

array $args – Parameter name/values to add to the permalink.
array|false $cart_item – Container cart item associated with the bundle when WC_Product_Bundle ::is_editable_in_cart is called in cart context.
WC_Product_Bundle $bundle – Product bundle object.


 

woocommerce_bundled_item_discount_from_regular

Description

Use this filter to change the reference price used for calculating bundled item discounts.

Arguments

boolean $calc_discounts_from_regular – Indicates whether to calculate discounts using regular prices as reference. Setting this to false allows discount calculations using sale prices as reference.
WC_Bundled_Item $bundled_item – Bundled item object.

Example

In this snippet, taken from the Tips, Tricks and Snippets guide, the filter is used to allow discounts over sale prices.


 

woocommerce_sync_bundled_items_stock_status

Description

Database layer hook. Can be used to enable stock meta synchronization for bundled items, necessary if you need to run bundled item stock_status and max_stock meta field queries reliably.

Arguments

boolean $sync – Indicates whether to keep bundled items stock meta fields synchronized with the stock status/quantity of the associated products.

 

Template Filters ↑ Back to top

 

woocommerce_bundled_item_is_optional_checked

Description

Filters the default checkbox state of optional bundled items.

Arguments

boolean $is_checked – The default checkbox state of the (optional) bundled product. Unchecked (false) by default.
WC_Bundled_Item $bundled_item – Bundled item object.

Example

In this snippet, taken from the Tips, Tricks and Snippets guide, the filter is used to make optional bundled items selected by default.


 

woocommerce_bundled_item_classes

Description

Filters the html classes assigned to bundled item container elements in the single-product template.

Arguments

array $classes – Class names.
WC_Bundled_Item $bundled_item – Bundled item object.


 

woocommerce_bundled_product_quantity

Description

Modifies the default bundled product quantity value, which is equal to the minimum quantity by default.

Arguments

integer $quantity_value – The default quantity value.
integer $quantity_min – The default quantity value.
integer $quantity_max – The default quantity value.
WC_Bundled_Item $bundled_item – Bundled item object.


 

woocommerce_bundles_optional_bundled_item_suffix

Description

Modifies the “optional” suffix appended to optional bundled items.

Arguments

WC_Bundled_Item $bundled_item – Bundled item object.
WC_Product_Bundle $bundle – Product bundle object.

Example

In this snippet, taken from the Tips, Tricks and Snippets guide, the filter is used to remove the title suffix of optional bundled items.


 

woocommerce_bundle_front_end_params

Description

Use this filter to modify the parameters passed to the single-product add-to-cart script.

Arguments

array $params – Array of parameters passed to the front-end script.


 

woocommerce_force_show_bundled_dropdown_variation_attribute_options

Description

Use this filter to always render the attribute options of bundled variable products in drop-down menus. By default, if a bundled variable product has only one active variation with well-defined attribute values, then its attribute selection drop-downs are hidden and replaced by pre-selected value descriptions.

Arguments

boolean $force_dropdowns – Indicates whether to force the display of drop-down menus for attribute value selection.
array $args – Array of parameters passed to the front-end script.


 

woocommerce_bundle_show_bundled_product_attributes

Description

Controls whether to show the attributes of a bundled product in the single-product page of the bundle that contains it.

By default, if a bundled product is set to be visible in the single-product template of its bundle, its attributes are displayed after the attributes of the bundle.

Arguments

boolean $include – Indicates whether to display the attributes of the bundled product.
WC_Product_Bundle $bundle – Product bundle object.
WC_Bundled_Item $bundle – Bundled item object.

 

Cart Filters ↑ Back to top

 

woocommerce_bundled_item_add_to_cart_validation

Description

Applied when performing add-to-cart validation for bundle-type products, this filter can be used to run custom validation logic at bundled item level.

Arguments

boolean $passes_validation – Validation result.
WC_Product $bundle – Product object associated with the bundled item being validated.
WC_Bundled_Item $bundled_itemWC_Bundled_Item object.
integer $quantity – Bundled product quantity.
integer|''|false $variation_id – Variation ID, if applicable.
array $configuration – Bundle configuration array.

Examples

The Min/Max Items Mini-Extension provides a good use case for the filter. The filter is also used in the WC_PB_Addons_Compatibility class included in Product Bundles, which contains compatibility code for the Product Add-Ons extension.


 

woocommerce_add_to_cart_bundle_validation

Description

Applied when performing add-to-cart validation for bundle-type products, this filter provides a last chance to modify a successful validation result.

Arguments

boolean $passes_validation – Validation result.
integer $bundle_id – Product bundle ID.
WC_PB_Stock_Manager $stock_mgr – Stock manager object used for validating bundled product stock quantities.
array $configuration – Bundle configuration array.


 

woocommerce_bundled_item_has_bundled_weight

Description

By default, the weight of a non-virtual bundle is assumed to be static and equal to the value entered in its Weight field, even when it contains bundled products that are not shipped individually. Using this filter, it is possible to use the value defined in the Weight field as a base bundle weight, and have the weight of all packaged bundled items added to this base weight (“packaged” used in this context to refer to items that are not Shipped Individually).

Arguments

boolean $add_weight_to_container – Indicates whether the weight of this bundled product should be appended to the weight of the parent. Defaults to false.
WC_Product $product – The bundled product object.
integer $bundled_item_id – The ID of the bundled item that the product is associated with.
WC_Product_Bundle $bundle – The product bundle object.

Example

This snippet, taken from the Tips, Tricks and Snippets guide, demonstrates how to enable a variable-weight scheme when a bundle contains packaged items.


 

woocommerce_bundled_cart_item

Description

Use this filter to modify the cart item data of bundled products, which is re-applied on session load.

Arguments

array $cart_item – Cart item data of bundled product.
WC_Product_Bundle $bundle – The parent product bundle object.


 

woocommerce_bundle_container_cart_item

Description

Use this filter to modify the cart item data of bundle containers, which is re-applied on session load.

Arguments

array $cart_item – Cart item data of bundle container product.
WC_Product_Bundle $bundle – The product bundle object.


 

woocommerce_bundled_item_cart_item_identifier

Description

Use this filter to add custom fields to the configuration data of a product bundle when it is added to the cart. Commonly used when adding custom configuration input fields to bundled products.

Arguments

array $item_configuration – Bundled item configuration array.
integer $bundled_item_id – Bundled item ID.
integer $bundle_id – Product bundle ID.

Examples

The use of this filter is demonstrated in the WC_PB_Addons_Compatibility class included in Product Bundles, which contains compatibility code for the Product Add-Ons extension. The filter is used to read posted data associated with bundled Product Add-Ons fields before adding the bundle to the cart, in order to pass them to the hashing function used to generate the cart ID of the bundle.


 

woocommerce_bundled_item_cart_data

Description

Provides an opportunity to modify bundled/child cart item data by copying data that is already stored in the container/parent cart item. Commonly used to copy data added using the woocommerce_bundled_item_cart_item_identifier filter.

Arguments

array $bundled_item_cart_data – Custom fields to add to the cart item data of a bundled product when it gets added to the cart.
integer $cart_item_data – Cart item data of the container/parent, which has just been added in the cart.

Examples

The use of this filter is demonstrated in the WC_PB_Addons_Compatibility class included in Product Bundles, which contains compatibility code for the Product Add-Ons extension. The filter is used to copy bundled Product Add-Ons fields from the container cart item.


 

woocommerce_add_bundled_cart_item_subtotals

Description

By default, the cart item subtotal of a bundle container item is calculated as the sum of the base/static bundle price subtotal + the subtotals of any bundled items that are priced individually, while the subtotals of individually-priced items are displayed with a ‘Subtotal:’ prefix. The filter can be used to prevent this.

Arguments

boolean $add_subtotals – Indicates whether to modify the way subtotals appear. Defaults to true.
array $container_item_data – Container/parent cart item.
array $container_item_key – Container/parent cart item key.

Example

This snippet, taken from the Tips, Tricks and Snippets guide, demonstrates how to prevent the extension from modifying item subtotals in the cart/orders.

 

Order Filters ↑ Back to top

 

woocommerce_add_bundled_order_item_subtotals

Description

By default, the order item subtotal of a bundle container item is calculated as the sum of the base/static bundle price subtotal + the subtotals of any bundled items that are priced individually, while the subtotals of individually-priced items are displayed with a ‘Subtotal:’ prefix. The filter can be used to prevent this.

Arguments

boolean $add_subtotals – Indicates whether to modify the way subtotals appear. Defaults to true.
array $container_item_data – Container/parent order item.
WC_Order $order – Order object.

Example

This snippet, taken from the Tips, Tricks and Snippets guide, demonstrates how to prevent the extension from modifying item subtotals in the cart/orders.


 

woocommerce_bundle_sku_from_order_item

Description

Use this filter to alter the SKU of a product bundle object modified using the get_product_from_item method, based on a list of the bundled products and quantities packaged in the bundle (“packaged” used in this context to refer to items that are not Shipped Individually).

Arguments

string $sku – The bundle SKU.
WC_Product $product – The product bundle object.
array $container_item_data – Container/parent order item.
WC_Order $order – Order object.
array $packaged_products – Bundled product objects corresponding to items packaged in the bundle for shipping.
array $packaged_quantities – Quantities of the products packaged in the bundle for shipping.

 

Admin Filters ↑ Back to top

 

woocommerce_bundles_process_bundled_item_admin_data

Description

Use this filter to intercept and process custom posted fields associated with bundled item admin options. Any custom fields added here will be saved as custom bundled item meta.

Arguments

array $processed_data – Array of parameters to be used for adding/updating a specific bundled item.
array $posted_data – Array of posted data associated with a specific bundled item.
integer|'' $bundled_item_id – ID of the bundled item when updating, or empty when creating it for the first time.
integer $bundled_id – ID of the product bundle.


 

woocommerce_bundled_product_admin_html_tabs

Description

Use this filer to create extra tabs to display custom admin options for bundled items, in addition to the default Basic Settings and Advanced Settings tabs.

Arguments

array $tabs – Array tab sections to display.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top