> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftlywp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Storage

> How BoxBuilder stores data using native WordPress and WooCommerce tables.

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

| Data               | Storage            | Key                                      |
| ------------------ | ------------------ | ---------------------------------------- |
| Box enabled flag   | Product post meta  | `_is_boxbuilder_enabled`                 |
| Box configuration  | Product 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 data      | WC cart item data  | `boxbuilder_items`, `boxbuilder_message` |
| Cart parent flag   | WC cart item data  | `boxbuilder_is_parent`                   |
| Cart child flag    | WC cart item data  | `boxbuilder_is_child`                    |
| Cart session ID    | WC cart item data  | `boxbuilder_parent_session_id`           |
| Order box flag     | WC order item meta | `_boxbuilder_is_box`                     |
| Order child flag   | WC order item meta | `_boxbuilder_is_child`                   |
| Order parent link  | WC order item meta | `_boxbuilder_part_of_box`                |
| Order box contents | WC order item meta | `_boxbuilder_contents`                   |
| Gift message       | WC order item meta | `_boxbuilder_message`                    |
| Plugin settings    | `wp_options`       | `boxbuilder_*`                           |
| Saved boxes (Pro)  | User meta          | `_boxbuilder_saved_boxes`                |
| Share URLs (Pro)   | WP transients      | `boxbuilder_share_{key}`                 |

## Box Configuration Format

The `_boxbuilder_box_config` meta stores a JSON array:

```json theme={null}
{
  "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):**

```php theme={null}
[
    '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):**

```php theme={null}
[
    'boxbuilder_is_child'          => true,
    'boxbuilder_parent_session_id' => 'unique-session-id',
]
```

## Order Item Meta

After checkout, the parent-child relationship is preserved:

```php theme={null}
// 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:

```php theme={null}
// 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:

```php theme={null}
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.