WP JSON API for WordPress

Introduction

Welcome to the documentation for WP JSON API for WordPress!
Here you'll be able to learn how it works and explore the features available.
If you have any questions please feel free to contact us

WP JSON API adds REST endpoints to your WordPress site so an app can register users, log them in, read and update their details, and manage WooCommerce customer data and Points and Rewards.

This page documents version 5.0, which adds the wpapp/v4 API. If you build your app with Flutter, use our wp_json_api Flutter package 5.x, which uses this API for you.

Note: 5.0.0 and 3.5.0 are security releases. If your site runs an older version of WP JSON API, please update it now.

Requirements

To quickly get set up, you'll need to ensure that you have the below requirements.

• WordPress 5.0+
• WooCommerce Store 3.0+ (Optional, for the WooCommerce endpoints)
• WooCommerce Points and Rewards (Optional, for the Points and Rewards endpoints)

Which version do I need?

The plugin and the Flutter package share major versions: plugin 5.x works with wp_json_api 5.x.

Installing the Plugin

Follow the below steps to install the plugin on your WordPress site:

• Login into your WooSignal account (or create an account if you are new).

• Once you reach the Dashboard, on the left nav bar look for "Plugins" and click the link.

• Under WP JSON API, click "Download" to get version 5.0.0. If your app is still on wp_json_api 4.x and you can't update the plugin to 5.0 yet, use the "App still on wp_json_api 4.x? Download v3.5.0" link below it instead (see Which version do I need?).

• After downloading the plugin, visit your WordPress site and login to get to your admin dashboard. On your nav bar, look for "Plugins" like the below image.

  

  Select "Add New" and proceed to the next step below.

• Then select "Upload plugin" like the below image

  

  This will open a box below where you can upload a .zip file.

• Click "Choose file" can look for the WooSignal plugin you downloaded and select the .zip file to install. After you select "Install Now". You should then be able to activate the plugin from your WordPress admin to start using it.

• If you followed all the steps above you should now be ready to start using the plugin.

Upgrading to 5.0

Download 5.0.0 from your Dashboard and upload it in WordPress as above. When WordPress says the plugin is already installed, choose "Replace current with uploaded". After updating from 3.x:

• All app users are logged out. Every token issued by 3.x is revoked, so app users need to log in again.
• Users with admin-level access can no longer log in through the API. This includes administrators, shop managers and editors. See the wpapp_json_api_allow_privileged_users filter if you need to change this.
• Review your admin users. WordPress shows a notice listing the users with admin-level access. Check that you recognise every user, then click "I have reviewed these users".
• Existing apps keep working. The deprecated v3 API stays on, so apps built with wp_json_api 4.x keep working. Turn it off in Settings once your app uses wp_json_api 5.x.

Settings

5.0 adds a settings page at Settings → WP JSON API in your WordPress admin.

• Legacy v3 API - "Enable the deprecated v3 API". Apps built with wp_json_api 4.x or earlier use the v3 API. Turn this off once your app uses wp_json_api 5.0 or later. The v3 API will be removed in plugin version 6.0.
• App sessions - "Revoke all app sessions" logs every user out of the app. Use this if you think app tokens have been stolen.
• Administrators - a reminder that users with admin-level access can't log in to the app.

Each user's profile page in WP Admin also shows their active app sessions, with an option to log that user out of the app on all devices.

API v4

All v4 endpoints use the base path /wp-json/wpapp/v4, e.g. https://mysite.com/wp-json/wpapp/v4/auth/login.

Authentication

Login and Register return a token. Send it in both of these headers on every authenticated request:

Authorization: Bearer <token>
X-WPApp-Token: <token>

X-WPApp-Token is read when the server strips the Authorization header (common on Apache/CGI hosts), so clients should always send both. Tokens in the request body or query string are not accepted in v4, and there is no nonce.

• Tokens expire. The default lifetime is 90 days (filter wpapp_json_api_token_lifetime). A client can ask for a shorter lifetime with expires_in (seconds), never a longer one.
• Only a SHA-256 hash of each token is stored on your site.
• Tokens are revoked when the user logs out, changes their password (all their other tokens), resets their password or has it changed in WP Admin (all tokens), gains admin-level access, is deleted, or an admin revokes them.
• Privileged users can't use the API. Users with admin-level capabilities (e.g. administrators, shop managers and editors) can't log in to or use the API unless the site enables the wpapp_json_api_allow_privileged_users filter.
• Rate limiting. Login, registration and password checks are rate limited. A limited request returns wpapp_too_many_attempts with retry_after (seconds).

Example

curl -X POST https://mysite.com/wp-json/wpapp/v4/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login": "luke@example.com", "password": "thepassword1"}'

curl https://mysite.com/wp-json/wpapp/v4/user \
  -H "Authorization: Bearer 3f9c2a7d0b6e41f58a1c9d2e7b4f6a0c3e8d1b5a7c9f2e4d6b8a0c1e3f5a7b9d" \
  -H "X-WPApp-Token: 3f9c2a7d0b6e41f58a1c9d2e7b4f6a0c3e8d1b5a7c9f2e4d6b8a0c1e3f5a7b9d"

Responses

A successful request returns HTTP 200 (201 for register) with this body:

{
    "data": { ... },
    "message": "",
    "status": 200
}

An error returns an HTTP 4xx/5xx status with the standard WordPress REST error body:

{
    "code": "wpapp_invalid_credentials",
    "message": "The login details are incorrect.",
    "data": {
        "status": 401
    }
}

Check the HTTP status (or code) to tell success from failure, and show message to the user.

Error codes

Clients should treat any other code as a generic error and show message.

Example: rate limited

{
    "code": "wpapp_too_many_attempts",
    "message": "Too many attempts, please try again later.",
    "data": {
        "status": 429,
        "retry_after": 600
    }
}

Objects

User

{
    "id": 12,
    "username": "luke",
    "email": "luke@example.com",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "display_name": "Luke",
    "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g",
    "roles": ["customer"],
    "meta_data": {
        "billing_city": ["Mos Eisley"]
    },
    "created_at": "2026-10-12 15:00:00"
}

meta_data only contains allow-listed keys. It is always a JSON object ({} when empty). Values are arrays because WordPress meta can have several values per key.

Auth (returned by login and register)

{
    "token": "3f9c2a7d0b6e41f58a1c9d2e7b4f6a0c3e8d1b5a7c9f2e4d6b8a0c1e3f5a7b9d",
    "expires_at": 1768402800,
    "user": { User }
}

token is 64 hex characters. expires_at is a Unix timestamp in seconds.

Customer (WooCommerce)

{
    "id": 12,
    "first_name": "Luke",
    "last_name": "Skywalker",
    "display_name": "Luke",
    "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=96&d=mm&r=g",
    "billing": {
        "first_name": "Luke",
        "last_name": "Skywalker",
        "company": "WooSignal",
        "address_1": "33 West Lane",
        "address_2": "",
        "city": "London",
        "state": "London",
        "postcode": "B3 1JJ",
        "country": "GB",
        "email": "luke@example.com",
        "phone": "0292922"
    },
    "shipping": {
        "first_name": "Luke",
        "last_name": "Skywalker",
        "company": "",
        "address_1": "499 Home Road",
        "address_2": "",
        "city": "London",
        "state": "London",
        "postcode": "B3 1JJ",
        "country": "GB",
        "phone": "0292922"
    },
    "meta_data": {},
    "created_at": "2026-10-12 15:00:00"
}

Allowed meta keys

meta_data reads and writes are limited to an allow-list. By default this is the WooCommerce billing and shipping fields:

billing_first_name, billing_last_name, billing_company, billing_address_1,
billing_address_2, billing_city, billing_state, billing_postcode,
billing_country, billing_email, billing_phone,
shipping_first_name, shipping_last_name, shipping_company, shipping_address_1,
shipping_address_2, shipping_city, shipping_state, shipping_postcode,
shipping_country, shipping_phone

Add your own keys with the wpapp_json_api_allowed_user_meta_keys filter, e.g. in your theme's functions.php or a small plugin:

add_filter('wpapp_json_api_allowed_user_meta_keys', function ($keys) {
    $keys[] = 'favourite_store';
    $keys[] = 'marketing_opt_in';
    return $keys;
});

Capability, role, session and underscore-prefixed (protected) keys are always refused, even if a filter adds them.

API Requests: WordPress

Login

Login a user on WordPress with their username or email. Runs the WordPress authenticate filters, so two-factor and login limit plugins apply. Rate limited per login and per IP.

[POST]

Path /wp-json/wpapp/v4/auth/login

Body Parameters

{
    "login": "luke@example.com",
    "password": "thepassword1",
    "device_name": "Luke's iPhone"
}

Response: Auth

{
    "data": {
        "token": "3f9c2a7d0b6e41f58a1c9d2e7b4f6a0c3e8d1b5a7c9f2e4d6b8a0c1e3f5a7b9d",
        "expires_at": 1768402800,
        "user": {
            "id": 12,
            "username": "luke",
            "email": "luke@example.com",
            "first_name": "Luke",
            "last_name": "Skywalker",
            "display_name": "Luke",
            "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g",
            "roles": ["customer"],
            "meta_data": {},
            "created_at": "2026-10-12 15:00:00"
        }
    },
    "message": "",
    "status": 200
}

Errors: wpapp_invalid_credentials, wpapp_login_blocked, wpapp_privileged_user, wpapp_too_many_attempts.

Register a user

Register a user on WordPress. Registration follows the WordPress "Anyone can register" setting; WooCommerce registrations (wc_register: true) also follow WooCommerce's "Allow customers to create an account on the My account page" setting (filter wpapp_json_api_registration_enabled). New users always get the site's default role (customer for WooCommerce), never a role with admin-level access. Rate limited per IP.

[POST]

Path /wp-json/wpapp/v4/auth/register

Body Parameters

{
    "email": "luke@example.com",
    "password": "thepassword1",
    "username": "luke",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "wc_register": true,
    "meta_data": {
        "billing_phone": "0123456789"
    }
}

Response: Auth, with HTTP 201

{
    "data": {
        "token": "3f9c2a7d0b6e41f58a1c9d2e7b4f6a0c3e8d1b5a7c9f2e4d6b8a0c1e3f5a7b9d",
        "expires_at": 1768402800,
        "user": {
            "id": 12,
            "username": "luke",
            "email": "luke@example.com",
            "first_name": "Luke",
            "last_name": "Skywalker",
            "display_name": "luke",
            "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g",
            "roles": ["customer"],
            "meta_data": {
                "billing_phone": ["0123456789"]
            },
            "created_at": "2026-10-12 15:00:00"
        }
    },
    "message": "",
    "status": 201
}

Errors: wpapp_registration_disabled, wpapp_username_taken, wpapp_email_exists, wpapp_invalid_email, wpapp_weak_password, wpapp_meta_key_not_allowed, wpapp_woocommerce_missing, wpapp_too_many_attempts.

Logout

Revokes the token used for the request. Requires authentication.

[POST]

Path /wp-json/wpapp/v4/auth/logout

Parameters: {}

Response:

{
    "data": [],
    "message": "Logged out",
    "status": 200
}

WordPress Users Info

Returns the authenticated user. Requires authentication.

[GET]

Path /wp-json/wpapp/v4/user

Parameters: {}

Response: User

{
    "data": {
        "id": 12,
        "username": "luke",
        "email": "luke@example.com",
        "first_name": "Luke",
        "last_name": "Skywalker",
        "display_name": "Luke",
        "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g",
        "roles": ["customer"],
        "meta_data": {
            "billing_city": ["Mos Eisley"]
        },
        "created_at": "2026-10-12 15:00:00"
    },
    "message": "",
    "status": 200
}

Update Users Info

Update the authenticated user's info. Requires authentication.

[POST]

Path /wp-json/wpapp/v4/user

Body Parameters

Every meta_data key is checked against the allow-list before anything is saved; one refused key fails the whole request with wpapp_meta_key_not_allowed.

{
    "first_name": "Luke",
    "last_name": "Skywalker",
    "meta_data": [
        { "key": "billing_city", "value": "Mos Eisley", "action": "update" },
        { "key": "billing_company", "action": "delete" }
    ]
}

Response: the updated User

{
    "data": {
        "id": 12,
        "username": "luke",
        "email": "luke@example.com",
        "first_name": "Luke",
        "last_name": "Skywalker",
        "display_name": "Luke",
        "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g",
        "roles": ["customer"],
        "meta_data": {
            "billing_city": ["Mos Eisley"]
        },
        "created_at": "2026-10-12 15:00:00"
    },
    "message": "Updated",
    "status": 200
}

Update Users Password

Change the authenticated user's password. The current password is required. All of the user's other tokens are revoked; the token used for the request stays valid. Requires authentication.

[POST]

Path /wp-json/wpapp/v4/user/password

Body Parameters

{
    "current_password": "thepassword1",
    "password": "secretPassword2"
}

Response:

{
    "data": [],
    "message": "Password updated",
    "status": 200
}

Errors: wpapp_incorrect_password, wpapp_weak_password, wpapp_too_many_attempts.

Delete Account

Delete the authenticated user's account and all of its tokens. The user's current password is required. Requires authentication.

[POST]

Path /wp-json/wpapp/v4/user/delete

Body Parameters

{
    "password": "thepassword1"
}

Response:

{
    "data": [],
    "message": "Account deleted",
    "status": 200
}

Errors: wpapp_incorrect_password, wpapp_too_many_attempts.

API Requests: WooCommerce

WooCommerce Get Users Info

Returns the authenticated user's WooCommerce customer details, including billing and shipping. Requires authentication and WooCommerce (wpapp_woocommerce_missing otherwise).

[GET]

Path /wp-json/wpapp/v4/wc/customer

Parameters: {}

Response: Customer

{
    "data": {
        "id": 12,
        "first_name": "Luke",
        "last_name": "Skywalker",
        "display_name": "Luke",
        "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=96&d=mm&r=g",
        "billing": {
            "first_name": "Luke",
            "last_name": "Skywalker",
            "company": "WooSignal",
            "address_1": "33 West Lane",
            "address_2": "",
            "city": "London",
            "state": "London",
            "postcode": "B3 1JJ",
            "country": "GB",
            "email": "luke@example.com",
            "phone": "0292922"
        },
        "shipping": {
            "first_name": "Luke",
            "last_name": "Skywalker",
            "company": "",
            "address_1": "499 Home Road",
            "address_2": "",
            "city": "London",
            "state": "London",
            "postcode": "B3 1JJ",
            "country": "GB",
            "phone": "0292922"
        },
        "meta_data": {},
        "created_at": "2026-10-12 15:00:00"
    },
    "message": "",
    "status": 200
}

WooCommerce Update Users Info

Send the fields you want to update and the plugin will handle the rest. All parameters are optional. Requires authentication and WooCommerce.

[POST]

Path /wp-json/wpapp/v4/wc/customer

Body Parameters

{
    "first_name": "Luke",
    "last_name": "Skywalker",
    "billing": {
        "address_1": "33 West Lane",
        "city": "London",
        "postcode": "B3 1JJ",
        "country": "GB",
        "phone": "0292922"
    },
    "shipping": {
        "address_1": "499 Home Road",
        "city": "London",
        "postcode": "B3 1JJ",
        "country": "GB"
    }
}

Response: the updated Customer

{
    "data": {
        "id": 12,
        "first_name": "Luke",
        "last_name": "Skywalker",
        "display_name": "Luke",
        "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=96&d=mm&r=g",
        "billing": { ... },
        "shipping": { ... },
        "meta_data": {},
        "created_at": "2026-10-12 15:00:00"
    },
    "message": "Updated",
    "status": 200
}

API Requests: Points and Rewards

These endpoints need the WooCommerce Points and Rewards plugin. Without it they return wpapp_points_rewards_missing.

Get Points

Returns the authenticated user's points balance and its value. Requires authentication.

[GET]

Path /wp-json/wpapp/v4/wc/points

Parameters: {}

Response:

{
    "data": {
        "id": 12,
        "points": 120,
        "value": "1.20"
    },
    "message": "",
    "status": 200
}

Calculate Points Value

Returns the value of a number of points. Requires authentication.

[POST]

Path /wp-json/wpapp/v4/wc/points/calculate

Body Parameters

{
    "points": 120
}

Response:

{
    "data": {
        "value": "1.20"
    },
    "message": "",
    "status": 200
}

Developer filters

Use these WordPress filters (e.g. in your theme's functions.php or a small plugin) to change how the API behaves.

Examples

// Tokens last 30 days
add_filter('wpapp_json_api_token_lifetime', function () {
    return 30 * DAY_IN_SECONDS;
});

// Require 12 character passwords
add_filter('wpapp_json_api_min_password_length', function () {
    return 12;
});

// Turn off the deprecated v3 API in code
add_filter('wpapp_json_api_enable_v3', '__return_false');

Rate limits are set as [max attempts, window in seconds]:

add_filter('wpapp_json_api_rate_limits', function ($limits) {
    // Defaults:
    // 'login_ip'      => [30, 15 * MINUTE_IN_SECONDS]  login attempts per IP
    // 'login_user'    => [10, 15 * MINUTE_IN_SECONDS]  login attempts per username/email
    // 'register_ip'   => [10, HOUR_IN_SECONDS]         registrations per IP
    // 'password_user' => [5, 15 * MINUTE_IN_SECONDS]   password checks per user
    $limits['login_ip'] = [60, 15 * MINUTE_IN_SECONDS];
    return $limits;
});

If your site is behind a proxy or CDN, use wpapp_json_api_client_ip to return the visitor's real IP so rate limits apply per visitor. Only trust a forwarded header your proxy sets.

Legacy v3 API (plugin 3.5 / apps on wp_json_api 4.x)

Deprecated: the v3 API is only for apps that are already published. It is the API used by plugin 3.x and by wp_json_api 4.x for Flutter. Build new apps on the v4 API. In plugin 5.x, v3 still works but can be turned off in Settings, and it will be removed in plugin 6.0.

In plugin 5.x, v3 uses the same token storage, login checks and rate limits as v4: tokens expire, users with admin-level access can't log in, and user info no longer returns capability, role, session or protected meta.

The v3 API uses a nonce for login and register, sends the token in the request body, and returns errors in the status field of the response body (often with HTTP 200). Check status on every v3 response.

Changes from v3 to v4

v3 Endpoints

All v3 endpoints are POST (except the nonce) and authenticated ones take the user's token in the body.

Note: v3 also has /wp-json/wpapp/api/v3/update/user/role/add and /role/remove. Since 3.5.0 they can only add or remove the customer and subscriber roles (filter wpapp_json_api_allowed_roles), and they are not part of v4. Manage roles on the server instead.

Note: since 3.5.0, args and meta_data can't set capability, role, session or protected meta keys, and registration follows the WordPress / WooCommerce registration settings.

v3 Login example

#1 Get a nonce

[GET]

Path /wp-json/wpapp/auth/v3/nonce

Response:

{
    "data": {
        "nonce": "002bac1c4e",
        "root": "https://mysite.com/wp-json/",
        "expiry": 1586639327
    },
    "message": "",
    "status": 200
}

#2 Login with the nonce

[POST]

Path /wp-json/wpapp/api/v3/user/login?auth=email

Body Parameters

{
    "nonce": "002bac1c4e",
    "email": "sam@aol.com",
    "password": "thepassword1"
}

Response:

{
    "data": {
        "user_token": "9dfade62d610dbf601c2sodfefcc344eac507861d7a75778",
        "user_id": 2,
        "expiry": 1768402800,
        "first_name": "Sam",
        "last_name": "Cook",
        "username": "samcook",
        "email": "sam@aol.com",
        "created_at": "2020-04-05 23:34:32",
        "avatar": "https://secure.gravatar.com/avatar/b7ebd909f128794ca00ce488ef880421?s=250&d=mm&r=g"
    },
    "message": "",
    "status": 200
}

#3 Use the token in the body of authenticated requests

[POST]

Path /wp-json/wpapp/api/v3/user/info

{
    "token": "9dfade62d610dbf601c2sodfefcc344eac507861d7a75778"
}

An invalid or expired token returns "status": 540 with the message Invalid token.