# Analytics Dashboard
Source: https://docs.swiftlywp.com/plugins/boxbuilder/analytics
Track box sales, popular items, fill rates, and revenue.
The Analytics Dashboard is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro includes a built-in analytics dashboard at **BoxBuilder → Analytics** that gives you insights into how your box products are performing.
## Dashboard Metrics
The analytics dashboard shows these key metrics:
| Metric | Description |
| --------------------------- | ------------------------------------------------------- |
| **Total Orders with Boxes** | Number of orders containing at least one box product |
| **Total Boxes Sold** | Total number of box products sold |
| **Total Revenue** | Revenue generated from box products |
| **Total Items in Boxes** | Total number of individual items placed in boxes |
| **Average Fill Rate** | How full customers are filling their boxes (percentage) |
| **Average Order Value** | Average value of orders containing boxes |
## Reports
### Most Popular Products
A chart showing which products are most frequently added to boxes. Helps you understand customer preferences and stock accordingly.
### Top Selling Box Products
A table showing your best-performing box products by revenue and units sold.
### Top Boxes
A table showing which box configurations generate the most orders and revenue.
### Fill Rate Analysis
Understand how customers use your boxes:
* Are they filling boxes to capacity, or leaving spots empty?
* Which box sizes have the best fill rate?
* Does fill rate correlate with box capacity?
## Date Ranges
Filter analytics by time period:
| Range | Description |
| ------------------ | ----------------------- |
| **Last 7 days** | Previous week |
| **Last 30 days** | Previous month |
| **Last 90 days** | Previous quarter |
| **Last 12 months** | Previous year |
| **All time** | Since plugin activation |
## Dashboard Overview
The main **BoxBuilder → Dashboard** page also shows summary stats:
* Active Boxes (published box products)
* Boxes Sold (total count)
* Revenue (Pro only)
These give you a quick glance without visiting the full analytics page.
## Export
Export analytics data as CSV for use in spreadsheets or reporting tools. Click the **Export** button on the analytics page.
## Performance
Analytics queries run against WooCommerce order item meta — no custom database tables. Results are cached using WordPress object cache and refreshed when order statuses change.
# Appearance
Source: https://docs.swiftlywp.com/plugins/boxbuilder/appearance
Customize colors, borders, and visual styling of the box builder.
BoxBuilder is designed to look great with any WordPress theme out of the box. For further customization, use the **Appearance** settings tab.
## Appearance Settings
Navigate to **BoxBuilder → Settings → Appearance** to customize:
### Brand Colors
| Setting | Description | Default |
| ----------------- | ------------------------------------------------------------------------ | --------- |
| **Primary Color** | Main accent color for buttons, progress bars, selected states, and links | `#5c6ac4` |
| **Success Color** | Color for success states (item added badges, confirmations) | `#28a745` |
Choose a primary color that matches your store's branding. The color picker supports hex values — click "Default" to reset to the original color.
### Card Styling
| Setting | Options | Default |
| ---------------- | --------------------------------------------------------------------------------------------- | -------------- |
| **Corner Style** | Square (0px), Slightly Rounded (4px), Rounded (8px), More Rounded (12px), Very Rounded (16px) | Rounded (8px) |
| **Card Shadow** | None (Flat), Light (Subtle), Medium (Prominent) | Light (Subtle) |
### Advanced Pro
| Setting | Description | Default |
| ------------------ | --------------------------------------------------------------- | ------- |
| **Enable logging** | Write debug information to WooCommerce logs for troubleshooting | Enabled |
Leave logging enabled during setup and testing. You can disable it on production sites to avoid unnecessary log file growth. Logs are accessible at **WooCommerce → Status → Logs**.
## CSS Namespacing
All BoxBuilder CSS is namespaced under `.boxbuilder-wrap` to prevent conflicts with your theme. Every element uses a `.boxbuilder-` prefix:
```css theme={null}
.boxbuilder-wrap { }
.boxbuilder-grid { }
.boxbuilder-product-card { }
.boxbuilder-summary { }
.boxbuilder-progress { }
```
## Custom CSS
If you need custom styles beyond the settings, you can add CSS in **Appearance → Customize → Additional CSS** or your theme's custom CSS area.
Common customizations:
```css theme={null}
/* Change product card background */
.boxbuilder-wrap .boxbuilder-product-card {
background-color: #f9f9f9;
}
/* Change the Add to Box button style */
.boxbuilder-wrap .boxbuilder-add-btn {
border-radius: 20px;
text-transform: uppercase;
}
/* Adjust grid gap */
.boxbuilder-wrap .boxbuilder-grid {
gap: 20px;
}
```
Avoid using `!important` in custom CSS. BoxBuilder styles use low specificity intentionally — your theme or custom CSS should be able to override them naturally. If you need `!important`, the selector specificity may need adjusting.
## Theme Compatibility
BoxBuilder uses WordPress-native styles as a foundation and minimal custom CSS on top. It's tested and compatible with:
* Storefront
* Astra
* GeneratePress
* Flatsome
* OceanWP
* Divi
* Avada
If you experience styling issues with your theme, please [contact support](https://swiftlywp.com/support/).
# Box Sizes
Source: https://docs.swiftlywp.com/plugins/boxbuilder/box-sizes
Offer multiple box sizes with different capacities and prices.
Multiple box sizes is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro lets you offer multiple sizes for a single box product — for example, Small (6 items, $19.99), Medium (12 items, $34.99), and Large (24 items, \$59.99). The customer picks their size before building the box.
## Setting Up Sizes
Edit your box product and go to the **BoxBuilder** tab.
In the **Box Sizes** section, add your sizes. Each size has:
* **Label**: The name customers see (e.g., "Small", "Medium", "Large")
* **Capacity**: How many items this size holds
* **Price**: The price for this size (used with fixed or hybrid pricing)
## Size Display Settings
Configure size display in **BoxBuilder → Settings → Cart** under **Box Sizes**:
### Size Display Style
| Style | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Cards (dropdown on mobile)** | Visual cards showing label, capacity, and price — automatically switches to dropdown on small screens (default) |
| **Dropdown selector** | A compact dropdown menu — useful when you have many size options |
You can also set the **Cards Per Row** (2, 3, 4, or 5 — default is 3) to control how many size cards appear in a row.
### Size Change Behavior
When a customer changes their size after already adding items to the box, you can control what happens:
| Behavior | Description |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| **Keep items that fit, remove excess** | Items that still fit the new capacity are kept; excess items are removed (default) |
| **Prevent size change** | Block size changes when items exceed the new capacity |
| **Show warning and ask to confirm** | Display a confirmation dialog before changing |
## Example Configuration
| Size | Capacity | Price |
| --------- | -------- | ------- |
| Small | 6 items | \$19.99 |
| Medium | 12 items | \$34.99 |
| Large | 24 items | \$59.99 |
| Party Box | 48 items | \$99.99 |
Use sizes to create natural upsell opportunities. Show the per-item savings for larger sizes — "Small: $3.33/item vs Large: $2.50/item".
## How Sizes Work with Pricing
| Pricing Model | Size Price Behavior |
| ------------- | -------------------------------------------- |
| **Fixed** | Each size has its own fixed price |
| **Per-Item** | Size has no price — total is sum of items |
| **Hybrid** | Each size has a base price + per-item prices |
# Builder Position
Source: https://docs.swiftlywp.com/plugins/boxbuilder/builder-position
Control where the box builder appears on the WooCommerce product page.
When BoxBuilder is enabled on a product, the builder UI automatically appears on the single product page. You can control exactly where it's placed.
## Position Options
Configure the builder position in **BoxBuilder → Settings → General** under **Builder Position**.
### Full-Width Positions
These positions span the full width of the product page, below the product image/summary area:
| Position | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| **Before Product Tabs** | Above the WooCommerce product tabs (Description, Reviews, etc.) — recommended for classic themes |
| **Replace Product Tabs** | Replaces the product tabs entirely with the box builder |
| **After Product Tabs** | Below the product tabs |
### Narrow Positions
These positions place the builder within the product summary column (next to the product image):
| Position | Description |
| --------------------------- | ---------------------------------------------- |
| **After Price** | Below the product price |
| **After Short Description** | Below the short description / excerpt |
| **After Add to Cart Form** | Below the default add to cart button |
| **After Product Meta** | Below the product meta (SKU, categories, tags) |
### Block Theme Position
| Position | Description |
| ------------------------------- | ----------------------------------------------------------------------------- |
| **After Product Details Block** | For Full Site Editing / block themes — placed after the product details block |
### Manual Placement
| Position | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Shortcode Only \[boxbuilder]** | Disables automatic placement — use the `[boxbuilder]` shortcode or Gutenberg block to place the builder manually |
## Choosing the Right Position
**Before Product Tabs** works best for most classic themes (Storefront, Astra, GeneratePress, etc.). The builder gets full width and is prominently placed without interfering with the product image area.
If you're using a Full Site Editing theme (like Twenty Twenty-Four), use **After Product Details Block** for the best placement.
If you use Elementor, Divi, or another page builder, select **Shortcode Only** and place `[boxbuilder]` where you want the builder to appear. This gives you full control over positioning.
If you're not happy with any of the automatic positions, select "Shortcode Only" and use the `[boxbuilder]` shortcode or Gutenberg block to place the builder exactly where you want it.
## Summary Panel Position
You can also choose which side the summary panel appears on:
| Position | Description |
| -------------- | -------------------------------------------------------------- |
| **Right Side** | Summary panel on the right, product grid on the left (default) |
| **Left Side** | Summary panel on the left, product grid on the right |
## Hiding the Default Add to Cart
When BoxBuilder is enabled on a product, the default WooCommerce "Add to Cart" button is automatically hidden. The box builder's own "Add to Cart" button is used instead, which validates the box before adding to cart.
# Cart Integration
Source: https://docs.swiftlywp.com/plugins/boxbuilder/cart-integration
How box products appear and behave in the WooCommerce cart.
BoxBuilder integrates deeply with WooCommerce's cart system. When a customer adds a box to the cart, it appears as a single, clean line item with the box contents displayed beneath it.
## How It Works
Under the hood, BoxBuilder uses a **hidden sub-items pattern**:
1. The **parent item** is the box product itself — this is what the customer sees in the cart
2. Each selected product is added as a **hidden child item** — invisible to the customer but tracked by WooCommerce for stock management
This architecture means:
* WooCommerce handles stock reduction for each individual product automatically
* Coupons, taxes, and shipping work with standard WooCommerce calculations
* No custom database tables or workarounds needed
## Cart Display
The box appears in the cart as a single item with:
* Box product name and image
* Price (based on your pricing model)
* Box contents listed below the item name
* Gift message (if provided)
* Quantity (fixed at 1 per box by default)
### Cart Settings
Configure cart behavior in **BoxBuilder → Settings → Cart**:
| Setting | Description | Default |
| ------------------------- | ----------------------------------- | --------- |
| **Show cart contents** | Display box contents in the cart | Yes |
| **Box quantity editable** | Allow changing box quantity in cart | No |
| **After add redirect** | Where to go after adding to cart | Cart page |
### After Add to Cart Redirect
| Option | Behavior |
| ------------ | ------------------------------------------------ |
| **Cart** | Redirect to the cart page |
| **Checkout** | Redirect directly to checkout |
| **Stay** | Stay on the current page (with a success notice) |
## Removing a Box
When a customer removes a box from the cart, all hidden child items are automatically removed too. There's no way for orphaned child items to remain in the cart.
## Cart Item Visibility
Child items are hidden from:
* The cart table (customer view)
* The mini cart / cart widget
* The cart totals
But they are still tracked internally for:
* Stock management (each product's stock is reduced at checkout)
* Order line items (visible in admin)
* Inventory reports
## Pricing in Cart
| Pricing Model | Parent Item Price | Child Item Prices |
| ------------- | ------------------------------ | ----------------------------- |
| **Fixed** | Full box price (e.g., \$29.99) | \$0.00 each |
| **Per-Item** | \$0.00 | Each item's WooCommerce price |
| **Hybrid** | Base box price (e.g., \$10.00) | Each item's WooCommerce price |
## WooCommerce Cart Blocks
BoxBuilder is compatible with the WooCommerce Cart block (block-based cart). Child items are filtered from the Store API response so they don't appear in the block-based cart.
## Mini Cart
Box items display correctly in the WooCommerce mini cart widget. Child items are hidden — only the parent box item is shown.
## Related
* [Orders & Emails](/plugins/boxbuilder/orders-and-emails) — how boxes appear in orders
* [Pricing Models](/plugins/boxbuilder/pricing-models) — pricing configuration
* [Inventory](/plugins/boxbuilder/inventory) — stock management
# Category Filters
Source: https://docs.swiftlywp.com/plugins/boxbuilder/category-filters
Add category filter tabs to the product picker for easy browsing.
Category filters are a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
Category filter tabs appear above the product grid, letting customers quickly filter products by category. For example: **All | Chocolates | Sweets | Nuts | Dried Fruits**.
## How It Works
When your box product uses **By Category** as the product source, BoxBuilder Pro automatically generates filter tabs for each selected category. An "All" tab is included to show all products.
Clicking a tab filters the product grid instantly via AJAX — no page reload.
## Filter Display Styles
Configure the filter style in **BoxBuilder → Settings → Display** under **Search & Filter**:
| Style | Description |
| ------------------- | ----------------------------------------------------------------- |
| **Horizontal Tabs** | Clickable tabs above the grid (default) — best for 2–5 categories |
| **Dropdown Select** | A select dropdown — more compact for 6+ categories |
You can also enable/disable category filters globally in **BoxBuilder → Settings → Display** under **Search & Filter**.
## Setup
Go to **Products** and edit your box product.
In the **BoxBuilder** tab, set **Product Source** to **By Category** and select your categories.
Category filters appear automatically on the frontend when there are multiple categories selected.
Category filters only appear when the product source is set to **By Category** with 2 or more categories selected. If you use "All Products" or "Specific Products", there are no categories to filter by.
## Behavior
* Selecting a category tab filters the product grid to show only products in that category
* The product count and pagination update accordingly
* The "All" tab shows products from all selected categories
* Filter state is preserved if the customer paginates within a category
# Compatibility
Source: https://docs.swiftlywp.com/plugins/boxbuilder/compatibility
Themes, page builders, and plugins tested with BoxBuilder.
BoxBuilder is tested with the most popular WordPress themes, page builders, and WooCommerce extensions.
## Themes
BoxBuilder is tested and confirmed compatible with:
| Theme | Status |
| -------------------------------- | ---------------- |
| Storefront (WooCommerce default) | Fully compatible |
| Astra | Fully compatible |
| GeneratePress | Fully compatible |
| Flatsome | Fully compatible |
| OceanWP | Fully compatible |
| Divi (as theme) | Fully compatible |
| Avada | Fully compatible |
BoxBuilder is designed to work with any well-coded WordPress theme. If you experience issues with a specific theme, [contact support](https://swiftlywp.com/support/).
## Page Builders
The `[boxbuilder id="123"]` shortcode and Gutenberg block work with all major page builders:
| Page Builder | Integration |
| ------------------------ | ------------------------ |
| Gutenberg / Block Editor | Native block + shortcode |
| Elementor | Shortcode widget |
| Divi Builder | Code module or shortcode |
| WPBakery | Text block or raw HTML |
| Bricks Builder | Shortcode element |
| Beaver Builder | HTML module |
| Oxygen Builder | Shortcode component |
## WooCommerce Extensions
| Extension | Status | Notes |
| ------------------------------- | ---------------- | ----------------------------------- |
| WooCommerce Subscriptions | Compatible (Pro) | Required for subscription box mode |
| YITH WooCommerce PDF Invoices | Compatible | Box contents shown on invoices |
| WC PDF Invoices & Packing Slips | Compatible | Box contents shown on packing slips |
| WPML + WooCommerce Multilingual | Compatible (Pro) | Full translation support |
| WooCommerce Bookings | Compatible | No conflicts |
| WooCommerce Points and Rewards | Compatible | Points earned on box purchases |
| Sumo Subscriptions | Compatible (Pro) | Alternative subscription plugin |
| Fox Currency Switcher | Compatible (Pro) | Multi-currency pricing |
## Checkout Plugins
| Plugin | Status |
| ---------------------- | ---------- |
| CheckoutWC | Compatible |
| FunnelKit / WooFunnels | Compatible |
| CartFlows | Compatible |
## WooCommerce Cart/Checkout Blocks
BoxBuilder is compatible with the WooCommerce block-based cart and checkout. Child items are filtered from the Store API so they don't appear as separate line items.
## Known Interactions
BoxBuilder automatically disables the WooCommerce product image lightbox on box product pages to prevent conflicts with the builder UI. This is intentional.
If you use a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache), make sure your cart pages and box product pages are excluded from page caching. AJAX requests should not be cached.
CSS/JS minification plugins (Autoptimize, WP Rocket) should work fine. If you experience issues, try excluding BoxBuilder's CSS and JS files from minification.
## Reporting Compatibility Issues
If you find a plugin or theme that doesn't work with BoxBuilder:
1. Deactivate other plugins one by one to identify the conflict
2. Try switching to the Storefront theme to rule out theme issues
3. [Contact support](https://swiftlywp.com/support/) with:
* WordPress version
* WooCommerce version
* BoxBuilder version
* Conflicting plugin/theme name and version
* Description of the issue
* Screenshots if possible
# Creating a Box Product
Source: https://docs.swiftlywp.com/plugins/boxbuilder/creating-a-box
Learn how to create and configure a box product in WooCommerce with BoxBuilder.
A box product is a standard WooCommerce Simple Product with BoxBuilder enabled. This means it works with all existing WooCommerce features — shipping, taxes, coupons, and more.
## Create the Product
Go to **Products → Add New** in your WordPress admin.
Fill in the standard WooCommerce fields:
* **Product name**: e.g., "Build Your Own Chocolate Box"
* **Description**: Describe the box experience for your customers
* **Short description**: A brief summary shown on the product page
* **Product image**: The main box image customers will see
* **Product gallery**: Additional images of the box or example configurations
In the **General** tab of the Product Data panel:
* For **Fixed pricing**: Set the price you want to charge for the box (e.g., \$29.99)
* For **Per-item pricing**: Set the price to 0 — the total will be calculated from the selected items
Click the **BoxBuilder** tab in the Product Data panel. Check **Enable BoxBuilder**.
## Configure the Box
Once BoxBuilder is enabled, you'll see the configuration options:
### Capacity
| Setting | Description |
| ----------------- | --------------------------------------------------------------------------- |
| **Capacity Type** | **Fixed** — exact number of items. **Range** — minimum and maximum. |
| **Max Items** | Maximum number of items the box can hold (e.g., 12) |
| **Min Items** | Minimum items required (only shown for Range type) |
| **Allow Partial** | If enabled, customers can add the box to cart without filling it completely |
Use **Range** capacity when you want flexibility. For example, a box that holds 6–12 items lets customers choose how full they want their box.
### Pricing Model
| Model | How It Works | Best For |
| --------------- | ------------------------------------------------ | ------------------------------------------------ |
| **Fixed Price** | One price for the whole box, regardless of items | Gift boxes with a set price point |
| **Per-Item** | Total = sum of each item's price | Build-your-own where items have different values |
**Hybrid pricing** (base price + per-item) is available in [BoxBuilder Pro](/plugins/boxbuilder/pricing-models).
### Product Source
Choose which products customers can pick from:
| Source | Description |
| --------------------- | --------------------------------------------- |
| **All Products** | Every published, in-stock WooCommerce product |
| **By Category** | Only products from selected categories |
| **Specific Products** | Hand-picked individual products |
Using **By Category** is the most common approach. Create categories like "Chocolates", "Sweets", "Nuts" and assign your products to them. Then select those categories as the product source for your box.
### Layout
| Option | Description |
| --------------------- | ---------------------------------------------------------- |
| **Layout Style** | **Grid** (card-based) or **List** (compact rows) |
| **Products Per Page** | Number of products to show before pagination (default: 12) |
### Gift Message
Gift messages are controlled globally in **BoxBuilder → Settings → Gift Message** tab. When enabled, a text field appears in the box builder for customers to type a personal message.
## Box Overview in Admin
After creating box products, you can manage them from **BoxBuilder → All Boxes**. This page shows:
* All products with BoxBuilder enabled
* Capacity and pricing model for each box
* Quick links to edit or view each box
## Example Configurations
* Capacity: Fixed, 12 items
* Pricing: Fixed Price
* Product price: \$29.99
* Product source: Category "Chocolates"
* Layout: Grid
* Gift message: Enabled
* Capacity: Range, 6–12 items
* Pricing: Per-Item
* Product price: \$0.00
* Product source: Categories "Chips", "Cookies", "Drinks"
* Layout: Grid
* Allow partial: Yes
* Capacity: Fixed, 8 items
* Pricing: Fixed Price
* Product price: \$49.99
* Product source: Specific products (hand-picked flowers)
* Layout: Grid
* Gift message: Enabled
## Next Steps
* [Product Selection](/plugins/boxbuilder/product-selection) — control which products appear and how
* [Pricing Models](/plugins/boxbuilder/pricing-models) — detailed pricing configuration
* [Gift Messages](/plugins/boxbuilder/gift-messages) — customize the gift message experience
# Custom Items
Source: https://docs.swiftlywp.com/plugins/boxbuilder/custom-items
Create text-based items that don't need WooCommerce products.
Custom Items is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
Custom Items mode lets you create box items as simple text entries with prices — no WooCommerce products required. This is ideal for businesses where the items don't need individual product pages, stock tracking, or shipping calculations.
## When to Use Custom Items
| Use Case | Example |
| --------------------- | ------------------------------------------------------------------ |
| **Food service** | Pizza toppings, sandwich fillings, salad ingredients |
| **Services** | Spa treatments, workshop add-ons |
| **Simple gift boxes** | Items that are only sold as part of a box, never individually |
| **Quick setup** | When you want to launch fast without creating WooCommerce products |
## Setting Up Custom Items
Edit your box product and go to the **BoxBuilder** tab. Check **Enable BoxBuilder**.
Set **Product Source** to **Custom Items**.
Add groups (like categories) to organize your items. For example:
* "Chocolates"
* "Sweets"
* "Dried Fruits"
For each group, add items with:
* **Name**: The item name customers see
* **Price**: The price for this item (used with per-item or hybrid pricing)
## Custom Items vs WooCommerce Products
| Feature | Custom Items | WooCommerce Products |
| ---------------------- | ------------ | -------------------- |
| Requires product pages | No | Yes |
| Stock tracking | No | Yes |
| Product images | No | Yes |
| Individual product SEO | No | Yes |
| Setup speed | Fast | Standard |
| Reusable across boxes | Per-box only | Yes |
If you need stock tracking, product images, or want items to also be sold individually, use WooCommerce products as your product source instead.
## How Custom Items Work in Cart & Orders
Custom items appear in the cart and order just like regular product-based box items. The item name and price are displayed in:
* Cart page
* Order confirmation
* Order emails
* Admin order screen
# Data Storage
Source: https://docs.swiftlywp.com/plugins/boxbuilder/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.
# FAQ
Source: https://docs.swiftlywp.com/plugins/boxbuilder/faq
Frequently asked questions about BoxBuilder for WooCommerce.
## General
Yes. BoxBuilder is designed to work with any well-coded WordPress theme. It's tested with Storefront, Astra, GeneratePress, Flatsome, OceanWP, Divi, and Avada. All styles are namespaced under `.boxbuilder-wrap` to prevent conflicts.
Yes. You can create as many box products as you want, each with its own configuration — different capacities, product sources, pricing models, and layouts. There's no limit in either the Free or Pro version.
No. BoxBuilder stores all data using standard WordPress and WooCommerce storage (post meta, order item meta, user meta, wp\_options). This ensures full compatibility with backup plugins, migration tools, and the WooCommerce ecosystem.
Yes. A product can be included in as many different box configurations as you want. Stock is shared — if a product has 10 units, those 10 units are available across all boxes.
Yes. BoxBuilder is compatible with the WooCommerce block-based cart and checkout. It also includes a native Gutenberg block for embedding the builder in pages.
## Pricing & Stock
Each item in the box is added to the WooCommerce cart as a hidden sub-item. WooCommerce handles stock reduction for each individual product at checkout. If a product goes out of stock, it's automatically hidden from the builder.
In the free version, you can achieve this with fixed pricing — set a box price that's less than the total of individual items. BoxBuilder Pro adds quantity-based discounts and bundle discount features.
Yes. Standard WooCommerce coupons work with box products. For fixed-price boxes, the coupon applies to the box price. For per-item boxes, coupons can apply to individual item prices.
Yes. BoxBuilder uses standard WooCommerce pricing and cart calculations, so your existing tax configuration applies automatically.
## Features
Yes. Gift messages are built into the free version. Enable them in **BoxBuilder → Settings → Gift Message**. The message is saved with the order and included in order emails.
Yes. Use the `[boxbuilder id="123"]` shortcode or the Gutenberg block to place the builder on any page or post.
Yes. The builder includes quantity controls (+/-) so customers can add multiple units of the same product to their box, up to the box capacity.
All hidden sub-items (the individual products in the box) are automatically removed along with the parent box item. There's no way for orphaned items to remain.
Yes. Enable **Allow Partial** in the box configuration. Customers can add the box to cart with fewer items than the maximum capacity. You can also set a minimum with range-based capacity.
## Pro
The free version includes everything needed to run a box-building experience: box products, fixed/per-item pricing, layouts, gift messages, and full WooCommerce integration. Pro adds multiple box sizes, category filters, custom items, hybrid pricing, analytics, saved boxes, shareable URLs, subscription mode, and multi-currency support. See the [full comparison](/plugins/boxbuilder/pro-overview).
Yes. All your box configurations, settings, and order data are preserved when upgrading. Simply deactivate the free version, install Pro, and activate your license.
No. The free version is fully functional for a store that needs basic box-building with fixed or per-item pricing. Many stores run successfully on the free version.
No. BoxBuilder detects if both versions are installed and only loads one. You should deactivate and delete the version you're not using.
## Technical
WordPress 6.0+, WooCommerce 7.0+, and PHP 7.4+. We recommend the latest versions of WordPress and WooCommerce with PHP 8.1+.
Yes. All strings use the `boxbuilder-wc` text domain. A `.pot` file is included for translations. BoxBuilder Pro also supports WPML for full multilingual support.
BoxBuilder Pro includes a template override system. Copy templates from the plugin's `/templates/` directory to your theme's `boxbuilder/` folder to customize the HTML. See [Template Overrides](/plugins/boxbuilder/template-overrides).
BoxBuilder Pro includes REST API endpoints under the `boxbuilder/v1` namespace. See [REST API](/plugins/boxbuilder/rest-api).
# Gift Messages
Source: https://docs.swiftlywp.com/plugins/boxbuilder/gift-messages
Let customers add personal gift messages to their boxes.
BoxBuilder includes a built-in gift message feature. When enabled, customers can type a personal message that's stored with the order and shown in confirmation emails.
## Enable Gift Messages
Gift messages are controlled globally in **BoxBuilder → Settings → Gift Message** tab.
| Setting | Description | Default |
| ----------------------- | ----------------------------------------------------- | --------------------------- |
| **Enable Gift Message** | Show the gift message field in the box builder | Enabled |
| **Required** | Make the gift message mandatory before adding to cart | No |
| **Label** | The label shown above the text field | "Gift Message" |
| **Placeholder** | Placeholder text inside the field | "Add a personal message..." |
| **Max Length** | Maximum number of characters allowed | 500 |
## How It Works
1. Customer sees a text field in the box builder (below the box summary)
2. They type their personal message
3. When the box is added to cart, the message is stored with the cart item
4. At checkout, the message is saved as order item meta
5. The message appears in:
* Order confirmation page
* Order confirmation email
* Admin order screen (**WooCommerce → Orders → Edit Order**)
* Customer's **My Account → Orders** history
## Customizing the Label
You can change the gift message label and placeholder text in **BoxBuilder → Settings → Labels** tab, or in the **Gift Message** tab for the specific label and placeholder.
## Where the Message Appears
| Location | Visible To |
| ------------------------------------- | --------------- |
| Cart page | Customer |
| Checkout page | Customer |
| Order confirmation page | Customer |
| Order confirmation email | Customer |
| Admin order screen | Store admin |
| Packing slip (with compatible plugin) | Warehouse staff |
The gift message is stored as WooCommerce order item meta (`_boxbuilder_message`), so it's accessible to any plugin that reads order item meta — including packing slip and PDF invoice plugins.
## Developer: Accessing the Gift Message
```php theme={null}
// Get gift message from an order item
$message = $item->get_meta( '_boxbuilder_message' );
// Filter the gift message before saving
add_filter( 'boxbuilder/gift_message', function( $message, $box_id ) {
// Modify or validate the message
return $message;
}, 10, 2 );
```
# Hooks & Filters
Source: https://docs.swiftlywp.com/plugins/boxbuilder/hooks-and-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` Pro
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` Pro
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` Pro
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` Pro
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` Pro
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 .= ' per box';
}
return $price_html;
}, 10, 3 );
```
### `boxbuilder/default_sizes` Pro
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 );
```
# Installation
Source: https://docs.swiftlywp.com/plugins/boxbuilder/installation
Install BoxBuilder for WooCommerce on your WordPress site.
## Installing the Free Version
In your WordPress admin, navigate to **Plugins → Add New**.
Type **"BoxBuilder for WooCommerce"** in the search box.
Click **Install Now**, then click **Activate**.
Download `boxbuilder-for-woocommerce.zip` from [WordPress.org](https://wordpress.org/plugins/boxbuilder-for-woocommerce/).
Go to **Plugins → Add New → Upload Plugin**. Choose the ZIP file and click **Install Now**.
Click **Activate Plugin**.
## Installing BoxBuilder Pro
Get your Pro license at [swiftlywp.com/plugin/boxbuilder-for-woocommerce](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/).
After purchase, download `boxbuilder-pro.zip` from your [SwiftlyWP account](https://app.swiftlywp.com).
Go to **Plugins → Add New → Upload Plugin**. Choose the Pro ZIP file, click **Install Now**, then **Activate**. If the free version is installed, BoxBuilder will automatically deactivate it — no manual step needed.
Go to **BoxBuilder → License** and enter your license key. Click **Activate**.
BoxBuilder automatically prevents both versions from running at the same time. When you activate Pro, the free version is deactivated automatically. You can safely delete the free version afterward.
## Upgrading from Free to Pro
When you upgrade from Free to Pro:
* All your box configurations are preserved
* All settings are kept
* Order history with box data remains intact
* No data is lost during the switch
Simply install and activate Pro — the free version is deactivated automatically. Then enter your license key at **BoxBuilder → License**.
## Updating BoxBuilder
### Free Version
Updates are delivered automatically through WordPress.org. You'll see update notifications in **Dashboard → Updates** and on the **Plugins** page.
### Pro Version
Pro updates are delivered through your license. When a new version is available:
1. You'll see an update notification on the **Plugins** page
2. Click **Update Now** to install the latest version
3. Your license must be active to receive updates
Keep your license active to receive updates and priority support. You can manage your license at **BoxBuilder → License**.
## Requirements
| Requirement | Minimum | Recommended |
| ----------- | ------- | ----------- |
| WordPress | 6.0+ | Latest |
| WooCommerce | 7.0+ | Latest |
| PHP | 7.4+ | 8.1+ |
BoxBuilder will automatically deactivate if WooCommerce is not installed. You'll see an admin notice with a direct link to install or activate WooCommerce.
## After Installation
Once BoxBuilder is activated, you'll see a new **BoxBuilder** menu in your WordPress admin sidebar (right below WooCommerce). Head to the [Quickstart guide](/plugins/boxbuilder/quickstart) to create your first box.
# Introduction
Source: https://docs.swiftlywp.com/plugins/boxbuilder/introduction
Build custom gift boxes, mix-and-match bundles, and curated product boxes for your WooCommerce store.
BoxBuilder for WooCommerce lets your customers build their own product boxes — pick items, fill the box, and add it to cart as a single product. Perfect for gift boxes, candy boxes, sample packs, hampers, and any "build your own" experience.
## What is BoxBuilder?
BoxBuilder is a WooCommerce plugin by [SwiftlyWP](https://swiftlywp.com) that adds a visual box builder to any WooCommerce product. Your customers browse available products, add items to their box, and checkout — all without leaving the product page.
Get BoxBuilder set up on your WordPress site in under 2 minutes.
Build your first box in 5 minutes.
Explore box configuration, pricing models, and display options.
Hooks, filters, template overrides, and REST endpoints.
## Who is it for?
* **Gift shops & candy stores** — let customers pick chocolates, sweets, or treats to fill a gift box
* **Florists** — build your own bouquet from available flowers
* **Subscription box companies** — let subscribers customize their monthly box
* **Food & beverage** — sample packs, cheese boards, coffee selections
* **Corporate gifting** — branded gift hampers with curated product choices
* **Any WooCommerce store** that wants a "build your own" product experience
## Free vs Pro
BoxBuilder comes in two versions:
Everything you need to launch a box-building experience:
* Create box products with fixed or range-based capacity
* Fixed price or per-item pricing
* Grid and list layouts
* Gift message support
* Full cart, order, and email integration
* Shortcode and Gutenberg block
* Mobile responsive
* Customizable labels, colors, and appearance
* 6 settings tabs with full control
[Download Free on WordPress.org →](https://wordpress.org/plugins/boxbuilder-for-woocommerce/)
Everything in Free, plus:
* Multiple box sizes (Small / Medium / Large)
* Category filter tabs in product picker
* Custom text-based items (no WooCommerce products needed)
* Hybrid pricing (base price + per-item)
* Analytics dashboard with revenue, fill rates, and popular items
* Save boxes for later (logged-in users)
* Shareable box URLs
* Subscription box mode (with WooCommerce Subscriptions)
* Multi-currency and WPML support
* Priority support
[Get BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
## Requirements
* WordPress 6.0 or higher
* WooCommerce 7.0 or higher
* PHP 7.4 or higher
BoxBuilder requires WooCommerce to be installed and activated. If WooCommerce is not active, BoxBuilder will deactivate itself and show a helpful notice with a link to install or activate WooCommerce.
## How it works
At a high level, BoxBuilder works like this:
Create a standard WooCommerce product and enable BoxBuilder on it. Configure the capacity, pricing model, and which products customers can choose from.
On the product page, customers see a visual builder with a product grid and a box summary panel. They browse, search, and add items until their box is full.
The completed box is added to the WooCommerce cart as a single line item. Box contents are shown in the cart, order confirmation, and emails.
Under the hood, BoxBuilder uses WooCommerce's native cart and order system — no custom database tables. Each item in the box is tracked as a hidden sub-item for proper stock management, while the customer only sees one clean "box" line item.
# Inventory Management
Source: https://docs.swiftlywp.com/plugins/boxbuilder/inventory
How BoxBuilder handles stock for individual products in boxes.
BoxBuilder works with WooCommerce's native inventory system. Each product in a box has its own stock level, and BoxBuilder respects those stock levels throughout the customer experience.
## How Stock Works
1. **Product picker**: Out-of-stock products are handled based on your Display settings (hidden, shown with badge, or shown without indicator)
2. **Add to cart**: Each selected product is added as a hidden cart item — WooCommerce tracks stock for each
3. **Checkout**: WooCommerce reduces stock for every individual product in the box
4. **Refund/cancel**: Stock is restored through standard WooCommerce order management
BoxBuilder does not manage stock separately. It relies entirely on WooCommerce's built-in stock management. If a product has stock tracking enabled in WooCommerce, BoxBuilder respects it.
## Out-of-Stock Handling
You can control how out-of-stock products appear in the builder via **BoxBuilder → Settings → Display** under **Stock Management**:
| Option | Description |
| ------------------------------ | -------------------------------------------------------------------------------------- |
| **Show all (no indicator)** | Out-of-stock products appear normally — no badge or restriction |
| **Show with badge (disabled)** | Products are visible but grayed out with a badge — customers cannot add them (default) |
| **Hide completely** | Out-of-stock products are removed from the product grid entirely |
You can also set a **Low Stock Threshold** (default: 5). When a product's stock is at or below this number, an "Only X left!" badge appears on the product card.
If a product goes out of stock while a customer is building their box (another customer purchased the last unit), the stock check happens again at checkout and WooCommerce will prevent the order if stock is insufficient.
## Stock Reduction at Checkout
When an order is placed:
| Item | Stock Reduced? |
| ------------------------- | -------------------------------------------------------------- |
| Box product (parent) | Only if stock tracking is enabled on the box product |
| Selected items (children) | Yes — each product's stock is reduced by the quantity selected |
This means if a customer builds a box with 3x Chocolate Truffles and 2x Vanilla Fudge, stock is reduced by 3 and 2 respectively for those products.
## Stock Restoration
When an order is cancelled or refunded:
* WooCommerce restores stock for each individual product
* Standard WooCommerce "Restore stock" behavior applies
## Pro: Enhanced Inventory Features
The following features are available in [BoxBuilder Pro](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/).
* **Low stock warnings**: "Only 3 left" badge on product cards in the builder
* **Stock reserve on add-to-cart**: Prevents overselling by reserving stock when the box is added to cart (before checkout)
* **Admin low stock alerts**: Notifications when items used in active boxes drop below a threshold
# Layouts & Display
Source: https://docs.swiftlywp.com/plugins/boxbuilder/layouts
Configure how the box builder looks on the frontend.
BoxBuilder offers multiple layout options for the product picker and box summary. You can configure these per box product and globally in settings.
## Product Grid Layouts
### Grid Layout
Products are displayed as cards in a responsive grid. Each card shows the product image, name, price, and an Add to Box button.
Configure in **BoxBuilder → Settings → General** under **Product Layout**:
| Setting | Description | Default |
| --------------------- | ------------------------------------ | ------- |
| **Layout Style** | Grid or List | Grid |
| **Products per page** | Number of products before pagination | 12 |
Grid layout works best for visual browsing (e.g., chocolates, flowers). Recommended: 8–16 products per page for optimal performance.
### List Layout
Products are shown as compact horizontal rows. Each row has a small thumbnail, product name, price, and add button. List layout fits more products in less vertical space.
Best for boxes with many items where customers need to scan quickly.
## Box Summary Panel
The summary panel shows what the customer has added to their box. It includes:
* Selected items with names and quantities
* Running total price
* Progress indicator (e.g., "6 of 12 items")
* Gift message field (if enabled)
* Add to Cart button
### Summary Position
Configure in **BoxBuilder → Settings → General** under **Builder Position**:
| Position | Description |
| -------------- | -------------------------------------------------------------- |
| **Right Side** | Summary panel on the right, product grid on the left (default) |
| **Left Side** | Summary panel on the left, product grid on the right |
### Summary Display Mode
Configure in **BoxBuilder → Settings → General** under **Box Summary**:
| Mode | Description |
| ------------- | ----------------------------------------------------------- |
| **List View** | Items shown as a simple list with quantities (default) |
| **Slot Grid** | Items shown as visual slots that fill up as items are added |
| **Minimal** | Compact view with just item names and counts |
**Slot Grid** mode creates a visual "filling up" experience — great for gift boxes where seeing the box fill adds to the shopping experience.
## Progress Indicator
The progress indicator shows customers how many items they've added and how many more they need. Configure in **BoxBuilder → Settings → General** under **Progress Indicators**.
| Style | Description |
| -------------------- | ------------------------------------------------ |
| **Progress Bar** | A visual bar that fills up (default) |
| **Percentage (50%)** | Displays completion as a percentage |
| **Slot Dots** | Individual dots for each slot |
| **Counter (6/12)** | Shows a simple fraction of items added vs. total |
You can also enable an "almost full" encouragement message (e.g., "Add 3 more items!") using the `{count}` placeholder.
## Mobile Display
BoxBuilder is mobile-responsive out of the box. Configure mobile settings in **BoxBuilder → Settings → General** under **Mobile**.
| Setting | Options | Default |
| ---------------------- | ------------------------------ | -------------- |
| **Mobile Layout** | Stacked, Tabbed (switch views) | Stacked |
| **Summary Position** | Below Products, Above Products | Below Products |
| **Sticky Add to Cart** | Checkbox | Enabled |
When **Stacked** is selected, products and the summary are displayed vertically. **Tabbed** mode lets customers switch between "Products" and "Your Box" views — ideal when screen space is limited. The **Sticky Add to Cart** keeps the button fixed at the bottom of the screen on mobile.
## Quantity Controls
Control how quantity buttons (+/-) appear on product cards. Configure in **BoxBuilder → Settings → General** under **Interaction**.
| Setting | Description |
| ------------------- | ---------------------------------------------------------------- |
| **Always visible** | Quantity controls shown on every card at all times (default) |
| **On hover** | Quantity controls appear when hovering over a card |
| **After First Add** | Quantity controls appear only after the item has been added once |
## Add Mode
| Mode | Description |
| ---------------- | ------------------------------------------------------------------ |
| **Button Click** | Customer clicks the "Add to Box" button to add items (default) |
| **Card Click** | Customer clicks anywhere on the product card to add it (quick add) |
| **Both** | Either method works — button click or card click |
"Card Click" mode is faster for high-volume stores where customers add many items quickly. "Both" gives customers the flexibility to use either method.
## Narrow Container Support
BoxBuilder uses CSS container queries to automatically adapt when placed in narrow containers (like sidebars or small Elementor columns). The layout adjusts columns and spacing to fit the available width.
## Related
* [Appearance](/plugins/boxbuilder/appearance) — colors, borders, and shadows
* [Builder Position](/plugins/boxbuilder/builder-position) — where the builder appears on the product page
* [Settings](/plugins/boxbuilder/settings) — full settings reference
# Multi-Currency & WPML
Source: https://docs.swiftlywp.com/plugins/boxbuilder/multi-currency
Translation support and multi-currency compatibility for international stores.
Multi-currency and WPML support is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro supports internationalization through standard WordPress translation tools. Dedicated multi-currency switcher integration is on the roadmap.
## Translation Support
All plugin strings use the `boxbuilder-wc` text domain and are fully translatable using standard WordPress tools:
* [Loco Translate](https://wordpress.org/plugins/loco-translate/)
* [Poedit](https://poedit.net/)
* WordPress.org translation system (for the free version)
A `.pot` file is included at `/languages/boxbuilder-for-woocommerce.pot` containing all translatable strings — labels, button text, messages, and admin settings.
### What Can Be Translated
* Box builder UI labels (Add to Box, Remove, Your Box, etc.)
* Gift message labels and placeholders
* Progress indicator text
* Cart and order display text
* Admin settings and page titles
## Currency Display
BoxBuilder reads your store's WooCommerce currency settings and displays prices correctly in your configured currency. This includes:
* Currency symbol and position (before/after price)
* Decimal and thousands separators
* Number of decimal places
All prices in the builder — product cards, summary panel, and totals — follow your WooCommerce currency configuration.
## Coming Soon
The following features are planned for a future release and are **not yet available**:
### Multi-Currency Switcher Integration
Dedicated compatibility with popular currency switcher plugins:
| Plugin | Status |
| --------------------------------- | ------- |
| **Fox – Currency Switcher** | Planned |
| **WooCommerce Multi-Currency** | Planned |
| **WPML WooCommerce Multilingual** | Planned |
This will allow prices in the box builder to update automatically when the customer switches currency.
### WPML Integration
Deeper integration with [WPML](https://wpml.org/) for:
* Registering custom strings with WPML String Translation
* Language-aware product filtering in the box builder
* Translated box configurations per language
### RTL Support
Full RTL (right-to-left) layout support for languages like Arabic, Hebrew, and Persian.
# Orders & Emails
Source: https://docs.swiftlywp.com/plugins/boxbuilder/orders-and-emails
How box contents are stored in orders and displayed in emails.
When a customer checks out with a box product, the box contents are preserved in the WooCommerce order and included in all relevant emails.
## Order Storage
Box data is stored using standard WooCommerce order item meta:
* **Parent order item**: The box product with meta `_boxbuilder_is_box = yes`
* **Child order items**: Each selected product, linked to the parent via `_boxbuilder_part_of_box`
* **Gift message**: Stored as `_boxbuilder_message` on the parent order item
This means box data is:
* Backed up with standard WordPress/WooCommerce backups
* Accessible to any plugin that reads order item meta
* Preserved through order status changes
## Admin Order Screen
When viewing an order in **WooCommerce → Orders**, box orders show:
* The box product as a line item
* Box contents listed as sub-items beneath the parent
* Gift message displayed with the box item
* Each child item with its product name and quantity
Click on any child item to go to its WooCommerce product page. This makes it easy to check stock or edit individual products.
## Customer-Facing Displays
### Order Confirmation Page (Thank You Page)
After checkout, the order confirmation page shows:
* Box product name
* Box contents listed
* Gift message (if provided)
### My Account → Orders
In the customer's account area, past orders show box contents when the order is expanded. Customers can see exactly what was in each box.
### Order Emails
Box contents are included in these WooCommerce emails:
| Email | Sent To | Box Contents Shown |
| ---------------------- | -------- | ------------------ |
| **New Order** | Admin | Yes |
| **Order Confirmation** | Customer | Yes |
| **Processing Order** | Customer | Yes |
| **Completed Order** | Customer | Yes |
| **Refunded Order** | Customer | Yes |
The gift message is also included in order emails.
## Packing Slip Integration
Because box items are stored as standard WooCommerce order items, they're automatically visible to packing slip plugins:
* **WooCommerce PDF Invoices & Packing Slips** — child items appear on packing slips
* **YITH WooCommerce PDF Invoices** — compatible
BoxBuilder Pro includes enhanced packing slip formatting that groups child items visually under their parent box.
## Refunds
When refunding a box order:
* Refunding the parent box item refunds the box price
* Stock for individual items can be restored through standard WooCommerce refund controls
* Partial refunds work as expected
## Related
* [Cart Integration](/plugins/boxbuilder/cart-integration) — how boxes work in the cart
* [Inventory](/plugins/boxbuilder/inventory) — stock management for box items
# Pricing Models
Source: https://docs.swiftlywp.com/plugins/boxbuilder/pricing-models
Understand the pricing options available for your box products.
BoxBuilder supports multiple pricing models to fit different business needs. The pricing model is set per box product in the **BoxBuilder** tab of the product editor.
## Fixed Price
The box has one set price regardless of which items the customer selects.
**How it works:**
* You set the product price in the WooCommerce **General** tab (e.g., \$29.99)
* Customer selects any combination of items
* The total is always the product price — \$29.99
**Best for:**
* Gift boxes with a set price point
* "Pick any 12 for \$29.99" style offers
* Boxes where all items have similar value
**How stock works:**
Each selected item is added to the cart as a hidden sub-item with a price of \$0. WooCommerce still reduces stock for each individual product when the order is placed.
## Per-Item Pricing
The box total is the sum of each selected item's price.
**How it works:**
* Set the box product price to **\$0.00** (the product itself has no base cost)
* Each item the customer adds contributes its own price to the total
* The price updates live as items are added or removed
**Best for:**
* Build-your-own boxes where items have different values
* Custom assortments with premium and standard options
* When you want transparent, item-level pricing
**How stock works:**
Each selected item is added to the cart as a hidden sub-item at its regular WooCommerce price.
## Hybrid Pricing
Hybrid pricing is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
Combines a base box price with per-item pricing.
**How it works:**
* You set a base price for the box itself (e.g., \$10.00 for the packaging)
* Each item adds its own price on top
* Total = base price + sum of item prices
**Best for:**
* Premium packaging with a separate cost
* Boxes where the container itself has value (wooden crate, branded box)
* When you want to charge for the box and the contents separately
## Price Display
The box summary panel shows a live-updating price as the customer adds items:
| Pricing Model | What Customer Sees |
| ------------- | ------------------------------------------------------------- |
| Fixed | "Total: \$29.99" (doesn't change) |
| Per-Item | "Total: $0.00" → "$4.99" → "\$12.47" (updates with each item) |
| Hybrid | "Box: $10.00 + Items: $4.99 = Total: \$14.99" |
You can control whether individual item prices are shown in the summary panel via **BoxBuilder → Settings → Display → Show prices in summary**.
## Pricing and Cart
When a box is added to the cart, WooCommerce handles the pricing natively:
* **Fixed price**: The parent box item has the full price. Child items are set to \$0.
* **Per-item**: The parent box item is \$0. Each child item has its own price.
* **Hybrid**: The parent box has the base price. Each child item has its own price.
This means coupons, taxes, and shipping all work correctly with WooCommerce's built-in calculations.
## Related
* [Creating a Box Product](/plugins/boxbuilder/creating-a-box) — full box setup guide
* [Cart Integration](/plugins/boxbuilder/cart-integration) — how boxes appear in the cart
* [Settings](/plugins/boxbuilder/settings) — price display options in settings
# Pro Features Overview
Source: https://docs.swiftlywp.com/plugins/boxbuilder/pro-overview
Everything included in BoxBuilder Pro.
BoxBuilder Pro includes everything in the free version plus powerful features for growing stores.
[Get BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
## Pro Features at a Glance
Offer Small, Medium, and Large sizes with different capacities and prices.
Clickable category tabs above the product grid for easy browsing.
Text-based items that don't need WooCommerce products.
Base box price plus per-item pricing combined.
Revenue, popular items, fill rates, and top-selling boxes.
Customers save boxes and come back later to finish.
Share a pre-filled box via a unique link.
Monthly/quarterly customizable subscription boxes.
WPML and currency switcher compatibility.
## Free vs Pro Comparison
| Feature | Free | Pro |
| ---------------------------- | --------- | --------- |
| Box products | Unlimited | Unlimited |
| Fixed & Per-Item pricing | Yes | Yes |
| Hybrid pricing | — | Yes |
| Grid & List layouts | Yes | Yes |
| Gift messages | Yes | Yes |
| Shortcode & Block | Yes | Yes |
| Customizable labels & colors | Yes | Yes |
| Mobile responsive | Yes | Yes |
| Cart/Order/Email integration | Yes | Yes |
| Multiple box sizes | — | Yes |
| Category filter tabs | — | Yes |
| Custom text-based items | — | Yes |
| Analytics dashboard | — | Yes |
| Save boxes for later | — | Yes |
| Shareable box URLs | — | Yes |
| Subscription box mode | — | Yes |
| Multi-currency support | — | Yes |
| WPML compatibility | — | Yes |
| Low stock warnings | — | Yes |
| Stock reservation | — | Yes |
| Priority support | — | Yes |
## Pricing
Visit [swiftlywp.com/plugin/boxbuilder-for-woocommerce](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/) for current pricing.
## Upgrading
See the [Installation guide](/plugins/boxbuilder/installation) for step-by-step upgrade instructions. All your existing box configurations and settings are preserved when upgrading.
# Product Selection
Source: https://docs.swiftlywp.com/plugins/boxbuilder/product-selection
Control which products appear in the box builder and how they're displayed.
The product picker is the main interface customers use to browse and add items to their box. You can control exactly which products appear, how many are shown, and how they're displayed.
## Product Source Options
When editing a box product, the **Product Source** setting in the BoxBuilder tab controls which products customers can choose from.
### All Products
Every published, in-stock product in your WooCommerce store will appear in the picker. This is the simplest option but may not be ideal if you have products that don't belong in a box (e.g., shipping supplies, gift cards).
### By Category
Select one or more WooCommerce product categories. Only products in those categories will appear.
This is the **recommended approach** for most stores. Create dedicated categories for your box items:
| Category | Example Products |
| ---------- | ------------------------------------- |
| Chocolates | Dark Truffle, Milk Bar, White Praline |
| Sweets | Gummy Bears, Lollipop, Hard Candy |
| Nuts | Cashews, Almonds, Pistachios |
You can use the same product in multiple boxes. A "Dark Truffle" product can appear in both a "Chocolate Box" and a "Premium Gift Hamper" — just include the "Chocolates" category in both box configurations.
### Specific Products
Hand-pick individual products by searching and selecting them. Best for curated boxes where you want precise control over the available items.
## Display Settings
These settings control how products appear in the picker. Configure in **BoxBuilder → Settings → General** under **Product Layout**:
| Setting | Options | Default |
| --------------------- | ---------- | ------- |
| **Layout Style** | Grid, List | Grid |
| **Products Per Page** | Any number | 12 |
### Grid Layout
Products are shown as cards with image, name, price, and an **Add to Box** button. Grid layout is the most visual and works best when your products have good images.
### List Layout
Products are shown as compact horizontal rows with a thumbnail, name, price, and add button. List layout fits more products in less space and works well when you have many items.
## Product Cards
Each product in the picker displays:
* **Product image** — uses the WooCommerce product thumbnail
* **Product name**
* **Price** — the regular or sale price
* **Add to Box button** — adds one unit to the box
* **Stock indicators** — out-of-stock products can be hidden, shown with a badge, or shown without indicator (configured in [Settings → Display](/plugins/boxbuilder/settings#display))
* **Low stock badge** — "Only X left!" badge when stock is low (configurable threshold)
By default, out-of-stock products are shown with a badge but disabled — customers can see them but cannot add them. You can change this behavior in **BoxBuilder → Settings → Display** under **Stock Management**.
## Search
The product picker includes a search field that filters products by name. Customers can type to quickly find specific items without scrolling through the full grid.
Search works with AJAX — results update as the customer types, without reloading the page.
## Pagination
When you have more products than the **Products Per Page** setting, the picker shows pagination controls. Products are loaded via AJAX for a smooth browsing experience.
## Category Filtering
Category filter tabs are a [Pro feature](/plugins/boxbuilder/category-filters). In the free version, all products from the selected source are shown together.
With BoxBuilder Pro, clickable category tabs appear above the product grid. Customers can filter by category (e.g., "Chocolates | Sweets | Nuts | All") to quickly find what they want.
# Quickstart
Source: https://docs.swiftlywp.com/plugins/boxbuilder/quickstart
Create your first box product in 5 minutes.
This guide walks you through creating a box product, configuring it, and seeing it live on your store.
## Before You Start
Make sure you have:
* BoxBuilder installed and activated ([Installation guide](/plugins/boxbuilder/installation))
* WooCommerce installed with at least a few products in your store
* Products with prices and images set up
## Create Your First Box
Go to **Products → Add New** in your WordPress admin. Give your product a name (e.g., "Build Your Own Gift Box"), set a price, and add a featured image.
For **fixed pricing**, the product price is the box price regardless of items selected. For **per-item pricing**, set the product price to 0 — the total will be calculated from the items the customer picks.
In the **Product Data** panel, click the **BoxBuilder** tab. Check the **Enable BoxBuilder** checkbox.
Choose your capacity type:
* **Fixed**: Exact number of items (e.g., 12)
* **Range**: Minimum and maximum (e.g., 6 to 12 items)
Toggle **Allow partial boxes** if customers can check out without filling the box completely.
* **Fixed Price**: The product price applies regardless of which items are selected
* **Per-Item**: Price is the sum of all selected items
Choose which products customers can add to this box:
* **All Products**: Every published product in your store
* **By Category**: Products from specific categories (e.g., "Chocolates", "Sweets")
* **Specific Products**: Hand-pick individual products
Select **Grid** or **List** for the product picker display. Set the number of products per page (default: 12).
Click **Publish**. Your box product is now live.
## View Your Box
Visit the product page on your store's frontend. You'll see the BoxBuilder interface with:
* A **product grid** showing available items with images, names, and prices
* An **Add to Box** button on each product card
* A **box summary panel** showing selected items and the running total
* A **progress counter** showing how many items have been added (e.g., "3 of 12")
* An **Add to Cart** button that becomes active once the box meets the minimum capacity
## Test the Full Flow
Click **Add to Box** on several products. Watch the summary panel update with each item, and the progress counter increment.
Keep adding items until you reach the capacity. The progress indicator will show the box is complete.
If gift messages are enabled in settings, type a message in the gift message field.
Click **Add to Cart**. You'll be taken to the cart page (or stay on the page, depending on your settings).
In the cart, you'll see your box as a single line item. The box contents are shown beneath it.
Proceed through checkout. After placing the order, check:
* The order confirmation page shows box contents
* The order confirmation email includes box contents
* The admin order screen (**WooCommerce → Orders**) shows the box with all items
You've created and tested your first box product. Next, explore [pricing models](/plugins/boxbuilder/pricing-models), [display settings](/plugins/boxbuilder/layouts), or the full [settings reference](/plugins/boxbuilder/settings).
## Next Steps
Fixed price, per-item, or hybrid pricing.
Grid, list, summary panel, and mobile options.
Full reference of all 6 settings tabs.
Enable and customize gift messages.
# REST API
Source: https://docs.swiftlywp.com/plugins/boxbuilder/rest-api
REST API endpoints and AJAX handlers for custom integrations.
REST API endpoints are a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro provides REST API endpoints for sharing functionality, and AJAX handlers for all other frontend operations.
## REST API Endpoints
REST endpoints are registered under the `boxbuilder/v1` namespace.
### Create Share Link
```
POST /wp-json/boxbuilder/v1/share
```
Creates a shareable link for a box configuration. Requires the user to be logged in.
**Request body:**
```json theme={null}
{
"box_id": 123,
"items": [
{ "product_id": 45, "quantity": 2 },
{ "product_id": 67, "quantity": 1 }
],
"size": "medium",
"gift_message": "Happy Birthday!"
}
```
**Parameters:**
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | ----------------------------------------------------- |
| `box_id` | integer | Yes | The WooCommerce product ID for the box |
| `items` | array | Yes | Array of selected items with product\_id and quantity |
| `size` | string | No | Selected box size ID |
| `gift_message` | string | No | Gift message text |
**Response:**
```json theme={null}
{
"share_key": "a1b2c3d4e5f6",
"share_url": "https://yourstore.com/?boxbuilder_share=a1b2c3d4e5f6",
"expires": "2025-02-15T00:00:00"
}
```
### Get Shared Box
```
GET /wp-json/boxbuilder/v1/share/{key}
```
Retrieves a shared box configuration by its share key. No authentication required.
**Parameters:**
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------- |
| `key` | string | 12-character alphanumeric share key |
**Response:**
```json theme={null}
{
"box_id": 123,
"items": [
{ "product_id": 45, "quantity": 2 },
{ "product_id": 67, "quantity": 1 }
],
"size": "medium",
"gift_message": "Happy Birthday!",
"created_at": "2025-01-16T12:00:00"
}
```
Share links expire after 30 days. They are stored as WordPress transients.
## AJAX Handlers
BoxBuilder uses WordPress AJAX (`admin-ajax.php`) for all frontend builder operations. These handlers are available to both logged-in and guest users.
### Product & Configuration
| Action | Description |
| ------------------------------- | ------------------------------------------- |
| `boxbuilder_pro_get_products` | Fetch paginated products for the box picker |
| `boxbuilder_pro_get_product` | Get a single product's details |
| `boxbuilder_pro_get_categories` | Fetch product categories for filter tabs |
| `boxbuilder_pro_get_box_config` | Get the box configuration for a product |
| `boxbuilder_pro_get_sizes` | Fetch available box sizes (Pro) |
| `boxbuilder_pro_check_stock` | Real-time stock check for products |
### Session & Cart
| Action | Description |
| ----------------------------- | ------------------------------------------------- |
| `boxbuilder_pro_save_session` | Save the current builder session (selected items) |
| `boxbuilder_pro_load_session` | Load a previously saved session |
| `boxbuilder_pro_add_to_cart` | Add a completed box to the WooCommerce cart |
| `boxbuilder_pro_validate_box` | Validate box contents before checkout |
### Sharing (Pro)
| Action | Description |
| ---------------------------------- | ---------------------------------- |
| `boxbuilder_pro_create_share_link` | Create a shareable box link |
| `boxbuilder_pro_get_shared_box` | Retrieve shared box data |
| `boxbuilder_pro_load_shared_box` | Load a shared box into the builder |
### Analytics (Pro)
| Action | Description |
| --------------------------------- | ------------------------------ |
| `boxbuilder_pro_get_analytics` | Fetch analytics dashboard data |
| `boxbuilder_pro_export_analytics` | Export analytics as CSV |
## Using AJAX in Custom Code
All AJAX requests require a nonce for security. The nonce is available via the localized `boxbuilderData` object:
```js theme={null}
// Example: fetch products for a box
wp.ajax.post( 'boxbuilder_pro_get_products', {
nonce: boxbuilderData.nonce,
box_id: 123,
page: 1,
per_page: 12,
category: 0,
search: ''
}).done( function( response ) {
console.log( response.products );
console.log( response.total_pages );
}).fail( function( error ) {
console.error( error );
});
```
## Error Handling
Both REST API and AJAX endpoints return standard error responses:
```json theme={null}
{
"success": false,
"data": {
"code": "boxbuilder_invalid_box",
"message": "The specified box product does not exist."
}
}
```
| Error Code | Description |
| --------------------------- | ------------------------------------ |
| `boxbuilder_invalid_box` | Box product not found or not enabled |
| `boxbuilder_box_incomplete` | Box doesn't meet minimum capacity |
| `boxbuilder_invalid_item` | Product not allowed in this box |
| `boxbuilder_out_of_stock` | One or more items are out of stock |
| `boxbuilder_invalid_nonce` | Security nonce is invalid or expired |
# Saved Boxes
Source: https://docs.swiftlywp.com/plugins/boxbuilder/saved-boxes
Let logged-in customers save boxes and return later to finish building.
Saved Boxes is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro lets logged-in customers save their in-progress box and come back later to finish building it.
## How It Works
1. Customer starts building a box but isn't ready to checkout
2. They click **Save for Later** in the box summary panel
3. The box configuration (selected items, quantities, gift message) is saved to their account
4. Later, they visit **My Account → Saved Boxes** and click **Continue Building**
5. The builder loads with their saved selections pre-filled
## My Account Integration
A **Saved Boxes** tab is added to the WooCommerce **My Account** page. Customers can:
* View all their saved boxes
* Continue building any saved box
* Delete saved boxes they no longer want
## Storage
Saved boxes are stored as WordPress user meta (`_boxbuilder_saved_boxes`). Each saved box records:
* Box product ID
* Selected items and quantities
* Gift message (if any)
* Date saved
Saved boxes require the customer to be logged in. Guest users cannot save boxes. Consider enabling WooCommerce account creation to maximize this feature.
## Session Tracking
BoxBuilder Pro also tracks the current box session, so if a customer navigates away from the product page and returns (without explicitly saving), their selections are preserved for the duration of their browsing session.
# Settings Reference
Source: https://docs.swiftlywp.com/plugins/boxbuilder/settings
Complete reference for all BoxBuilder settings across all 6 tabs.
BoxBuilder settings are found at **BoxBuilder → Settings** in your WordPress admin. Settings are organized into 6 tabs: General, Display, Labels, Gift Message, Cart, and Appearance.
Click **Save Settings** at the bottom of any tab to apply changes. Settings apply globally to all box products unless overridden at the individual product level.
***
## General
The General tab controls layout, positioning, interaction behavior, the box summary panel, progress indicators, and mobile settings.
### Product Layout
| Setting | Description | Options | Default |
| ----------------- | ------------------------------------------ | ---------- | ------- |
| Layout Style | How products are displayed in the builder | Grid, List | Grid |
| Products Per Page | Number of products shown before pagination | Any number | 12 |
Grid layout works best for visual browsing (e.g., chocolates, flowers). List layout is better when product details matter (e.g., items with descriptions or variations). Recommended: 8–16 products per page for optimal performance.
### Builder Position
| Setting | Description | Options | Default |
| ------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Position on Product Page | Where the builder appears on the product page | After Product Details Block, Before Product Tabs, Replace Product Tabs, After Product Tabs, After Price, After Short Description, After Add to Cart Form, After Product Meta, Shortcode Only | Before Product Tabs |
| Summary Panel Position | Which side the box summary panel appears on | Right Side, Left Side | Right Side |
**Choosing the right position:**
* **FSE/Block themes** (e.g., Twenty Twenty-Four): Use "After Product Details Block"
* **Classic themes** (e.g., Storefront, Astra): "Before Product Tabs" is recommended
* **Page builders** (Elementor, Divi, etc.): Use "Shortcode Only" and place `[boxbuilder]` where you want
### Interaction
| Setting | Description | Options | Default |
| ----------------- | ------------------------------------------------- | ------------------------------------------ | -------------- |
| Add to Box Mode | How customers add products to the box | Button Click, Card Click (quick add), Both | Button Click |
| Quantity Controls | When +/- quantity buttons appear on product cards | Always Visible, On Hover, After First Add | Always Visible |
"Card Click" mode is faster for high-volume stores where customers add many items quickly. "Both" gives customers the flexibility to use either method.
### Box Summary
The summary panel shows selected items and the running total.
| Setting | Description | Options | Default |
| --------------------------- | --------------------------------------- | ----------------------------- | --------- |
| Display Mode | How items appear in the summary panel | List View, Slot Grid, Minimal | List View |
| Show thumbnails in summary | Display product images next to items | Checkbox | Enabled |
| Show item prices in summary | Display individual prices for each item | Checkbox | Enabled |
**Slot Grid** mode shows a visual representation of the box filling up — great for gift boxes where the "filling" experience matters. **Minimal** keeps the summary compact with just item names and counts.
### Progress Indicators
| Setting | Description | Options | Default |
| ---------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- | ------------------ |
| Show progress indicator | Display visual feedback for box completion | Checkbox | Enabled |
| Progress Style | Visual style for the progress indicator | Progress Bar, Percentage (50%), Slot Dots, Counter (6/12) | Progress Bar |
| Show "almost full" encouragement message | Display a motivational message when close to full | Checkbox | Enabled |
| Message Text | The encouragement message text | Text input | "Add more items!" |
Use `{count}` in the message text as a placeholder for the number of remaining items. For example, "Add more items!" becomes "Add 3 more items!" when there are 3 slots left.
### Mobile
| Setting | Description | Options | Default |
| ----------------------------------- | -------------------------------------------------------------------- | ---------------------------------------- | -------------- |
| Mobile Layout | How the builder displays on mobile devices | Stacked (default), Tabbed (switch views) | Stacked |
| Summary Position | Where the summary appears relative to products (stacked layout only) | Below Products, Above Products | Below Products |
| Sticky Add to Cart button on mobile | Fix the Add to Cart button at the bottom of the screen | Checkbox | Enabled |
**Stacked** layout shows products and summary vertically. **Tabbed** layout lets customers switch between "Products" and "Your Box" views — useful when screen space is limited.
***
## Display
The Display tab controls product card information, stock management, and search/filter options.
### Product Cards
| Setting | Description | Default |
| ------------------------------- | ------------------------------------- | ------- |
| Show price on each product card | Display the product price on the card | Enabled |
| Display "Only X left!" badge | Show a low stock warning badge | Enabled |
Disable "Show price" for fixed-price boxes where individual item prices are irrelevant — customers only need to know the total box price.
### Stock Management
| Setting | Description | Options | Default |
| --------------------- | -------------------------------------------------- | -------------------------------------------------------------------- | -------------------------- |
| Out of Stock Products | How to handle products with zero stock | Show all (no indicator), Show with badge (disabled), Hide completely | Show with badge (disabled) |
| Low Stock Threshold | Stock level that triggers the "Only X left!" badge | Any number | 5 |
"Show with badge (disabled)" keeps the product visible but prevents customers from adding it — this avoids confusion about missing products. "Hide completely" removes them entirely from the grid.
### Search & Filter
| Setting | Description | Options | Default |
| ---------------------- | ------------------------------------------ | -------------------------------- | -------------------- |
| Enable product search | Show a search bar above the product grid | Checkbox | Enabled |
| Search Placeholder | Placeholder text shown in the search field | Text input | "Search products..." |
| Enable category filter | Show category filter controls | Checkbox | Enabled |
| Category Filter Style | How category filters are presented | Horizontal Tabs, Dropdown Select | Horizontal Tabs |
Horizontal tabs work best when you have 2–5 categories. For 6+ categories, switch to the dropdown to avoid wrapping and clutter.
***
## Labels
The Labels tab lets you customize all user-facing text strings in the builder interface.
### Products Section
| Setting | Description | Default |
| ----------------- | ----------------------------------------------------- | ----------------------------------------- |
| Section Title | Heading above the product grid | "Choose Your Products" |
| Section Subtitle | Subtitle text below the heading (leave empty to hide) | "Select items to add to your custom box." |
| Add to Box Button | Text on the add button for each product | "Add to Box" |
### Box Summary Panel
| Setting | Description | Default |
| -------------------------------------- | ----------------------------------------- | -------------------------------------------- |
| Panel Title | Heading of the summary sidebar | "Your Box" |
| Slots Remaining Text | Text showing remaining capacity | " slots remaining" |
| Empty Box Title | Title shown when no items have been added | "Your box is empty" |
| Empty Box Hint | Helper text when box is empty | "Click on products to add them to your box." |
| Add to Cart Button | Text on the final add-to-cart button | "Add Box to Cart" |
| Box Size Selector Title Pro | Heading above box size options | "Choose Your Box Size" |
Use `{count}` in the "Slots Remaining Text" field as a placeholder for the number. For example, " slots remaining" becomes "4 slots remaining" when there are 4 empty slots.
***
## Gift Message
The Gift Message tab controls whether customers can add a personal note to their box.
### Gift Message Toggle
| Setting | Description | Default |
| ------------------------------------ | ----------------------------------------------------- | -------- |
| Enable gift message field | Show the gift message textarea in the builder | Enabled |
| Require customers to enter a message | Make the gift message mandatory before adding to cart | Disabled |
### Field Settings
| Setting | Description | Default |
| ---------------- | ------------------------------------------------------- | --------------------------- |
| Field Label | Label shown above the text area | "Gift Message" |
| Placeholder Text | Placeholder inside the empty text area | "Add a personal message..." |
| Max Characters | Maximum character limit for the message (0 = unlimited) | 500 |
Keep the character limit reasonable — 500 characters is typically enough for a thoughtful gift message without allowing excessively long text that could cause display issues on packing slips.
***
## Cart
The Cart tab controls how boxes behave in the WooCommerce cart and after adding to cart.
### Cart Display
| Setting | Description | Default |
| ---------------------------------------------- | ------------------------------------------------------------ | -------- |
| Show list of items inside the box on cart page | Display individual box contents beneath the box item in cart | Enabled |
| Allow changing box quantity in cart | Let customers increase/decrease box quantity from the cart | Disabled |
### After Add to Cart
| Setting | Description | Options | Default |
| ----------- | -------------------------------------------------- | -------------------------------------- | --------- |
| Redirect To | Where to send customers after adding a box to cart | Cart Page, Checkout Page, Stay on Page | Cart Page |
### Box Sizes Pro
These settings control how multiple box sizes are presented when using [Box Sizes](/plugins/boxbuilder/box-sizes) in BoxBuilder Pro.
| Setting | Description | Options | Default |
| -------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- |
| Size Display Style | How size options are shown to customers | Cards (dropdown on mobile), Dropdown selector | Cards (dropdown on mobile) |
| Cards Per Row | Number of size cards per row (cards style only) | 2, 3, 4, 5 | 3 |
| Size Change Behavior | What happens when a customer switches to a smaller size and items exceed the new capacity | Keep items that fit, remove excess; Prevent size change; Show warning and ask to confirm | Keep items that fit, remove excess |
***
## Appearance
The Appearance tab controls colors, card styling, and advanced options.
### Brand Colors
| Setting | Description | Default |
| ------------- | -------------------------------------------------------------- | --------- |
| Primary Color | Main accent color used for buttons, selected states, and links | `#5c6ac4` |
| Success Color | Color used for "added" badges and confirmation states | `#28a745` |
Choose a primary color that matches your store's branding. The color picker supports hex values — click "Default" to reset to the original color.
### Card Styling
| Setting | Description | Options | Default |
| ------------ | ------------------------------ | --------------------------------------------------------------------------------------------- | -------------- |
| Corner Style | Border radius of product cards | Square (0px), Slightly Rounded (4px), Rounded (8px), More Rounded (12px), Very Rounded (16px) | Rounded (8px) |
| Card Shadow | Shadow effect on product cards | None (Flat), Light (Subtle), Medium (Prominent) | Light (Subtle) |
### Advanced Pro
| Setting | Description | Default |
| ---------------------------------- | ------------------------------------------- | ------- |
| Enable logging for troubleshooting | Write debug information to WooCommerce logs | Enabled |
Leave logging enabled during setup and testing. You can disable it on production sites to avoid unnecessary log file growth. Logs are accessible at **WooCommerce → Status → Logs**.
# Shareable Box URLs
Source: https://docs.swiftlywp.com/plugins/boxbuilder/shareable-boxes
Share a pre-configured box via a unique link.
Shareable Box URLs is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro lets customers share their box configuration with others via a unique URL. The recipient opens the link and sees the box pre-filled with the shared selections.
## How It Works
The customer adds items to their box as usual.
A **Share** button in the box summary generates a unique URL.
The customer copies the URL and sends it to someone (email, messaging, social media).
The recipient visits the URL. The box builder loads with all the shared items pre-selected.
The recipient can keep the box as-is, modify it, add a gift message, and add it to their own cart.
## Use Cases
* **Gift registries**: "Here's the box I'd love — buy it for me!"
* **Recommendations**: "I made this chocolate selection for you, try it!"
* **Team orders**: "Fill your box like mine" — for corporate or group gifts
* **Social sharing**: Share curated boxes on social media
## Technical Details
* Share links use a unique 12-character key
* Shared box data is stored as a WordPress transient with a **30-day expiry**
* After 30 days, the link expires and shows a "this shared box has expired" message
* Share links are read-only — the original sharer's box is not affected by changes the recipient makes
## Share URL Format
```
https://yourstore.com/product/build-your-own-box/?boxbuilder_share=abc123xyz456
```
The `boxbuilder_share` parameter triggers the builder to load with the shared configuration.
# Shortcode & Block
Source: https://docs.swiftlywp.com/plugins/boxbuilder/shortcode-and-block
Embed the box builder anywhere using a shortcode or Gutenberg block.
BoxBuilder can be displayed on any page or post using either a shortcode or a Gutenberg block. This lets you place the builder anywhere — not just on the WooCommerce product page.
## Shortcode
Use the `[boxbuilder]` shortcode to embed a box builder anywhere:
```
[boxbuilder id="123"]
```
Replace `123` with the WooCommerce product ID of your box product.
### Finding the Product ID
1. Go to **Products → All Products**
2. Hover over your box product
3. The ID is shown below the product name, or in the URL when editing (`post=123`)
### Using in Page Builders
The shortcode works in all major page builders:
| Page Builder | How to Add |
| ------------------ | ----------------------------------------------------- |
| **Elementor** | Add a Shortcode widget, paste `[boxbuilder id="123"]` |
| **Divi** | Add a Code module, paste the shortcode |
| **WPBakery** | Add a Text Block or Raw HTML element |
| **Beaver Builder** | Add an HTML module |
| **Bricks Builder** | Add a Shortcode element |
| **Oxygen Builder** | Add a Shortcode component |
## Gutenberg Block
BoxBuilder includes a native Gutenberg block for the WordPress block editor.
Open the page where you want the box builder in the block editor.
Click the **+** button to add a block. Search for **"BoxBuilder"**.
In the block settings sidebar, select which box product to display.
Save or publish the page. The box builder will render on the frontend.
The block shows a placeholder in the editor. The full interactive box builder is only visible on the frontend.
## Product Page Integration
By default, BoxBuilder automatically displays the builder on the WooCommerce single product page for any product that has BoxBuilder enabled. You don't need to use a shortcode or block for this.
The position on the product page is configurable — see [Builder Position](/plugins/boxbuilder/builder-position).
## Multiple Boxes on One Page
You can place multiple box builders on a single page using multiple shortcodes or blocks. Each operates independently with its own product configuration, selections, and cart integration.
```
[boxbuilder id="101"]
[boxbuilder id="102"]
[boxbuilder id="103"]
```
# Subscription Boxes
Source: https://docs.swiftlywp.com/plugins/boxbuilder/subscriptions
Recurring customizable box subscriptions with WooCommerce Subscriptions.
Subscription Boxes is a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
BoxBuilder Pro integrates with WooCommerce Subscriptions to offer recurring, customizable box subscriptions. Customers subscribe to a box and customize their selections before each renewal.
## Requirements
* [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/) (official extension)
* Or [Sumo Subscriptions](https://developer.sumo.dev/)
## How It Works
Create a WooCommerce Subscription product with your desired billing period (monthly, quarterly, etc.).
Enable BoxBuilder on the subscription product, configure capacity, products, and pricing.
Customer builds their first box and subscribes. Their box configuration is saved with the subscription.
Before the next billing date, the customer can log in and customize their box for the upcoming period.
A configurable deadline (e.g., 3 days before billing) locks the box for customization. After the deadline, the current configuration is used.
## Notification Emails
BoxBuilder sends a reminder email before each renewal period:
> "Your next box ships on \[date]. Customize your box before \[deadline]."
If the customer doesn't customize their box before the deadline, the default box contents (set by the admin or the customer's previous selection) are used.
## Admin Configuration
* Set the **customization deadline** (days before renewal)
* Set **default box contents** used when customers don't customize
* View subscription box history for each customer
## Use Cases
| Business Type | Subscription Box |
| -------------- | -------------------------------------------------------- |
| Coffee roaster | Monthly coffee selection box — choose 4 bags each month |
| Snack company | Quarterly snack box — pick your favorites every 3 months |
| Beauty brand | Monthly sample box — choose products to try |
| Book club | Monthly book box — select genres or specific titles |
# Template Overrides
Source: https://docs.swiftlywp.com/plugins/boxbuilder/template-overrides
Customize the BoxBuilder frontend template for full control over the HTML output.
BoxBuilder uses a single frontend template file to render the box builder UI on product pages. You can customize the builder's output using hooks, CSS, or by modifying the template directly in child themes.
## Frontend Template
The builder UI is rendered from a single template file:
```
boxbuilder-pro/templates/boxbuilder-frontend.php
```
This template handles the complete builder interface including:
* Product grid / list layout
* Box summary panel
* Progress indicators
* Gift message field
* Add to Cart button
* Size selector (Pro)
## Template Variables
The following variables are available inside the template:
| Variable | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------- |
| `$box_id` | int | The WooCommerce product ID for the box |
| `$config` | array | The box configuration array (capacity, pricing model, product source, etc.) |
| `$css_vars` | string | CSS custom properties for theming (primary color, success color, etc.) |
The template also reads global plugin options:
| Option Key | Description |
| ------------------------------------ | -------------------------------------- |
| `boxbuilder_mobile_layout` | Mobile layout mode (stacked or tabbed) |
| `boxbuilder_mobile_summary_position` | Summary position on mobile |
| `boxbuilder_mobile_sticky_cart` | Whether sticky cart button is enabled |
| `boxbuilder_summary_display_mode` | Summary panel display mode |
| `boxbuilder_summary_show_thumbnails` | Show thumbnails in summary |
| `boxbuilder_summary_show_prices` | Show prices in summary |
| `boxbuilder_progress_style` | Progress indicator style |
| `boxbuilder_add_mode` | Add to box interaction mode |
| `boxbuilder_qty_controls_display` | Quantity controls display behavior |
## Customizing with Hooks
The recommended way to add content before or after the builder is with hooks:
```php theme={null}
// Add content before the product grid
add_action( 'boxbuilder/before_product_grid', function( $box_id, $config ) {
echo 'Build your perfect gift!
';
}, 10, 2 );
// Add content after the add to cart button
add_action( 'boxbuilder/after_add_to_cart_button', function( $box_id ) {
echo 'Free shipping on all boxes!
';
}, 10, 1 );
```
## Customizing with CSS
For visual changes, use the [Appearance settings](/plugins/boxbuilder/appearance) or add custom CSS. All BoxBuilder elements are namespaced under `.boxbuilder-wrap` with `.boxbuilder-` prefixed class names.
```css theme={null}
/* Example: customize product cards */
.boxbuilder-wrap .boxbuilder-product-card {
background-color: #f9f9f9;
border: 1px solid #e0e0e0;
}
```
## Customizing with JavaScript
BoxBuilder's frontend is a Vue.js application. You can interact with it via the localized `boxbuilderData` object:
```js theme={null}
// Available data from wp_localize_script
console.log( boxbuilderData.ajaxUrl ); // AJAX endpoint
console.log( boxbuilderData.nonce ); // Security nonce
console.log( boxbuilderData.i18n ); // Translatable strings
```
Modifying the Vue.js application directly is not recommended as it may break with plugin updates. Use hooks and CSS for customizations whenever possible.
# Troubleshooting
Source: https://docs.swiftlywp.com/plugins/boxbuilder/troubleshooting
Solutions to common issues with BoxBuilder.
## Builder Not Showing on Product Page
Make sure WooCommerce is installed and activated. BoxBuilder requires WooCommerce to function. If WooCommerce is missing, BoxBuilder will deactivate itself.
1. Check that **Enable BoxBuilder** is checked in the product's BoxBuilder tab
2. Make sure the product is published (not draft)
3. Check the **Builder Position** setting in **BoxBuilder → Settings → General** — try a different position
4. If using a page builder, try the `[boxbuilder id="123"]` shortcode directly
5. Check for JavaScript errors in the browser console (F12 → Console tab)
1. Check the **Product Source** setting — make sure the selected categories/products have published, in-stock items
2. If using "By Category", confirm your products are assigned to the selected categories
3. If using "Specific Products", confirm the selected products are published and in stock
4. Check that products have prices set — products without prices are excluded
## Cart Issues
Check **BoxBuilder → Settings → Cart → Show cart contents** — make sure it's set to "Yes".
1. For **Fixed pricing**: Make sure the box product has the correct price set in the WooCommerce General tab
2. For **Per-item pricing**: Set the box product price to \$0.00 — the total should be the sum of selected items
3. Clear the WooCommerce cart and add the box again
4. Check if any other plugins are modifying cart prices (disable other plugins temporarily to test)
This can happen if another plugin is interfering with cart item visibility. BoxBuilder hides child items via the `woocommerce_cart_item_visible` filter. Check if another plugin is also hooking into this filter.
## Order Issues
1. Check that your email template is using standard WooCommerce order item display
2. If you have a custom email template, make sure it supports order item meta display
3. Test with the default WooCommerce email template by temporarily switching to the Storefront theme
1. Make sure gift messages are enabled in **BoxBuilder → Settings → Gift Message**
2. Check the order in admin — look for `_boxbuilder_message` in the order item meta
3. The gift message is stored with the parent box order item, not as a separate order note
## Style Issues
1. Clear your browser cache and any caching plugins
2. Check if your theme is overriding BoxBuilder styles — try switching to Storefront temporarily
3. Check for CSS conflicts using browser DevTools (F12 → Elements → Styles)
4. Make sure no optimization plugin is stripping BoxBuilder's CSS file
1. Go to **Settings → Media** and check the thumbnail sizes
2. Regenerate thumbnails using a plugin like [Regenerate Thumbnails](https://wordpress.org/plugins/regenerate-thumbnails/)
3. Ensure your product images are large enough — BoxBuilder uses the WooCommerce thumbnail size
## Performance
1. Reduce **Products Per Page** in settings (try 8 or 12 instead of 24+)
2. Optimize your product images — use appropriate sizes, not full-resolution uploads
3. Check if your hosting meets the minimum requirements
4. Disable other plugins temporarily to identify conflicts
## Still Need Help?
If you can't resolve your issue:
1. Check the [FAQ](/plugins/boxbuilder/faq) for additional answers
2. Check [Compatibility](/plugins/boxbuilder/compatibility) for known plugin/theme interactions
3. [Contact Support](https://swiftlywp.com/support/) — include your WordPress version, WooCommerce version, theme name, and a description of the issue