WooCommerce API Pro

A WooCommerce storefront REST API with Google Sign-In, native WordPress cookie authentication, product discovery, checkout, orders, and Firebase notifications.

[!IMPORTANT] Compatibility: This plugin is designed for frontends served from the same WordPress site/origin and for native mobile applications. Native apps must preserve the WordPress cookies in a persistent cookie jar and send the returned REST nonce. A browser frontend hosted on a different domain is not supported out of the box; use a same-origin reverse proxy or provide a carefully configured HTTPS, CORS, cookie, and SameSite policy.

Contents

• Requirements
• Features
• Installation
• Configuration
• Frontend authentication
• Endpoint summary
• Pagination
• API reference
• Errors
• Web shortcode
• Firebase configuration
• Extension hooks
• Security notes
• Troubleshooting
• Upgrading to 3.0.0

Requirements

• WordPress 6.5 or newer
• WooCommerce
• PHP 7.4 or newer
• HTTPS in production
• A Google OAuth client ID

Features

• Google ID-token authentication
• Native WordPress login cookies and REST nonces
• New Google accounts always receive the WordPress subscriber role
• Store configuration, countries, states, categories, and product endpoints
• Product variations, prices, stock, images, and ratings
• Customer profiles and billing/shipping addresses
• Server-calculated shipping quotes
• Validated checkout with coupons and WooCommerce payment methods
• Customer order history, order details, and cancellation
• Optional Firebase Cloud Messaging integration
• Built-in API reference under WC API Pro → API Reference

Installation

1. Install and activate WooCommerce.
2. Upload this plugin to wp-content/plugins/myapp-auth-pro.
3. Activate WooCommerce API Pro.
4. Open WC API Pro → Settings.
5. Enter the Google OAuth client ID used as the ID-token audience.
6. Ensure the WordPress site uses HTTPS in production.

Configuration

Open WC API Pro → Settings in WordPress administration.

Setting	Required	Description
Google Client ID	Yes	OAuth client ID that must match the aud claim in Google ID tokens
Avatar meta key	No	WordPress user-meta key used to store the Google profile image URL

New Google users always receive the WordPress subscriber role. This is enforced by the plugin and is not configurable from the administration screen.

Firebase is optional and is configured with constants described in Firebase configuration.

API base URL

/wp-json/woocommerce-api-pro/v1

Frontend authentication

The plugin uses the standard WordPress login cookie. The frontend must not create or attach a JWT, bearer token, or custom session token.

1. Sign in with Google

Obtain a Google ID token using Google Identity Services, then send it to the plugin. The request must use credentials: "include" so the browser accepts the WordPress login cookie.

const response = await fetch(
  "/wp-json/woocommerce-api-pro/v1/auth/google",
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      id_token: googleIdToken,
      fcm_token: optionalFirebaseToken,
      platform: "web",
    }),
  }
);

const login = await response.json();

if (!response.ok) {
  throw new Error(login.message || "Login failed");
}

let restNonce = login.nonce;

A successful response contains:

{
  "success": true,
  "is_new": false,
  "nonce": "wordpress-rest-nonce",
  "user": {
    "id": 42,
    "email": "customer@example.com",
    "name": "Example Customer",
    "roles": ["subscriber"]
  }
}

The browser stores the wordpress_logged_in_* cookie automatically. JavaScript does not need to read or copy it.

2. Call protected endpoints

Protected REST requests require:

• credentials: "include" to send the WordPress login cookie
• X-WP-Nonce to provide WordPress REST CSRF protection

const response = await fetch(
  "/wp-json/woocommerce-api-pro/v1/profile",
  {
    credentials: "include",
    headers: {
      "X-WP-Nonce": restNonce,
    },
  }
);

const profile = await response.json();

The cookie authenticates the WordPress user. The nonce protects the request against CSRF; it is not a replacement authentication token.

3. Check the login

Use /auth/session to verify the current WordPress login and receive the current REST nonce.

const response = await fetch(
  "/wp-json/woocommerce-api-pro/v1/auth/session",
  {
    credentials: "include",
    headers: {
      "X-WP-Nonce": restNonce,
    },
  }
);

const session = await response.json();

if (response.ok) {
  restNonce = session.nonce;
}

4. Log out

await fetch(
  "/wp-json/woocommerce-api-pro/v1/auth/logout",
  {
    method: "POST",
    credentials: "include",
    headers: {
      "X-WP-Nonce": restNonce,
    },
  }
);

Logout invalidates the current WordPress session and clears its authentication cookies.

Supported frontend environments

This authentication flow supports:

• A web or headless frontend served from the same WordPress site/origin.
• A native mobile application that persists WordPress cookies in a cookie jar and sends the REST nonce.

A browser frontend hosted on a different domain is not supported by default. For that architecture, proxy /wp-json/ through the frontend origin or intentionally configure HTTPS, CORS, credentials, cookie scope, and SameSite=None; Secure. Do not disable WordPress nonce validation to make cross-origin requests work.

Endpoint summary

Public

Method	Endpoint	Purpose
POST	/auth/google	Google login and WordPress cookie creation
GET	/store	Store and currency configuration
GET	/locations	Allowed countries and states
GET	/categories	Paginated product categories
GET	/products	Paginated product catalog
GET	/products/{id}	Product details and variation count
GET	/products/{id}/variations	Paginated product variations

WordPress login required

Method	Endpoint	Purpose
GET	/auth/session	Validate the login and return a REST nonce
POST	/auth/logout	Log out the current WordPress session
GET	/profile	Get the customer profile and addresses
PUT	/profile	Update account details
PUT	/profile/address	Update billing and shipping addresses
DELETE	/account	Permanently delete the account with confirmation
GET	/payment-methods	List enabled payment methods
POST	/shipping-methods	Calculate shipping rates for cart items
PUT	/push-token	Register or refresh an FCM token
DELETE	/push-token	Remove an FCM token
POST	/checkout	Validate the cart and create an order
GET	/orders	List the customer’s orders
GET	/orders/{id}	Get an order owned by the customer
POST	/orders/{id}/cancel	Cancel an eligible order

The complete request and response reference is available in WordPress under WC API Pro → API Reference.

Pagination

Every collection that can grow with store or customer data is paginated:

• GET /products
• GET /categories
• GET /products/{id}/variations
• GET /orders

These endpoints accept page and per_page (per_page has a maximum of 100). Responses contain total, total_pages, and current_page, and also return X-WP-Total and X-WP-TotalPages headers. Other endpoints return fixed-size configuration, a single resource, or a calculated result and do not require pagination.

API reference

All paths below are relative to:

/wp-json/woocommerce-api-pro/v1

Protected endpoints require the WordPress login cookie and an X-WP-Nonce header as described in Frontend authentication.

Authentication

POST /auth/google

Verifies a Google ID token, finds or creates the WordPress user, sets the normal WordPress authentication cookie, and returns a REST nonce.

Authentication: public.

Request body:

Field	Type	Required	Description
id_token	string	Yes	Raw Google ID token
fcm_token	string	No	Firebase registration token to save during login
platform	string	No	android, ios, or web

Example response:

{
  "success": true,
  "is_new": true,
  "nonce": "wordpress-rest-nonce",
  "user": {
    "id": 42,
    "email": "customer@example.com",
    "name": "Example Customer",
    "first_name": "Example",
    "last_name": "Customer",
    "avatar": "https://example.com/avatar.jpg",
    "roles": ["subscriber"]
  }
}

The request must use credentials: "include" or the browser will not retain the returned login cookie.

GET /auth/session

Confirms that the WordPress login remains valid and returns the authenticated user plus the current REST nonce.

Authentication: WordPress cookie and REST nonce.

POST /auth/logout

Invalidates the current WordPress session and clears its authentication cookies.

Authentication: WordPress cookie and REST nonce.

Store and locations

GET /store

Returns fixed store configuration.

Authentication: public.

Response fields include:

• name, description, and url
• currency and currency_symbol
• price_decimal_places, price_decimal_separator, and price_thousand_separator
• price_format
• taxes_enabled and coupons_enabled

GET /locations

Returns WooCommerce’s allowed countries and state/province maps for address forms.

Authentication: public.

{
  "success": true,
  "countries": {
    "BD": "Bangladesh",
    "US": "United States (US)"
  },
  "states": {
    "US": {
      "CA": "California"
    }
  }
}

Catalog

GET /categories

Returns paginated non-empty WooCommerce product categories.

Authentication: public.

Query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page; maximum 100
parent	integer	—	Limit results to children of a category; use 0 for top-level categories

Each category contains id, name, slug, parent, count, description, and image.

GET /products

Returns the paginated public product catalog.

Authentication: public.

Query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page; maximum 100
search	string	—	Product search text
category	string	—	Product category slug
featured	boolean	—	Restrict to featured products
on_sale	boolean	—	Restrict to products currently on sale
orderby	string	date	date, id, title, price, popularity, rating, or rand
order	string	DESC	ASC or DESC

Product summaries include identifiers, type, name, slug, SKU, permalink, prices, sale state, purchasing/stock state, rating data, and the primary image.

GET /products/{id}

Returns one visible product with descriptions, gallery images, categories, attributes, variations_count, and variations_endpoint.

Authentication: public.

Returns 404 product_not_found when the product does not exist or is not publicly visible.

GET /products/{id}/variations

Returns paginated visible variations for a variable product.

Authentication: public.

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page; maximum 100

Each variation includes id, attributes, prices, sale state, stock state, stock quantity, purchasing state, and image.

Customer profile

GET /profile

Returns the authenticated customer’s account, order statistics, FCM token, and WooCommerce billing/shipping addresses.

Authentication: WordPress cookie and REST nonce.

Important response fields:

• id, email, name, first_name, last_name, avatar, and roles
• orders_count and total_spent
• fcm_token
• billing and shipping

PUT /profile

Updates account fields. All fields are optional; only supplied fields are changed.

Authentication: WordPress cookie and REST nonce.

{
  "first_name": "Ahmed",
  "last_name": "Rahman",
  "email": "ahmed@example.com",
  "phone": "+8801700000000"
}

The email is validated before it is saved. Names and contact data are synchronized to the WooCommerce customer record.

PUT /profile/address

Updates billing and/or shipping fields.

Authentication: WordPress cookie and REST nonce.

Use prefixed fields to update one address:

{
  "billing_first_name": "Ahmed",
  "billing_last_name": "Rahman",
  "billing_address_1": "123 Main Street",
  "billing_city": "Dhaka",
  "billing_postcode": "1207",
  "billing_country": "BD",
  "billing_phone": "+8801700000000",
  "shipping_first_name": "Ahmed",
  "shipping_last_name": "Rahman",
  "shipping_address_1": "123 Main Street",
  "shipping_city": "Dhaka",
  "shipping_postcode": "1207",
  "shipping_country": "BD"
}

Supported address suffixes are first_name, last_name, address_1, address_2, city, state, postcode, country, and phone. An unprefixed field such as city updates both billing and shipping.

DELETE /account

Permanently deletes the authenticated WordPress account.

Authentication: WordPress cookie and REST nonce.

{
  "confirm": true
}

The confirm value must be true. Privileged accounts cannot be deleted through this endpoint.

Payment and shipping

GET /payment-methods

Returns enabled WooCommerce payment gateways with id, title, description, and supported features.

Authentication: WordPress cookie and REST nonce.

POST /shipping-methods

Calculates available shipping rates using cart items and the customer’s saved shipping address.

Authentication: WordPress cookie and REST nonce.

{
  "items": [
    {
      "product_id": 101,
      "variation_id": 0,
      "quantity": 2
    }
  ],
  "coupon_codes": ["WELCOME10"]
}

variation_id and coupon_codes are optional. The response contains requires_shipping and shipping_methods. Save the selected rate’s id and submit it as shipping_method during checkout.

Push notifications

PUT /push-token

Registers or refreshes the authenticated user’s Firebase token.

Authentication: WordPress cookie and REST nonce.

{
  "token": "fcm-registration-token",
  "platform": "android"
}

platform may be android, ios, or web.

DELETE /push-token

Removes the authenticated user’s saved Firebase token.

Authentication: WordPress cookie and REST nonce.

Checkout

POST /checkout

Validates products, variations, quantities, purchasing status, stock, payment method, coupons, and shipping before creating a WooCommerce order. Billing and shipping addresses come from the authenticated customer profile.

Authentication: WordPress cookie and REST nonce.

Request body:

{
  "items": [
    {
      "product_id": 101,
      "variation_id": 110,
      "quantity": 2
    }
  ],
  "payment_method": "cod",
  "shipping_method": "flat_rate:1",
  "coupon_codes": ["WELCOME10"]
}

Field	Required	Description
items	Yes	Non-empty array of products and quantities
items[].product_id	Yes	Parent/simple product ID
items[].variation_id	For variations	Variation belonging to product_id
items[].quantity	No	Positive quantity; defaults to 1
payment_method	No	Enabled gateway ID; defaults to cod
shipping_method	For physical products	Rate ID returned by /shipping-methods
coupon_codes	No	Coupon-code array

Successful creation returns HTTP 201:

{
  "success": true,
  "order_id": 1042,
  "order_key": "wc_order_...",
  "total": 2500,
  "payment_url": "https://example.com/checkout/order-pay/1042/..."
}

Cash-on-delivery orders move to processing. Other gateways create a pending order and return the WooCommerce payment URL.

Orders

GET /orders

Returns the authenticated customer’s orders, newest first.

Authentication: WordPress cookie and REST nonce.

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	10	Orders per page; maximum 100

The response contains orders, total, total_orders, total_pages, and current_page.

GET /orders/{id}

Returns one order owned by the authenticated customer, including line items, addresses, shipping total, tax total, and payment data.

Authentication: WordPress cookie and REST nonce.

Returns 404 not_found for a missing order or an order owned by another customer.

POST /orders/{id}/cancel

Cancels an order owned by the authenticated customer when its status is pending or on-hold.

Authentication: WordPress cookie and REST nonce.

Eligible statuses can be customized with the myapp_api_cancellable_order_statuses filter.

Errors

Errors use the standard WordPress REST shape:

{
  "code": "invalid_shipping_method",
  "message": "Select an available shipping method.",
  "data": {
    "status": 400
  }
}

Common errors:

HTTP	Code	Meaning
400	no_token	Google ID token is missing
400	invalid_email	Profile email is invalid
400	empty_cart	Checkout/shipping request has no items
400	invalid_item	Product or quantity cannot be purchased
400	invalid_variation	Variation does not belong to the product
400	invalid_payment_method	Payment method is not enabled
400	invalid_shipping_method	Physical order has no selected valid rate
400	confirmation_required	Account deletion is missing confirm: true
401	invalid_token	Google rejected the ID token
401	wrong_audience	Google token audience does not match the configured client ID
401	unverified_email	Google email is not verified
401	not_logged_in	WordPress cookie is missing or expired
403	rest_cookie_invalid_nonce	REST nonce is missing, invalid, or expired
403	account_not_allowed	Privileged account is blocked from storefront login
404	product_not_found	Product is missing or not visible
404	not_found	Order is missing or belongs to another customer
409	identity_mismatch	Email is linked to another Google subject
409	insufficient_stock	Requested quantity exceeds stock
409	cant_cancel	Order status cannot be cancelled
502	google_unreachable	Google verification service could not be reached
503	google_not_configured	Google Client ID is missing
503	woocommerce_unavailable	WooCommerce is inactive

Web shortcode

Use the built-in Google login UI on a WordPress page:

[myapp_google_login]

Specify a post-login path with:

[myapp_google_login redirect="/my-account/"]

The shortcode uses the same Google verification logic and WordPress login cookies.

Firebase configuration

Add the service-account location to wp-config.php:

define( 'MYAPP_FIREBASE_CREDENTIALS', '/absolute/path/to/service-account.json' );

You can optionally define the project ID. Otherwise, it is read from the service-account file.

define( 'MYAPP_FIREBASE_PROJECT_ID', 'your-firebase-project-id' );

Optional Android notification overrides:

define( 'MYAPP_FIREBASE_ANDROID_ICON', 'ic_notification' );
define( 'MYAPP_FIREBASE_ANDROID_COLOR', '#000000' );
define( 'MYAPP_FIREBASE_ANDROID_CHANNEL', 'myapp_channel' );

Keep the service-account JSON outside the public web root and never commit it to Git.

Extension hooks

Allow or block API users

Administrators are blocked from storefront API login by default. Override the decision carefully:

add_filter( 'myapp_api_user_allowed', function ( $allowed, $user ) {
    return $allowed;
}, 10, 2 );

Customize cancellable order statuses

The default cancellable statuses are pending and on-hold:

add_filter( 'myapp_api_cancellable_order_statuses', function ( $statuses, $order ) {
    return [ 'pending', 'on-hold' ];
}, 10, 2 );

Replace or supplement order-update push delivery

add_action( 'myapp_send_fcm_push_notification', function ( $payload, $order ) {
    // Send to an additional notification service.
}, 20, 2 );

The payload contains the user ID, order ID, old/new status, FCM token, platform, title, and message body.

Security notes

• Use HTTPS in production. Authentication cookies and Google tokens must not travel over plain HTTP.
• Never expose Firebase service-account JSON under the public web root or commit it to source control.
• Do not disable WordPress REST nonce validation. The nonce protects cookie-authenticated requests from CSRF.
• Use credentials: "include" only with trusted origins.
• Never configure credentialed CORS with Access-Control-Allow-Origin: *.
• Treat account deletion as irreversible and require an explicit confirmation screen in the client.
• Product prices, stock, coupons, payment methods, and shipping rates are recalculated and validated by the server during checkout.
• New Google accounts are restricted to the subscriber role; privileged accounts are blocked from storefront API login by default.

Troubleshooting

Login succeeds but the next request returns 401 not_logged_in

• Confirm that both requests use credentials: "include".
• Confirm that the frontend and WordPress are on the same origin, or that a correct credentialed cross-origin cookie policy exists.
• Check the browser’s network panel for a Set-Cookie response from /auth/google.
• On native mobile, enable a persistent cookie jar and reuse it for every API request.

A protected request returns 403 rest_cookie_invalid_nonce

• Send the login response’s nonce in the X-WP-Nonce header.
• Obtain the current nonce from /auth/session while the existing nonce remains valid.
• Do not send the Google ID token as the REST nonce.

Google login returns wrong_audience

The ID token’s aud value must exactly match WC API Pro → Settings → Google Client ID. Configure the frontend SDK to request an ID token for that OAuth client.

Shipping methods are empty

• Save a complete shipping country, state, postcode, and city in the customer profile.
• Confirm that the products require shipping.
• Confirm that a WooCommerce shipping zone and method match the saved address.
• Include coupon codes in the shipping request when free shipping depends on a coupon.

Online payment is not completed immediately

Non-COD checkout creates a pending order and returns payment_url. Open that WooCommerce URL to complete the selected gateway’s hosted checkout flow.

Upgrading to 3.0.0

Version 3.0.0 is a breaking API upgrade:

• The API namespace is now /woocommerce-api-pro/v1.
• Customer JWT authentication has been removed.
• Custom session authorization headers have been removed.
• Authentication now uses WordPress login cookies and REST nonces.

WordPress.org readme

GitHub renders this README.md. The accompanying readme.txt uses the separate WordPress.org plugin-readme format.

License

GPL-2.0-or-later.