AJAX Endpoints

Complete reference for every WordPress AJAX action registered by BoxCart, covering public storefront interactions, customer account operations, and admin management endpoints.

Overview

BoxCart uses WordPress AJAX (admin-ajax.php) for all frontend and admin interactions. Every AJAX action registered by the plugin is prefixed with boxcart_ to avoid naming collisions with other plugins.

WordPress provides two hook patterns for AJAX handlers:

wp_ajax_{action} - Fires for logged-in users only
wp_ajax_nopriv_{action} - Fires for guests (not logged in)

Public endpoints register both hooks so they are accessible to all visitors. Customer endpoints register only wp_ajax_ so they require authentication. Admin endpoints additionally check for the manage_options capability.

Nonce verification

Every BoxCart AJAX handler verifies a nonce before processing the request. The nonce action is boxcart_ajax_nonce and is passed in the nonce parameter. All handlers call check_ajax_referer('boxcart_ajax_nonce', 'nonce', false) and return a 403 error if verification fails. The nonce is automatically localised to the frontend via wp_localize_script and is available in JavaScript as boxcartData.nonce.

Making AJAX Requests

BoxCart localises an object called boxcartData containing the AJAX URL and nonce. You can use jQuery or the native Fetch API to call any endpoint.

Using jQuery:

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_get_basket',
        nonce: boxcartData.nonce
    },
    success: function(response) {
        if (response.success) {
            console.log(response.data);
        }
    }
});

Using Fetch API:

const formData = new FormData();
formData.append('action', 'boxcart_add_to_basket');
formData.append('nonce', boxcartData.nonce);
formData.append('product_id', 42);
formData.append('quantity', 1);

fetch(boxcartData.ajaxUrl, {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('Item added:', data.data);
    }
});

Public Endpoints

These endpoints are available to both guest visitors and logged-in users. They are registered with both wp_ajax_ and wp_ajax_nopriv_ hooks, making them accessible without authentication.

Action	Auth	Description
`boxcart_search_products`	Public	Search products by name. Returns matching products for the live search feature on the storefront.
`boxcart_load_table_products` Pro	Public	Pro only. Loads products for the Pro table-view storefront. Returns rendered HTML for table rows and mobile cards. Not registered on the free build.
`boxcart_get_slots`	Public	Get available collection time slots for a specific location and date. Respects capacity limits, closures, and lead time settings.
`boxcart_add_to_basket`	Public	Add a product to the basket. Accepts `product_id`, `quantity`, and optional `quantity_type_id`.
`boxcart_update_basket_item`	Public	Update the quantity of an item already in the basket. Pass the `item_id` and new `quantity`.
`boxcart_remove_from_basket`	Public	Remove a specific item from the basket by `item_id`.
`boxcart_get_basket`	Public	Get the current basket contents including items, totals, tax breakdown, and selected collection slot.
`boxcart_clear_basket`	Public	Clear all items from the basket.
`boxcart_set_slot`	Public	Select a collection time slot for the current basket. Requires `location_id`, `slot_date`, `time_start`, and `time_end`.
`boxcart_get_current_slot`	Public	Get the currently selected collection slot for the basket.
`boxcart_clear_slot`	Public	Clear the currently selected collection slot from the basket.
`boxcart_place_order`	Public	Submit the checkout to create an order. Validates basket contents, slot selection, customer details, and payment method before creating the order record.
`boxcart_create_payment_intent` Pro	Public	Pro only. Creates a Stripe PaymentIntent for the current basket total. Returns the client secret needed to confirm payment on the frontend. Ships with Stripe payments in Pro and is not registered on the free build.
`boxcart_refresh_nonce`	Public	Generate a fresh nonce. No nonce verification required on this endpoint - it exists specifically to recover from expired nonces (e.g. cached pages, long sessions).

Example: Add to Basket

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_add_to_basket',
        nonce: boxcartData.nonce,
        product_id: 42,
        quantity: 2,
        quantity_type_id: 1
    },
    success: function(response) {
        if (response.success) {
            // response.data contains updated basket
            console.log('Items in basket:', response.data.item_count);
            console.log('Basket total:', response.data.total);
        } else {
            console.error('Error:', response.data.message);
        }
    }
});

Example: Get Available Slots

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_get_slots',
        nonce: boxcartData.nonce,
        location_id: 3,
        date: '2025-06-15'
    },
    success: function(response) {
        if (response.success) {
            response.data.slots.forEach(function(slot) {
                console.log(slot.time_start + ' - ' + slot.time_end
                    + ' (' + slot.remaining_capacity + ' remaining)');
            });
        }
    }
});

Customer Endpoints

These endpoints are only available to logged-in customers. They are registered with wp_ajax_ only (no nopriv hook), so unauthenticated requests will receive a 0 or -1 response from WordPress.

Action	Auth	Description
`boxcart_toggle_favourite`	Logged-in	Toggle a product as a favourite for the current customer. Pass `product_id` to add or remove from favourites.
`boxcart_get_favourites`	Logged-in	Get the current customer's list of favourite products.
`boxcart_reorder`	Logged-in	Quick reorder a previous order. Copies items from the specified order into the current basket for review before checkout.
`boxcart_get_order_details`	Logged-in	Get order details for modal display. Returns full order information including line items, status history, and collection details. Only returns orders belonging to the authenticated customer.
`boxcart_start_order_modification`	Logged-in	Start modifying an existing order. Only permitted when the order is within the modification window and in a modifiable status.
`boxcart_cancel_order_modification`	Logged-in	Cancel an in-progress order modification, discarding any changes.
`boxcart_save_order_modification`	Logged-in	Save and apply changes made during an order modification session.
`boxcart_update_account`	Logged-in	Update the customer's account details such as name, email, and phone number.
`boxcart_change_password`	Logged-in	Change the customer's password. Requires the current password and the new password.
`boxcart_send_customer_message`	Logged-in	Send a message from the customer regarding an order. Creates a message thread visible to both the customer and admin.
`boxcart_get_order_messages`	Logged-in	Get all messages for a specific order. Returns the conversation thread between customer and admin.
`boxcart_post_purchase_signup`	Guest	Create a customer account from the order-confirmation page. View-token gated (proof of order ownership), nonce-protected, and rate-limited per IP (5 per hour). Calls WordPress core's `wp_create_user()` and emails a BoxCart-branded "set your password" link - never sets a password or auth cookie directly.

Example: Toggle Favourite

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_toggle_favourite',
        nonce: boxcartData.nonce,
        product_id: 42
    },
    success: function(response) {
        if (response.success) {
            // response.data.is_favourite = true or false
            var icon = response.data.is_favourite ? 'heart-filled' : 'heart-outline';
            console.log('Favourite toggled:', response.data.is_favourite);
        }
    }
});

Example: Quick Reorder

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_reorder',
        nonce: boxcartData.nonce,
        order_id: 156
    },
    success: function(response) {
        if (response.success) {
            // Items from order #156 added to basket
            // Redirect to basket for review
            window.location.href = response.data.basket_url;
        } else {
            console.error('Reorder failed:', response.data.message);
        }
    }
});

Admin Endpoints

These endpoints are restricted to users with administrator privileges. Each handler verifies both the nonce and the manage_options capability before processing. They are used by the BoxCart admin dashboard in the WordPress back end.

Action	Auth	Description
`boxcart_update_order_status`	Admin	Change the status of an order (e.g. Pending to Processing, Processing to Ready). Triggers status change emails and logs the change in the order history.
`boxcart_send_order_message`	Admin	Send a message from the admin to a customer regarding an order. Creates a message in the order conversation thread.
`boxcart_save_location`	Admin	Create or update a collection location. Handles both new locations and edits to existing ones, including name, address, and contact details.
`boxcart_delete_location`	Admin	Delete a collection location and its associated schedules and slots.
`boxcart_save_opening_hours`	Admin	Save the opening hours schedule for a location. Defines which days of the week the location is open and the hours for each day.
`boxcart_save_slot`	Admin	Save a collection time slot for a location including start time, end time, and capacity.
`boxcart_delete_slot`	Admin	Delete a collection time slot from a location.
`boxcart_save_closure`	Admin	Save a closure period for a location. Supports both single date and date range closures to block orders during holidays or maintenance.
`boxcart_delete_closure`	Admin	Delete a closure period from a location.
`boxcart_save_capacity_override`	Admin	Save a capacity override for a specific date, allowing the admin to increase or decrease the number of available orders for that day.
`boxcart_delete_capacity_override`	Admin	Delete a capacity override, reverting the date to the default slot capacity.
`boxcart_duplicate_product`	Admin	Duplicate an existing product, creating a copy with the same details, category, and settings.
`boxcart_bulk_delete_products`	Admin	Delete multiple products at once. Accepts an array of product IDs to remove.
`boxcart_delete_all_products`	Admin	Move all BoxCart products to the trash. Used for bulk cleanup of the entire product catalogue.
`boxcart_create_category`	Admin	Create a new product category.
`boxcart_save_category`	Admin	Save a category (create or update). Handles both new categories and edits to existing ones.
`boxcart_update_category_order`	Admin	Update the sort order of categories. Accepts an ordered array of category IDs.
`boxcart_import_upload`	Admin	Upload a CSV file for product import. Validates the file, saves it to a temporary location, and returns preview data including headers, sample rows, and auto-detected column mapping.
`boxcart_import_batch`	Admin	Import a batch of rows from a previously uploaded CSV file using the user-provided column mapping. Processes products in batches for large imports.
`boxcart_import_cleanup`	Admin	Clean up after an import by deleting the temporary CSV file and associated transient data.
`boxcart_reverse_import`	Admin	Reverse a previous import by trashing all products that were created during that import. Uses the import token to identify which products to remove. Provides a safe "undo" for imports.
`boxcart_test_stripe_connection`	Admin	Test the configured Stripe API keys by making a verification call to the Stripe API. Returns success or a descriptive error.
`boxcart_confirm_payment`	Admin	Confirm that a bank transfer payment has been received. Sets the payment status to "Paid" and advances the order status to "Processing". Sends a payment confirmation email to the customer.

Example: Update Order Status

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: {
        action: 'boxcart_update_order_status',
        nonce: boxcartData.nonce,
        order_id: 203,
        status: 'ready'
    },
    success: function(response) {
        if (response.success) {
            console.log('Order status updated to:', response.data.new_status);
            // Status change email automatically sent to customer
        }
    }
});

Example: Upload CSV for Import

// Step 1: Upload the CSV file and get a preview
var formData = new FormData();
formData.append('action', 'boxcart_import_upload');
formData.append('nonce', boxcartData.nonce);
formData.append('csv_file', fileInput.files[0]);

jQuery.ajax({
    url: boxcartData.ajaxUrl,
    type: 'POST',
    data: formData,
    processData: false,
    contentType: false,
    success: function(response) {
        if (response.success) {
            // response.data contains headers, sample rows, and mapping
            console.log('Headers:', response.data.headers);
            console.log('Sample rows:', response.data.sample_rows);
            // Step 2: Use boxcart_import_batch to process rows
            // Step 3: Use boxcart_import_cleanup to remove temp file
        }
    }
});

Response Format

All BoxCart AJAX endpoints return responses using the standard WordPress JSON format via wp_send_json_success() and wp_send_json_error().

Success response:

{
    "success": true,
    "data": {
        // Endpoint-specific data
    }
}

Error response:

{
    "success": false,
    "data": {
        "message": "A human-readable error description"
    }
}

Error handling

Always check response.success before accessing response.data. When a nonce check fails, WordPress returns a 403 Forbidden HTTP status. When a user lacks the required capability, BoxCart returns a JSON error with an appropriate message. Expired nonces can be refreshed by reloading the page.