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 onlywp_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 also check a capability (see Admin Endpoints). A few admin actions go through admin-post.php instead (see Admin-post Actions).
BoxCart AJAX handlers verify a nonce, passed in the nonce parameter, before doing anything. Storefront handlers check boxcart_ajax_nonce with check_ajax_referer('boxcart_ajax_nonce', 'nonce', false); the nonce is localised to the frontend and available in JavaScript as boxcartData.nonce. Admin handlers check a separate boxcart_admin_nonce. If the check fails, the handler returns a JSON error (success: false with a message) and does nothing. The one exception is boxcart_refresh_nonce, which takes no nonce because it hands out a fresh one (for pages served from a cache).
Since 1.8.0 a few admin endpoints have their own nonce. boxcart_search_word_products, boxcart_add_search_word and boxcart_remove_search check boxcart_search_insights (available as boxcartSearchInsights.nonce), and boxcart_dashwidget_day checks boxcart_dashwidget_day (boxcartDashWidget.nonce). If one of these checks fails, WordPress ends the request with -1 and a 403 status rather than a JSON error.
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 | Load and search products for the storefront's product cards. Takes search, category, page, limit and favourites_only (GET). Since 1.8.0 a search matches product names, "Also found by" words, descriptions and category names, most relevant first, and plurals match singulars. When nothing matches, it tries the closest word the shop uses: search_corrected is a search it showed instead, search_suggested one it only offers ("Did you mean …?"), and search_original is the search as typed. Send exact=1 to search for exactly what was typed. Each product also has search_match (name, words, description, category or similar), search_category (the category it was found through, for products found only that way), and photo, photo_width and photo_height for the photo pop-up (empty when "Tap a product photo to see it larger" is off). |
boxcart_load_table_products Pro |
Public | Pro only. Loads products for the Pro table-view storefront. Returns rendered HTML for table rows (table_html) and mobile cards (mobile_html). The layout parameter (rows, cards or both, default both) picks which to build; the storefront asks only for the one its width shows, and the response says which it built. Since 1.8.0 it uses the same search as boxcart_search_products: it takes exact and returns search_corrected, search_suggested and search_original. 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 the order cut-off (lead time or fixed cut-off). |
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. Refuses the order with an error message when payments are on but no payment method is available. |
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. Since 1.5.0 checkout calls it when the customer presses Place Order (after Stripe has checked the card details), not when the checkout page loads. Ships with Stripe payments in Pro and is not registered on the free build. Refused for signed-out visitors while members-only pricing is on, and limited to 20 calls per basket in 10 minutes. |
boxcart_log_search |
Public | Count a customer's search for Search Insights (1.8.0). The shop page sends it once typing has settled (about two seconds after the results show, on Enter, or on leaving the search box or the page), once per search per page view. Takes term (POST). With BoxCart Pro it also sends added=1 when the search led to a basket add, with counted=1 if the search itself was already sent, so only the add is counted. Checks boxcart_ajax_nonce. Returns a 403 error with no data when the nonce fails or Search Insights is off; otherwise it always succeeds with no data, even when it leaves the search out (shop staff, bots, anything that looks like an email address, phone number, postcode or link, or more than 30 searches from one IP address in 10 minutes). The number of products found is worked out on the server. |
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, plus total_rows: the lines under the total (VAT, discount, refunds, anything left to pay). Only returns orders belonging to the authenticated customer (by account). |
boxcart_start_order_modification |
Logged-in | Start modifying an existing order. Only permitted for the customer's own order, 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. Quantities must be on each product's steps. On an order paid by card, a lower total is refunded to the card first (the change is refused if the refund fails) and a higher total leaves the order part paid; the success message says which. |
boxcart_update_account |
Logged-in | Update the customer's account details such as name, email, and phone number. Changing the email needs current_password; the new address takes effect from a confirmation link emailed to it. |
boxcart_change_password |
Logged-in | Change the customer's password. Requires the current password and the new password. After 5 wrong current passwords in a row the account waits 15 minutes. |
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. Up to 2,000 characters, and up to 10 messages an hour per customer per order. |
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 need shop access: the manage_boxcart_shop capability, which administrators always have and shop staff are given (1.6.0). These stay with administrators (manage_options): boxcart_delete_all_products, the boxcart_import_* and boxcart_reverse_import actions, boxcart_test_stripe_connection, boxcart_send_shop_report_now and the boxcart_setup_* actions, along with the settings, settings import/export and email preview/test actions. Each handler verifies both the nonce and the capability before processing. They are used by the BoxCart admin dashboard in the WordPress back end, where the nonce comes from boxcartAdmin.nonce.
| 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_copy_slots |
Admin | Copy one day's time slots to other days. Takes location_id, from_day (0 = Sunday to 6 = Saturday), to_days[], and replace (set to delete the slots those days already have first; otherwise copies whose times a day already has are skipped). Returns a message and the copied, skipped and removed counts. Added in 1.5.0. |
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. If orders are booked on those dates, it returns an error with needs_confirmation and a message listing them; send the request again with confirmed=1 to close anyway. |
boxcart_delete_closure |
Admin | Delete a closure period from a location. |
boxcart_save_capacity_override |
Admin | Save a capacity override for a slot on a specific date, allowing the admin to increase or decrease the number of orders it can take. Since 1.6.0, saving again for the same slot and date changes the existing override. Refused for a date with special times. |
boxcart_slot_booked_count |
Admin | How many orders are booked for a weekly slot (slot_id) on a date, for the capacity override form. Returns booked. Pro, 1.6.0. |
boxcart_save_date_slots |
Admin | Save a date's special times (Pro, 1.6.0): location_id, date and ranges (JSON: start, end, capacity for each, up to 24, no overlaps), replacing any it had. Needs an active Pro licence. If orders on the date are booked at times that won't be offered, it returns an error with needs_confirmation and a message listing them; send again with confirmed=1 to save anyway. |
boxcart_delete_date_slots |
Admin | Remove a date's special times, so the usual weekly slots apply again (Pro, 1.6.0). Same needs_confirmation step as above. |
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 payment has been received (bank transfer, cash on collection, or the balance on a part-paid order). Sets the payment status to "Paid" and leaves the order status as it is. For a bank transfer, the customer gets a "Payment Received" email. |
boxcart_refund_order Pro |
Admin | Pro only. Refund part or all of an order's card payment through Stripe. Takes order_id and amount (up to what was paid by card, less earlier refunds). Added in 1.5.0. Since 1.6.0 it also takes request_key: the same key sent again (a retry after a lost answer) returns the first refund instead of refunding again. |
boxcart_dashwidget_day |
Admin | The day picker on the BoxCart Today dashboard widget (1.8.0). Takes date (GET, Y-m-d) and returns html: that day's figures and collections, ready to drop into the widget. Needs the widget's capability (boxcart_dashboard_widget_capability, default manage_boxcart_shop). Returns a 400 error for a missing or invalid date. |
boxcart_search_word_products |
Admin | Products for the "Add as a search word" picker on the Searches screen and the BoxCart Searches widget (1.8.0). Takes q (GET). Returns products, each with id and title: up to 50 products matching q, or the first 8 by name when q is empty. Published, draft and private products are included. |
boxcart_add_search_word |
Admin | Add a search to the "Also found by" words of one or more products (1.8.0). Takes term and product_ids[] (up to 50), or a single product_id (POST). A product whose words are already full (500 characters) is skipped; if none of them can take it, it returns an error with a message. The search then leaves the "Found nothing" list in the BoxCart Searches widget until someone searches for it on a later day and it still finds nothing. Returns message. |
boxcart_remove_search |
Admin | Remove a search from the Search Insights log, for typing mistakes (1.8.0). Takes term (POST). Only the days it found nothing are deleted, so a real search can't be wiped by mistake. Returns message. |
boxcart_send_shop_report_now Pro |
Admin | Pro only. Send the latest Shop Report now, to the signed-in user's own email address (Settings, 1.8.0). It doesn't count as the scheduled report. Needs manage_options and an active Pro licence. Returns message. Not registered on the free build. |
boxcart_setup_pages |
Admin | Guided Setup step 1. Creates any missing Shop, Basket, Checkout and My Account pages (reusing pages that already have the BoxCart shortcode or block) and assigns them in Settings. Returns the created and adopted counts and each page's status. Added in 1.5.0. |
boxcart_setup_location |
Admin | Guided Setup step 2. Creates a location with its open days and time slots. Takes name, address, city, postcode, days[] (0 = Sunday), and the time slots as slot_start[] and slot_end[] (HH:MM) with slot_capacity[], applied to every chosen day (they replace any slots those days already had). Added in 1.5.0. |
boxcart_setup_product |
Admin | Guided Setup step 3. Creates a product. Takes name, price, unit (each, unit, bunch, bag, box, kg, g or lb), step_{unit} for weights (for example step_kg = 0.25), category (created if new) and image_id. Added in 1.5.0. |
boxcart_setup_touches |
Admin | Guided Setup step 4. Saves how customers pay (pay_cash, pay_bank, bank_name, bank_sort, bank_number), the order email sender and alert address (from_name, from_address, alerts_to), and VAT (vat: none, inclusive or exclusive, with vat_rate). Added in 1.5.0. |
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
}
}
});
Admin-post Actions
Since 1.8.0, two admin actions go through admin-post.php (a form or a link) rather than AJAX. Each checks its own nonce with check_admin_referer(), sent as _wpnonce, then the capability. They redirect or send a file instead of returning JSON.
| Action | Auth | Description |
|---|---|---|
boxcart_resend_shop_emails |
Admin | The Resend button on BoxCart Today's warning about orders whose shop email didn't go (POST). Queues the shop's new order email again for each order the warning lists (from the last week, at most 20), then returns to the dashboard with boxcart_resent set to the number queued. Nonce action boxcart_resend_shop_emails. Needs the widget's capability (boxcart_dashboard_widget_capability, default manage_boxcart_shop). |
boxcart_export_searches Pro |
Admin | Pro only. Download a period's searches as a CSV file, from the link at the foot of the Searches screen (GET). Takes period (4weeks, 12weeks or 26weeks; default 12weeks). Columns: Search, Searches, Found nothing, Products found (latest), Led to a basket add, Last searched. Nonce action boxcart_export_searches. Needs manage_options and an active Pro licence. Not registered on the free build. |
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"
}
}
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.