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 boxcart_ajax.nonce.

Making AJAX Requests

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

Using jQuery:

jQuery.ajax({
    url: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_get_basket',
        nonce: boxcart_ajax.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', boxcart_ajax.nonce);
formData.append('product_id', 42);
formData.append('quantity', 1);

fetch(boxcart_ajax.ajax_url, {
    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`	Public	Load products for table view mode via AJAX. Returns rendered HTML for table rows and mobile cards.
`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`	Public	Create a Stripe PaymentIntent for the current basket total. Returns the client secret needed to confirm payment on the frontend.
`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: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_add_to_basket',
        nonce: boxcart_ajax.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: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_get_slots',
        nonce: boxcart_ajax.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_send_reset_code`	Guest	Send a password reset code. Sends a verification code to the customer's email address.
`boxcart_verify_reset_code`	Guest	Verify a password reset code. Confirms the code is valid and has not expired.
`boxcart_reset_password`	Guest	Reset the customer's password using a verified reset code. Requires the code and the new password.
`boxcart_checkout_login`	Guest	Handle customer login during checkout via AJAX. Authenticates the user without a full page reload.
`boxcart_checkout_register`	Guest	Handle customer registration during checkout via AJAX. Creates a new account and logs the customer in.

Example: Toggle Favourite

jQuery.ajax({
    url: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_toggle_favourite',
        nonce: boxcart_ajax.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: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_reorder',
        nonce: boxcart_ajax.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_reorder_categories`	Admin	Reorder categories via drag-and-drop. Persists the new display order.
`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: boxcart_ajax.ajax_url,
    type: 'POST',
    data: {
        action: 'boxcart_update_order_status',
        nonce: boxcart_ajax.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', boxcart_ajax.nonce);
formData.append('csv_file', fileInput.files[0]);

jQuery.ajax({
    url: boxcart_ajax.ajax_url,
    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.