Data Structures and Storage

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

Product Data ↑ Back to top

Composite Products 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 Composite type by adding a composite term value to the product_type taxonomy.

All composite products are instances of the WC_Product_Composite class, which extends the core WC_Product class. You can use all methods of the WC_Product class with composite-type product instances. In addition to these, the WC_Product_Composite class provides a number of methods specific to Composite Product 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.

WC_Product_Composite objects rely on their own datastore for reading/writing object properties from/to the database. The following table contains a list of properties and meta fields specific to the Composite type:

Property Meta Key Description
price _bto_base_price Base price of the composite product.

regular_price _bto_base_regular_price Base regular price of the composite product.

sale_price _bto_base_sale_price Base sale price of the composite product.

composite_data _bto_data Component data, serialized.
scenario_data _bto_scenario_data Scenario definitions, serialized.
layout _bto_style Layout value.

Values: single | progressive | paged | paged-componentized
shop_price_calc _bto_shop_price_calc Catalog Price value.

Values: defaults | min_max | hidden
editable_in_cart _bto_edit_in_cart Edit in Cart option value.
Values: yes | no
add_to_cart_form_location _bto_add_to_cart_form_location Form Location value.

Values: yes | no
sold_individually_context _bto_sold_individually Sold Individually option context.

Values: product | configuration
virtual_composite _wc_pb_virtual_composite Manages state for the Virtual checkbox. When the Virtual box is ticked, all Components, in addition to the Composite itself, are treated as Virtual.

When the virtual_composite property is true, then the virtual property is also true.

When the virtual_composite property is false, the virtual property is used to control whether the Composite is an assembled or unassembled one.

For more information, refer to the examples that follow this table.

Values: yes | no
aggregate_weight _wc_bto_aggregate_weight When creating assembled Composites, this property controls whether chosen Component Option weights should be aggregated and added to the weight specified under Product Data > Shipping.

Values: yes | no

Examples: Physical/Virtual Composite Products

Virtual Composite — virtual_composite => true | virtual => true
Unassembled Composite — virtual_composite => false | virtual => true
Assembled Composite — virtual_composite => false | virtual => false

Cart & Order Item Data ↑ Back to top

Relationships ↑ Back to top

In cart context, a WC_Product_Composite 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 composite product shows up as a group of cart items:

  • A container cart item, associated with the composite product itself.
  • A number of child cart items, each associated with a Component.

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 child products to the cart/orders 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 parent and child prices in the cart makes it easier to implement complex pricing schemes and allows each child 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
composite_parent string Child Cart item ID of the container cart item that this child cart item belongs to.
composite_children array Parent Cart item IDs of all child cart items associated with a composite container item.
composite_data array Parent/Child Composite configuration data array, used for a) identifying the entire group uniquely and b) carrying out in-cart validation.
composite_item string Child Component ID associated with this child cart item.

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

  • Check if a cart item is a composite child item and get its parent.
  • Check if a cart item is a composite parent item and get its children.

For details, please refer to the Functions Reference.

Order Item Data ↑ Back to top

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

Key Type Item Context Description
_composite_cart_key string Parent/Child Original cart item ID (or other unique hash) that identifies the order item.
_composite_parent string Child Unique hash of the parent order item.
_composite_children serialized array Parent Unique hashes of all associated child items.
_composite_data serialized array Parent/Child Serialized array with composite configuration data, used for a) identifying the entire group uniquely and b) carrying out in-cart validation when re-ordering.
_composite_item string Child Component ID associated with this child order item.
_component_priced_- _individually string Child Indicates whether the item was Priced Individually when the order was placed.
_component_needs_- shipping string Child Indicates whether the child item was Shipped Individually from the composite when the order was placed.
_composite_weight numeric Parent The total per-unit weight of a composite parent 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 composite. The extension provides a set of global utility functions that you can use to:

  • Check if an order item is a composite child item and get its parent.
  • Check if an order item is a composite parent item and get its children.

For details, please refer to the Functions Reference.

Questions & Support ↑ Back to top

Have a question? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!

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

Back to the top