wp_send_json() │ WP 3.5.0

Encodes the passed variable into JSON, prints the result to the screen and terminates the script (die). Used to return data for AJAX requests.

The function sets the following HTTP header:

@ header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) );
Uses: wp_json_encode()
Used By: wp_send_json_error(), wp_send_json_success()

No Hooks.

Returns

null. Interrupts the script.

Usage

wp_send_json( $response, $status_code, $options );
$response(string/array/number/object/bool) (mandatory)
Variable, usually an array or object, which will be encoded in JSON.
$status_code(number) (WP 4.7)
The HTTP status code to set. Status code list see here.
Default: null
$options(number) (WP 5.6)

Options to be passed to function json_encode(). A bitmask made up of values:

JSON_FORCE_OBJECT
JSON_HEX_QUOT
JSON_HEX_TAG
JSON_HEX_AMP
JSON_HEX_APOS
JSON_INVALID_UTF8_IGNORE
JSON_INVALID_UTF8_SUBSTITUTE
JSON_NUMERIC_CHECK
JSON_PARTIAL_OUTPUT_ON_ERROR
JSON_PRESERVE_ZERO_FRACTION
JSON_PRETTY_PRINT
JSON_UNESCAPED_LINE_TERMINATORS
JSON_UNESCAPED_SLASHES
JSON_UNESCAPED_UNICODE
JSON_THROW_ON_ERROR

The meaning of these constants is explained on the JSON constants page.

Default: 0

Examples

0

#1 Example of sending an Ajax request and returning a JSON result

This code sends an AJAX request to the plugin's ajax/save_field.php page

jQuery(document).ready(function(){

	jQuery( '#btn_save' ).click( function(e){
		e.preventDefault();

		jQuery.post(
			pluginUrl + 'ajax/save_field.php',
			jQuery('#my-form').serialize(),
			function( data ) {
				alert( data.message + " ID:" + data.ID );
				//This will alert "Saved ID:1"
			}
		);
	} );

} );

This is the code of the file that receives the request. It uses wp_send_json() to conveniently return the result in JSON format:

<?php
// load WP
require_once( $_SERVER['DOCUMENT_ROOT'] . '/wp-load.php' );

$nonce = $_POST['_wpnonce_name'];
if( empty($_POST) || ! wp_verify_nonce($nonce, 'my-nonce') )
	die( 'security check' );

$return = array(
	'message' => 'Saved',
	'ID' => 1
);

wp_send_json( $return );

// the function will interrupt the script itself
// so there's no need for die or exit

Changelog

Since 3.5.0 Introduced.
Since 4.7.0 The $status_code parameter was added.
Since 5.6.0 The $options parameter was added.

wp_send_json() code WP 6.1.1

wp-includes/functions.php 
function wp_send_json( $response, $status_code = null, $options = 0 ) {
	if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: WP_REST_Response, 2: WP_Error */
				__( 'Return a %1$s or %2$s object from your callback when using the REST API.' ),
				'WP_REST_Response',
				'WP_Error'
			),
			'5.5.0'
		);
	}

	if ( ! headers_sent() ) {
		header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) );
		if ( null !== $status_code ) {
			status_header( $status_code );
		}
	}

	echo wp_json_encode( $response, $options );

	if ( wp_doing_ajax() ) {
		wp_die(
			'',
			'',
			array(
				'response' => null,
			)
		);
	} else {
		die;
	}
}

AJAX

Helper Functions