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

# REST API

> REST API endpoints and AJAX handlers for custom integrations.

<Info>
  REST API endpoints are a **Pro feature**. [Upgrade to BoxBuilder Pro →](https://swiftlywp.com/plugin/boxbuilder-for-woocommerce/)
</Info>

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"
}
```

<Note>
  Share links expire after 30 days. They are stored as WordPress transients.
</Note>

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