Data Structures and Storage

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

Product Data ↑ Back to top

Database Level ↑ Back to top

Product Bundles are stored in the database as custom post type entries of the product post type, similar to all product types in WooCommerce core. The extension introduces the Bundle type by adding a bundle term value to the product_type taxonomy. The database schema for bundles includes the same data as the schema for simple WooCommerce products. Some additional type-specific options are stored in the meta table:

Meta Key Description
_wc_pb_base_price Base price of the bundle.
_wc_pb_base_regular_price Base regular price of the bundle.
_wc_pb_base_sale_price Base sale price of the bundle.
_wc_pb_layout_style Layout option state.
Values: default | tabular.
_wc_pb_edit_in_cart Indicates whether Editing in Cart is enabled.
Values: yes | no.
_wc_pb_sold_individually_context Sold Individually option context.
Values: product | configuration.

Data associated with bundled items is not saved in the post meta table. Instead, for scalability and speed when working with bundle parent/child relationships, the extension adds two tables to the database:

  • woocommerce_bundled_items and
  • woocommerce_bundled_itemmeta.

Both table names are prefixed with your WP Database Table Prefix, usually wp_.

The woocommerce_bundled_items table is used to store all bundle-to-bundled-products associations using a simple schema:

Table Field Description
bundled_item_id Unique ID of the bundled item.
product_id ID of the product associated with the bundled item.
bundle_id ID of the “parent” product bundle.
menu_order Sort order of the bundled item relative to other items in the same bundle.

The woocommerce_bundled_itemmeta table stores all bundled item options as meta data, similar to how the postmeta table is used by WordPress to store meta data for the posts table:

Table Field Description
meta_id Unique ID of the meta entry.
bundled_item_id ID of the associated bundled item.
meta_key Meta key.
meta_value Meta value.
For database schema details, refer to /includes/class-wc-pb-install.php

The extension provides a Database API for working with these tables, which includes:

  • query_bundled_items, a utility function for database queries which includes support for meta queries and
  • a number of utility functions for creating, updating and deleting bundled items and meta.

These functions, (as well as all bundled item data operations at the application level) rely on a WC_Bundled_Item_Data class that handles all CRUD (create, read, update, delete) operations for a single bundled item.

Application Level ↑ Back to top

All bundles are instances of the WC_Product_Bundle class, which extends the core WC_Product class. Naturally, you can use all methods of the WC_Product class on bundle-type product instances. The WC_Product_Bundle class provides a number of methods specific to Product Bundle objects. A detailed reference of all methods is beyond the scope of this document – please refer to the class itself for details about each method.

One WC_Product_Bundle method worth mentioning here is get_bundled_items, which returns a collection of WC_Bundled_Item class instances – one for each bundled item contained in the parent bundle. The extension uses the WC_Bundled_Item class as an application level abstraction of the “bundled item” concept. The class provides a unified API for accessing various product data relevant in a bundle context: A type-unaware method example is is_in_stock, which is used to obtain the stock status of a bundled item. Note that this may not be the same as the stock status of the associated bundled product, due to the influence of the Minimum Quantity option, and/or the existence of Variation Filters. Other type-unaware method examples are is_optional, get_title and get_description. A type-specific method example is the get_children method, which returns the variation IDs of a bundled variable product, taking Variation Filtering settings into account. Please refer to the WC_Bundled_Item class inline method documentation for details.

Every instance of the WC_Bundled_Item class relies on a WC_Bundled_Item_Data class instance in order to obtain the data necessary for its own initialization. The WC_Bundled_Item_Data class is a bundled item data wrapper that also handles all bundled item database CRUD operations – for details, please refer to the Functions Reference document section that is dedicated to the Bundled Items CRUD class.

Cart & Order Item Data ↑ Back to top

Relationships ↑ Back to top

In cart context, a WC_Product_Bundle product acts as a trigger for adding additional products to the cart on the woocommerce_add_to_cart action, depending on the posted configuration data. Prior to this, the extension does its own client-side and server-side validation to ensure that a configuration can be added to the cart, taking into account all configuration and availability constraints.

In the cart, a bundle shows up as a group of cart items:

  • A container cart item, associated with the product bundle itself.
  • A number of bundled cart items, each associated with a bundled product.

Assuming that an order is placed, the same group of quantity-synced cart items will find their way into the created order, as well.

Thanks to this approach:

  • All inventory management is relayed to WooCommerce core.
  • Compatibility with 3rd party plugins/extensions is greatly simplified, since the process of adding bundled products to the cart/order does not bypass any hooks that would be normally triggered in core.
  • The container cart/order item can be used to easily override the physical properties of its children at the application layer, useful in use cases with complex shipping requirements.
  • A clear separation of bundle level and bundled product level prices in the cart makes it easier to implement complex pricing schemes and allows each bundled item to maintain its individual tax rate.

Cart Item Data ↑ Back to top

Parent/child cart items are identified by appending the following fields to cart items:

Field Type Item Context Description
bundled_by string Bundled Cart item ID of the container cart item that this bundled cart item belongs to.
bundled_items array Container Cart item IDs of all bundled cart items associated with this bundle container item.
stamp array Bundled/Container Array with bundle configuration data, used for a) identifying the entire group uniquely and b) carrying out in-cart validation.
bundled_item_id string Bundled Bundled item ID associated with this bundled cart item. Refer to the Database schema in the Product Data section above.

This data is used internally to establish the parent/child relationships of cart items associated with a bundle. The extension provides a set of global utility functions that you can use to:

  • Check if a cart item is a bundled item and get its parent.
  • Check if a cart item is a bundle container item and get its children.

For details, please refer to the Cart section of the Functions Reference document.

Order Item Data ↑ Back to top

Parent/child order items are identified by creating the following order item meta:

Key Type Item Context Description
_bundle_cart_key string Bundled/Container Original cart item ID (or other unique hash) that identifies this order item.
_bundled_by string Bundled Unique hash of the container cart item that this bundled order item belongs to.
_bundled_items serialized array Container Unique hashes of all bundled items associated with this bundle container item.
_stamp serialized array Bundled/Container Serialized array with bundle configuration data, used for a) identifying the entire group uniquely and b) carrying out in-cart validation when re-ordering.
_bundled_item_id string Bundled Bundled item ID associated with this bundled order item. Refer to the Database schema in the Product Data section above.
_bundled_item_priced_- _individually string Bundled Indicates whether the item was individually priced when the order was placed.
_bundled_item_needs_- shipping string Bundled Indicates whether the bundled item required shipping individually from the bundle when the order was placed.
_bundle_weight numeric Container The total per-unit weight of a bundle container when the order was placed. May differ from the value defined in the Weight field of the Shipping tab when using a variable container weight.

This data is used internally to establish the parent/child relationships of order items associated with a bundle. The extension provides a set of global utility functions that you can use to:

  • Check if an order item is a bundled item and get its parent.
  • Check if an order item is a bundle container item and get its children.

For details, please refer to the Order section of the Functions Reference document.

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

Back to the top