Skip to main content
BoxBuilder uses zero custom database tables. All data is stored using standard WordPress and WooCommerce storage mechanisms, ensuring full compatibility with backup plugins, migration tools, and the WooCommerce ecosystem.

​
Storage Map

DataStorageKey
Box enabled flagProduct post meta_is_boxbuilder_enabled
Box configurationProduct post meta_boxbuilder_box_config
Box sizes (Pro)Product post meta_boxbuilder_box_sizes
Custom items (Pro)Product post meta_boxbuilder_custom_items
Cart box dataWC cart item databoxbuilder_items, boxbuilder_message
Cart parent flagWC cart item databoxbuilder_is_parent
Cart child flagWC cart item databoxbuilder_is_child
Cart session IDWC cart item databoxbuilder_parent_session_id
Order box flagWC order item meta_boxbuilder_is_box
Order child flagWC order item meta_boxbuilder_is_child
Order parent linkWC order item meta_boxbuilder_part_of_box
Order box contentsWC order item meta_boxbuilder_contents
Gift messageWC order item meta_boxbuilder_message
Plugin settingswp_optionsboxbuilder_*
Saved boxes (Pro)User meta_boxbuilder_saved_boxes
Share URLs (Pro)WP transientsboxbuilder_share_{key}

​
Box Configuration Format

The _boxbuilder_box_config meta stores a JSON array: 
{
  "capacity_type": "fixed",
  "max_items": 12,
  "min_items": 6,
  "allow_partial": false,
  "pricing_model": "per_item",
  "fixed_price": 0,
  "product_source": "categories",
  "allowed_cats": [12, 15, 18],
  "allowed_products": [],
  "layout": "grid",
  "products_per_page": 12
}

​
Cart Item Data Structure

When a box is in the cart: Parent item (the box): 
[
    'boxbuilder_is_parent'     => true,
    'boxbuilder_session_id'    => 'unique-session-id',
    'boxbuilder_items'         => [
        ['product_id' => 45, 'quantity' => 2],
        ['product_id' => 67, 'quantity' => 1],
    ],
    'boxbuilder_message'       => 'Happy Birthday!',
]
Child items (hidden sub-items): 
[
    'boxbuilder_is_child'          => true,
    'boxbuilder_parent_session_id' => 'unique-session-id',
]

​
Order Item Meta

After checkout, the parent-child relationship is preserved: 
// Parent order item
$item->get_meta( '_boxbuilder_is_box' );       // 'yes'
$item->get_meta( '_boxbuilder_contents' );     // array of items
$item->get_meta( '_boxbuilder_message' );      // 'Happy Birthday!'

// Child order item
$item->get_meta( '_boxbuilder_is_child' );     // 'yes'
$item->get_meta( '_boxbuilder_part_of_box' );  // parent order item ID

​
Querying Box Orders

To find orders containing boxes: 
// Get all orders with box products
$orders = wc_get_orders( [
    'meta_query' => [
        [
            'key'   => '_boxbuilder_is_box',
            'value' => 'yes',
        ],
    ],
] );

​
Plugin Settings

All settings are stored in wp_options with the boxbuilder_ prefix: 
get_option( 'boxbuilder_default_layout', 'grid' );
get_option( 'boxbuilder_products_per_page', 12 );
get_option( 'boxbuilder_primary_color', '#5c6ac4' );
get_option( 'boxbuilder_gift_message_enabled', 'yes' );

​
Data Cleanup on Uninstall

When BoxBuilder is uninstalled (deleted, not just deactivated), it removes:
  • All boxbuilder_* options from wp_options
  • BoxBuilder-specific post meta from products
  • BoxBuilder-specific user meta
Order data (_boxbuilder_* order item meta) is preserved after uninstall. This ensures historical order records remain intact.