Developer · Guide
How to Make AJAX Requests in WordPress

Short answer
Send WordPress AJAX requests through wp-admin/admin-ajax.php. Enqueue your script, pass the AJAX URL and a nonce to JavaScript with wp_localize_script, register a handler with the wp_ajax hook for your action, and return JSON with wp_send_json. End the handler with wp_die, and use the nopriv hook when logged-out users need access.
Key takeaways
- All AJAX requests must go through wp-admin/admin-ajax.php, never straight to plugin pages.
- Register a handler on wp_ajax_{$action} for logged-in users and wp_ajax_nopriv_{$action} for logged-out users.
- Pass the AJAX URL and a nonce to JavaScript with wp_localize_script, and check the nonce in the handler.
- Return JSON with wp_send_json, wp_send_json_success, or wp_send_json_error, and end handlers with wp_die.
- Use the REST API with register_rest_route and a permission_callback when you need a named route under /wp-json/.
What is AJAX in WordPress and how does it work?
AJAX lets a page send a request to WordPress and update part of the page without a full reload.
AJAX stands for Asynchronous JavaScript and XML, but in WordPress it almost always means a JavaScript request that returns JSON.
A button click, a form submit, or a live search can send data to the server and show the reply in place. The page stays where it is, and only the changed part updates.
All WordPress AJAX requests must go through one file. WordPress Developer states that all AJAX requests must go through wp-admin/admin-ajax.php and must never go directly to plugin pages (checked November 2026).
That single entry point keeps requests in one place, so WordPress can load, check the action name, and run the matching handler.
You send an “action” value with each request. WordPress reads that value, looks for a handler registered for it, and runs that handler. If no handler matches, the request fails in a clear way that you can spot while testing.
What do you need before you write AJAX code?
You need a script file, a registered handler, and a nonce before your first AJAX request can run safely.
Start with a small plan. Name the action, decide what data the browser sends, and decide what the server returns. A clear action name such as “my_tag_count” is easier to trace in code and in the debug log than a vague name such as “do_thing”.
You also need to know where the script will run. Enqueue context changes with the screen, and the WordPress Developer handbook states that admin pages use admin_enqueue_scripts, front-end pages use wp_enqueue_scripts, and the login page uses login_enqueue_scripts (checked November 2026).
Pick the hook that matches the screen, or your script will load in the wrong place or not at all.
A guide on how to defer JavaScript in WordPress can help when a script loads late or in the wrong order. Keep that guide in mind if your script runs before its data is ready.
Plan the reply format before you write code. JSON is the normal reply for WordPress AJAX, and the handler functions in this guide return JSON by design. A plain text reply works for a tiny test, but JSON is easier to read in JavaScript and easier to check for errors.
How do you send an AJAX request from JavaScript?
Send the request to admin-ajax.php with an “action” value, then read the reply in a callback.
Your JavaScript needs two things: the URL of admin-ajax.php and the action name.
The URL is admin_url(“admin-ajax.php”) in PHP, and you pass it to JavaScript when you enqueue the script. The action name must match the handler name you register in PHP, or WordPress will not find a handler.
A simple request sends an object with the action and any extra data. The server runs the handler, returns a reply, and your callback runs with that reply. Use the “done” callback for a good reply and the “fail” callback for an error, so each path has its own code.
Do not hard-code the admin-ajax.php URL in your JavaScript file. The site address can change, and a hard-coded URL breaks when the site moves. Pass the URL from PHP each time, as shown in the next sections, so the same script works on any site.
MDN Web Docs states that you use the fetch() method to make a request and fetch a resource, and that it returns a Promise that resolves to the Response (checked November 2026). Pass the admin-ajax.php URL as the path to fetch.
Learn WordPress states that you can make an AJAX request with the fetch() method in plain JavaScript, or with the WordPress apiFetch package (checked November 2026). Use fetch() when you want plain JavaScript without jQuery.
How do you enqueue a script and pass it the AJAX URL and a nonce?
Enqueue the script with wp_enqueue_script, then pass the AJAX URL and a nonce to JavaScript with wp_localize_script.
The WordPress Developer handbook gives this pattern: enqueue the script with wp_enqueue_script, pass the AJAX URL and a nonce with wp_localize_script, then register the handler and end it with wp_die (checked November 2026).
That pattern is the base for every example in this guide, so learn it once and reuse it.
wp_localize_script creates a global JavaScript object from PHP data.
The handbook example uses an object named “my_ajax_obj” with an “ajax_url” value of admin_url(“admin-ajax.php”) and a nonce value. Your JavaScript can then read my_ajax_obj.ajax_url without guessing the URL, and it can send the nonce with each request.
A nonce must be created so the request can be validated as legitimate.
The same WordPress Developer handbook states that a nonce must be created for this purpose (checked November 2026). Create the nonce in PHP, pass it with wp_localize_script, send it from JavaScript, and check it in the handler before you run any other code.
Use these steps to set up the script:
- Register or enqueue your JavaScript file with wp_enqueue_script on the right hook for the screen.
- Call wp_localize_script with the script handle, an object name such as “my_ajax_obj”, and the AJAX URL plus a nonce.
- In JavaScript, read the URL and nonce from that object, never from a hard-coded string.
- Send the nonce with the request data, and check it first in the PHP handler.
If the nonce check fails, stop the request at once. Do not run the rest of the handler, and do not return data that the caller should not see.
How do you handle an AJAX request in PHP?
Register a handler with add_action on the wp_ajax hook for your action name, then end the handler with wp_die.
The hook name carries the action name. WordPress Developer states that wp_ajax_{$action} fires authenticated AJAX actions for logged-in users, and the dynamic part $action is the “action” field submitted to admin-ajax.php (checked November 2026).
The same source states that this hook was introduced in WordPress 2.1.0 (checked November 2026). A request with action “my_tag_count” therefore runs a handler registered on wp_ajax_my_tag_count.
Logged-out users need a separate hook. WordPress Developer states that wp_ajax_nopriv_{$action} is the hook for logged-out users, and that you should register both hooks to allow both groups (checked November 2026).
Register only the hook you need if the action must stay private, such as a handler that changes user data.
A basic handler looks like this in plain code:
add_action( “wp_ajax_my_tag_count”, “my_ajax_handler” ); add_action( “wp_ajax_nopriv_my_tag_count”, “my_ajax_handler” );
function my_ajax_handler() { check the nonce here build the reply here wp_die(); }
End every handler with wp_die. The WordPress Developer handbook pattern ends the handler with wp_die (checked November 2026). Without that call, WordPress adds a trailing “0” to the reply, and your JavaScript may read the extra character as part of the data.
If no handler is registered for the action, WordPress returns “0”. WordPress Developer states that an unmatched action returns “0”, with a 400 status for the unmatched case (checked November 2026). Seeing “0” in the reply is therefore a useful clue: check the action name spelling in JavaScript and in PHP first.
How do you return JSON from WordPress?
Return JSON with wp_send_json, wp_send_json_success, or wp_send_json_error, and let the function end the request for you.
WordPress Developer states that wp_send_json sends a JSON response back to an AJAX request, and that it encodes the response as JSON, prints it, and dies (checked November 2026). That built-in ending means you do not need a separate wp_die call after wp_send_json.
PHP Manual states that json_encode returns the JSON representation of a value, as a JSON encoded string on success or false on failure (checked November 2026). Keep the data you return simple, so the encoded reply stays small and easy to read.
The function takes three values. WordPress Developer states that $response is required, $status_code is optional and was added in 4.7.0, and $flags is optional and was added in 5.6.0 (checked November 2026).
The same source states that wp_send_json was introduced in WordPress 3.5.0 (checked November 2026). Use $status_code when the reply needs a status other than 200, such as 400 for bad input.
The two companion functions make success and failure easy to tell apart. WordPress Developer states that wp_send_json_success and wp_send_json_error let the done or fail callbacks fire in JavaScript (checked November 2026).
Use wp_send_json_success for a good result and wp_send_json_error for a failed check, such as a bad nonce or missing data.
| Reply function | When to use it | What JavaScript sees |
|---|---|---|
| wp_send_json | Any JSON reply | Encoded JSON, then the request ends |
| wp_send_json_success | A good result | Success flag with your data in done |
| wp_send_json_error | A failed check | Error flag with your message in fail |
Keep the reply small and exact. Send only the fields the page needs, such as a count, a message, or a list of items. A large reply slows the request and makes the JavaScript harder to read.
How do you make AJAX work on the front end?
Use wp_localize_script on the front end, because the global ajaxurl variable does not exist there.
The global ajaxurl variable exists automatically in the WordPress admin area but not on the public front end. WordPress Developer states this split in the AJAX handbook discussion, and it gives wp_localize_script as the front-end route (checked November 2026).
A front-end script that reads ajaxurl directly will fail with an undefined variable error.
Enqueue the script with wp_enqueue_scripts for front-end pages.
That hook is the front-end match for admin_enqueue_scripts, as the handbook states in the enqueue context list. Pass the AJAX URL and nonce with wp_localize_script in the same function, so the data is ready when the script runs.
Test the front end while logged out as well as logged in.
A handler registered only on wp_ajax_{$action} will not run for a visitor, and the reply will be “0”. Register the nopriv hook too when visitors should be able to use the feature, and keep it off when the action must stay logged in.
How do you check that your AJAX request worked?
Open the browser developer tools, watch the Network tab, and read the reply and status for the admin-ajax.php request.
Run the action on the page, then look for a request to admin-ajax.php in the Network tab.
Click it to see the data sent, the status code, and the reply body. A good JSON reply shows your data, while a reply of “0” points to a missing handler or a wrong action name.
Check the request data first when the reply is wrong. Confirm the action name matches the PHP hook, confirm the nonce is sent, and confirm the URL is admin-ajax.php. A single spelling error in the action name is the most common cause of a “0” reply.
A guide on how to enable debug mode in WordPress shows how to turn on error logging for PHP faults in the handler. Turn debug mode on in a test site, run the request again, and read the log for the exact error line.
A guide on how to read the WordPress debug log shows where to find those entries and how to read them. A PHP error in the handler often shows in the log even when the browser reply only shows “0” or a blank body.
Allow about 30 minutes for a first working example, including time to test it logged in and logged out. Most of that time goes to checking the action name, the nonce, and the reply format, not to writing the code itself.
When should you use the REST API instead of admin-ajax.php?
Use the REST API when you need a named URL, a clear route, or an endpoint other code can call without admin-ajax.php.
Routes live under /wp-json/ on your site. WordPress Developer states that register_rest_route registers a custom REST route on the rest_api_init hook, and that namespaces should follow the vendor/v1 pattern (checked November 2026).
A route such as your-plugin/v1/count is easier to read and to document than an action name hidden in request data.
A permission callback is required for a REST route. WordPress Developer states that a permission_callback is required since WordPress 5.5, and a missing one raises a _doing_it_wrong notice (checked November 2026).
Set the callback to check the same things your AJAX handler checks, such as a nonce or a user capability, before you return data.
A guide on how to fix a REST API error in WordPress can help when a route returns an error in Site Health or in the browser. Use it when the route is registered but the reply is not what you expect.
Pick admin-ajax.php for a quick form or button inside WordPress, and pick the REST API for a public endpoint or a feature that other apps may call. Both routes need the same checks: a valid nonce or permission check, a clear reply format, and an error path that JavaScript can read.
What mistakes should you avoid?
Avoid sending requests to plugin pages, skipping the nonce check, and forgetting wp_die at the end of a handler.
Sending a request straight to a plugin file skips WordPress loading and breaks the action system.
All requests must go through admin-ajax.php, as the handbook states. A direct file request may seem to work in a test, but it will fail on sites with different paths and it skips the checks WordPress provides.
Skipping the nonce check is a second common fault. A nonce proves the request came from a page your site served, so check it before you read input or change data. A handler that trusts any request with the right action name can be called by any page that knows that name.
Forgetting wp_die adds a trailing “0” to the reply, unless you use wp_send_json, which ends the request itself.
Check the reply body in the Network tab when a JSON parse fails, since a stray “0” is often the cause. Keep each handler short, return one clear reply, and test it logged in and logged out before you ship it.
Frequently asked questions
Can I send an AJAX request straight to a plugin file?
No. All WordPress AJAX requests must go through wp-admin/admin-ajax.php. WordPress reads the action value from the request and runs the handler registered for it. Sending a request straight to a plugin file skips WordPress loading and the action system, so use admin-ajax.php every time.
Why does my AJAX request return 0?
A reply of 0 usually means no handler is registered for the action name in the request. Check the spelling of the action in your JavaScript and in the PHP add_action call first. It can also mean the request ran a handler for the wrong user state, such as a logged-out visitor hitting a logged-in-only hook.
Can I use ajaxurl on the front end of my site?
No. The global ajaxurl variable exists automatically in the WordPress admin area but not on the public front end. For front-end forms and buttons, enqueue the script with wp_enqueue_scripts and pass the AJAX URL and a nonce to JavaScript with wp_localize_script.
How do I send a success or error reply from a handler?
Use wp_send_json_success for a good result and wp_send_json_error for a failed check, such as a bad nonce or missing data. These two functions let the done or fail callbacks fire in JavaScript, so each path has its own code. Plain wp_send_json works for any JSON reply and ends the request for you.
When should I use the REST API instead of admin-ajax.php?
Use the REST API when you need a named URL, a clear route, or an endpoint other code can call without admin-ajax.php. Register the route with register_rest_route on rest_api_init, follow the vendor/v1 namespace pattern, and set a permission_callback, which is required since WordPress 5.5. For a quick form or button inside WordPress, admin-ajax.php is the simpler choice.
Sources
- Enqueuing JavaScript WordPress Developer
- wp_ajax_{$action} WordPress Developer
- wp_send_json WordPress Developer
- Adding Custom Endpoints WordPress Developer
- register_rest_route WordPress Developer
- Fetch API MDN Web Docs
- json_encode PHP Manual
- JavaScript in Themes Learn WordPress
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


