REST API

REST API endpoints are a Pro feature. Upgrade to BoxBuilder Pro →

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.

POST /wp-json/boxbuilder/v1/share

Creates a shareable link for a box configuration. Requires the user to be logged in. Request body:

{
  "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:

{
  "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:

{
  "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

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:

// 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:

{
  "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

Getting Started

Building Boxes

Display & Customization

WooCommerce Integration

Settings Reference

Pro Features

Developer

Help

REST API Endpoints

Get Shared Box

AJAX Handlers

Product & Configuration

Session & Cart

Analytics (Pro)

Using AJAX in Custom Code

Error Handling

​REST API Endpoints

​Create Share Link

​Get Shared Box

​AJAX Handlers

​Product & Configuration

​Session & Cart

​Sharing (Pro)

​Analytics (Pro)

​Using AJAX in Custom Code

​Error Handling

REST API Endpoints

Create Share Link

Get Shared Box

AJAX Handlers

Product & Configuration

Session & Cart

Sharing (Pro)

Analytics (Pro)

Using AJAX in Custom Code

Error Handling