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
{
"box_id": 123,
"items": [
{ "product_id": 45, "quantity": 2 },
{ "product_id": 67, "quantity": 1 }
],
"size": "medium",
"gift_message": "Happy Birthday!"
}
| 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 |
{
"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}
| Parameter | Type | Description |
|---|
key | string | 12-character alphanumeric share key |
{
"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:
// 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 |
