> ## 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.

# Hooks & Filters

> All available WordPress actions and filters for extending BoxBuilder.

BoxBuilder provides hooks and filters at major integration points. Use these to customize behavior without modifying plugin files.

## Box Builder Actions

### `boxbuilder_pro_loaded`

Fires when the BoxBuilder plugin finishes loading. Use this to initialize your extensions.

```php theme={null}
add_action( 'boxbuilder_pro_loaded', function() {
    // Plugin is fully loaded — safe to use BoxBuilder functions
});
```

### `boxbuilder/order_processing`

Fires when an order containing box products moves to processing status.

```php theme={null}
add_action( 'boxbuilder/order_processing', function( $order ) {
    // Send custom notification, update external system, etc.
    $order_id = $order->get_id();
}, 10, 1 );
```

### `boxbuilder/before_checkout_with_boxes`

Fires before the checkout form is rendered when the cart contains box products.

```php theme={null}
add_action( 'boxbuilder/before_checkout_with_boxes', function( $checkout ) {
    // Add custom messaging or validation before checkout
}, 10, 1 );
```

### `boxbuilder/order_item_created`

Fires when a box order line item is created during checkout.

```php theme={null}
add_action( 'boxbuilder/order_item_created', function( $item, $order ) {
    // Add custom meta to the order item
    $item->add_meta_data( '_my_custom_field', 'value' );
    $item->save();
}, 10, 2 );
```

### `boxbuilder/order_created`

Fires when an order containing box products is successfully created.

```php theme={null}
add_action( 'boxbuilder/order_created', function( $order ) {
    // Post-order processing for box orders
}, 10, 1 );
```

### `boxbuilder/mini_cart_boxes`

Fires when the mini cart displays box items.

```php theme={null}
add_action( 'boxbuilder/mini_cart_boxes', function( $box_count ) {
    // Customize mini cart display for boxes
}, 10, 1 );
```

### `boxbuilder/stock_reserved` <sup>Pro</sup>

Fires when stock is reserved for a box item (prevents overselling).

```php theme={null}
add_action( 'boxbuilder/stock_reserved', function( $product_id, $quantity, $session_id ) {
    // Track reserved stock, send alerts, etc.
}, 10, 3 );
```

### `boxbuilder/share_created` <sup>Pro</sup>

Fires when a shareable box link is created.

```php theme={null}
add_action( 'boxbuilder/share_created', function( $share_key, $share_data ) {
    // Track sharing analytics
}, 10, 2 );
```

### `boxbuilder/share_loaded` <sup>Pro</sup>

Fires when a shared box configuration is loaded from a URL.

```php theme={null}
add_action( 'boxbuilder/share_loaded', function( $share_key, $share_data ) {
    // Log shared box views
}, 10, 2 );
```

### `boxbuilder/customization_locked` <sup>Pro</sup>

Fires when a subscription box customization window is locked (deadline passed).

```php theme={null}
add_action( 'boxbuilder/customization_locked', function( $subscription_id ) {
    // Notify admin or trigger fallback logic
}, 10, 1 );
```

### `boxbuilder/reminder_sent` <sup>Pro</sup>

Fires when a customization reminder email is sent to a subscription customer.

```php theme={null}
add_action( 'boxbuilder/reminder_sent', function( $subscription_id, $product_id, $customer_email ) {
    // Track reminder delivery
}, 10, 3 );
```

## Box Builder Filters

### `boxbuilder/pricing_models`

Filter the available pricing models for boxes.

```php theme={null}
add_filter( 'boxbuilder/pricing_models', function( $models ) {
    // Add a custom pricing model
    $models['wholesale'] = [
        'label' => 'Wholesale Pricing',
        'description' => 'Special pricing for wholesale customers',
    ];
    return $models;
}, 10, 1 );
```

### `boxbuilder/price_html`

Filter the HTML output of box prices on the frontend.

```php theme={null}
add_filter( 'boxbuilder/price_html', function( $price_html, $product, $pricing_model ) {
    // Add "per box" suffix to fixed prices
    if ( $pricing_model === 'fixed' ) {
        $price_html .= ' <small>per box</small>';
    }
    return $price_html;
}, 10, 3 );
```

### `boxbuilder/default_sizes` <sup>Pro</sup>

Filter the default box size templates.

```php theme={null}
add_filter( 'boxbuilder/default_sizes', function( $sizes ) {
    // Add a custom default size
    $sizes[] = [
        'id'       => 'jumbo',
        'label'    => 'Jumbo',
        'capacity' => 48,
        'price'    => 99.99,
    ];
    return $sizes;
}, 10, 1 );
```

## Extensibility Hook Points

These hooks are registered as integration points for extending BoxBuilder. They can be used by add-ons and custom code:

| Hook                                  | Type   | Description                                         |
| ------------------------------------- | ------ | --------------------------------------------------- |
| `boxbuilder/box_added_to_cart`        | Action | Fires when a box is added to cart                   |
| `boxbuilder/before_product_grid`      | Action | Fires before the product grid renders               |
| `boxbuilder/after_add_to_cart_button` | Action | Fires after the add to cart button in the builder   |
| `boxbuilder/product_metabox_fields`   | Action | Add custom fields to the BoxBuilder product metabox |
| `boxbuilder/save_product_meta`        | Action | Save custom product metabox fields                  |
| `boxbuilder/available_products`       | Filter | Filter which products are available for a box       |
| `boxbuilder/box_price`                | Filter | Modify the calculated box price                     |
| `boxbuilder/item_low_stock`           | Action | Fires when a box item drops below stock threshold   |

## WooCommerce Integration Hooks

BoxBuilder hooks into standard WooCommerce hooks. You can add your own callbacks at a later priority:

### Cart Hooks

```php theme={null}
// BoxBuilder adds box data to cart items (priority 10)
add_filter( 'woocommerce_add_cart_item_data', 'boxbuilder_pro_add_box_data', 10, 3 );

// BoxBuilder displays box contents in cart (priority 10)
add_filter( 'woocommerce_get_item_data', 'boxbuilder_pro_display_box_data', 10, 2 );

// BoxBuilder hides child items from cart display (priority 10)
add_filter( 'woocommerce_cart_item_visible', 'boxbuilder_pro_hide_child_items', 10, 3 );

// BoxBuilder adjusts child item prices based on pricing model (priority 10)
add_action( 'woocommerce_before_calculate_totals', 'boxbuilder_pro_adjust_prices', 10, 1 );
```

### Order Hooks

```php theme={null}
// BoxBuilder saves box data to order items (priority 10)
add_action( 'woocommerce_checkout_create_order_line_item', 'boxbuilder_pro_save_order_data', 10, 4 );

// BoxBuilder hides child items in order display (priority 10)
add_filter( 'woocommerce_order_item_visible', 'boxbuilder_pro_hide_order_children', 10, 2 );

// BoxBuilder customizes meta display in admin (priority 10)
add_filter( 'woocommerce_order_item_display_meta_key', 'boxbuilder_pro_meta_key', 10, 3 );
add_filter( 'woocommerce_order_item_display_meta_value', 'boxbuilder_pro_meta_value', 10, 3 );
```

### Email Hooks

```php theme={null}
// BoxBuilder adds box content display to order emails
add_filter( 'woocommerce_email_order_items_args', 'boxbuilder_pro_email_args', 10, 1 );
```

## Hook Priority Guide

BoxBuilder uses priority `10` for all its hooks. To run your code:

* **Before BoxBuilder**: Use priority `5` or lower
* **After BoxBuilder**: Use priority `15` or higher
* **Override BoxBuilder**: Use the same priority (`10`) and remove BoxBuilder's callback first

```php theme={null}
// Remove BoxBuilder's callback and replace with your own
remove_filter( 'woocommerce_cart_item_visible', 'boxbuilder_pro_hide_child_items', 10 );
add_filter( 'woocommerce_cart_item_visible', 'my_custom_visibility', 10, 3 );
```