How to Use the WooCommerce REST API (v3): Setup, Authentication, and Examples

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.

To use the WooCommerce REST API, run WordPress 4.4 or newer with WooCommerce 3.5 or newer, enable a human-readable permalink structure, create a scoped key pair under WooCommerce > Settings > Advanced > REST API, and call the /wp-json/wc/v3/ endpoints. Over HTTPS, authenticate with HTTP Basic Auth using the consumer key and secret. Keep those credentials on your server, not in browser code.

This guide walks through setup, authentication, products and orders requests, the separate Store API, permission choices, and fixes for common 401 and server-configuration errors.

#	Preview	Product	Price
1		WooCommerce Explained: Your Step-by-Step Guide to WooCommerce	$15.35	Buy on Amazon
2		The Woocommerce playbook: The step-by-step guide to mastering Woocommerce and selling online	$25.00	Buy on Amazon
3		The Ultimate WordPress & WooCommerce Handbook: From Setup to Success in Online Selling	$12.90	Buy on Amazon

What the WooCommerce REST API does

The authenticated WooCommerce REST API is a server-to-server interface for managing store data and operations. The current and recommended version for new integrations is v3, whose base path is:

https://example.com/wp-json/wc/v3/

Depending on the resource and HTTP method, v3 supports create, read, update, and delete operations for products, product variations, orders, order actions, order notes, coupons, customers, shipping zones, and related store resources.

#1 Best Overall

Sale

WooCommerce Explained: Your Step-by-Step Guide to WooCommerce

$15.35

Buy on Amazon

Authentication is required because these endpoints can expose or change private business and customer data. A separate, unauthenticated Store API is intended for customer-facing product, cart, and checkout features. It does not provide the privileged store data exposed by the authenticated REST API.

Prerequisites and permalink requirements

Before generating credentials, verify the following on the WordPress site:

• WordPress 4.4 or newer.
• WooCommerce 3.5 or newer.
• Pretty permalinks enabled. In WordPress, go to Settings > Permalinks and select any human-readable structure, then save the change. The default Plain structure does not meet the documented requirement.
• HTTPS preferred. HTTPS protects credentials and request data in transit. HTTP requires a different authentication scheme and should not be the normal production setup.
• A WordPress user for the integration. The API key inherits the capabilities of the user selected when the key is created, so use a dedicated account with only the access the integration needs.

If the REST route returns a WordPress 404 immediately after changing permalinks, save the permalink settings again and confirm that the web server is forwarding requests to WordPress’s front controller.

Generate WooCommerce REST API keys

1. Sign in to WordPress with an account allowed to manage WooCommerce settings.
2. Open WooCommerce > Settings > Advanced > REST API.
3. Choose Add key (or the equivalent add-key control in your WooCommerce version).
4. Enter a descriptive key name, such as Warehouse integration production.
5. Select the WordPress user whose capabilities should apply to requests made with this key.
6. Choose a permission level: Read, Write, or Read/Write.
7. Generate the key and copy both the Consumer key and Consumer secret into your server-side secret store.

The consumer secret is displayed only once. If it is lost, revoke that key and create a new one rather than attempting to recover the old secret. Treat both values as passwords: do not commit them to source control, include them in support tickets, or embed them in JavaScript delivered to a browser.

Choose the correct WooCommerce API surface

Use v3 when a job needs privileged data or must create, update, or delete store records. Use the Store API when a browser-facing storefront needs public commerce functionality and should not receive administrator credentials. Do not substitute the Store API for an integration that needs customer records, private order data, or administrative writes.

Build the v3 base URL and endpoint

Start with your site’s HTTPS origin and append /wp-json/wc/v3/. For example:

https://example.com/wp-json/wc/v3/

Append the resource name to address a collection:

https://example.com/wp-json/wc/v3/products
https://example.com/wp-json/wc/v3/orders
https://example.com/wp-json/wc/v3/customers
https://example.com/wp-json/wc/v3/coupons

Append an ID for one record, such as /products/123, and use the HTTP method that the resource supports. Collection requests generally return a list; an individual resource request returns one record. Check the v3 resource documentation for fields and operations before sending writes, because not every endpoint permits every method.

Authenticate over HTTPS with HTTP Basic Auth

For HTTPS requests, provide the consumer key as the Basic Auth username and the consumer secret as the password. The credentials are sent in the Authorization header by a correctly configured client.

First smoke test with cURL

Run a read request against the orders collection. Replace the example credentials with the key pair generated in the dashboard:

curl https://example.com/wp-json/wc/v3/orders 
  -u consumer_key:consumer_secret

A successful response confirms that the URL resolves, the key pair is valid, and the selected user can read orders. Do not paste a real secret into shell history on a shared machine. An environment-variable form keeps it out of the command text:

export WC_CONSUMER_KEY='ck_replace_me'
export WC_CONSUMER_SECRET='cs_replace_me'
curl https://example.com/wp-json/wc/v3/orders 
  -u "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET"

Server-side JavaScript example

Use a server runtime, where the credentials remain private. This example requests products and checks the HTTP status before parsing JSON:

const key = process.env.WC_CONSUMER_KEY;
const secret = process.env.WC_CONSUMER_SECRET;
const auth = Buffer.from(`${key}:${secret}`).toString('base64');

const response = await fetch(
  'https://example.com/wp-json/wc/v3/products?per_page=20',
  { headers: { Authorization: `Basic ${auth}` } }
);

if (!response.ok) {
  throw new Error(`WooCommerce returned ${response.status}`);
}

const products = await response.json();
console.log(products);

Never move this code, the environment variables, or the generated Authorization value into a browser bundle. A browser request would disclose the key pair to every visitor.

Rank #2

The Woocommerce playbook: The step-by-step guide to mastering Woocommerce and selling online

$25.00

Buy on Amazon

Python example

The requests library can construct Basic Auth for a server-side script:

import os
import requests

response = requests.get(
    "https://example.com/wp-json/wc/v3/products",
    auth=(os.environ["WC_CONSUMER_KEY"], os.environ["WC_CONSUMER_SECRET"]),
    timeout=30,
)
response.raise_for_status()
products = response.json()
print(products)

Set a timeout and handle non-2xx responses in production. A retry policy should distinguish transient network failures from a permanent authentication or permission failure.

Create, update, and delete records

Read access is a safe first test. Write operations require a key with Write or Read/Write permission and a WordPress user permitted to perform that operation.

Create a product

Send a JSON body to the products collection with POST:

curl -X POST https://example.com/wp-json/wc/v3/products 
  -u "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET" 
  -H 'Content-Type: application/json' 
  -d '{
    "name": "Example mug",
    "type": "simple",
    "regular_price": "19.00",
    "description": "A product created by the integration",
    "catalog_visibility": "visible"
  }'

Use the field names and allowed values documented for the v3 product resource. Store the returned product ID instead of trying to identify the product by its display name.

Update a product

Address the product by ID and send only the fields that should change:

curl -X PUT https://example.com/wp-json/wc/v3/products/123 
  -u "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET" 
  -H 'Content-Type: application/json' 
  -d '{"regular_price":"21.00"}'

Confirm that the response represents the new state before marking the update complete in your own system. If a write can be retried, design it to be safe when the same request is submitted more than once.

Delete a product

Deletion is destructive. Use the documented delete behavior for the resource and test against a non-production site first:

curl -X DELETE 'https://example.com/wp-json/wc/v3/products/123?force=true' 
  -u "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET"

Only use a force-delete parameter when you have deliberately chosen permanent removal. Otherwise, follow the resource’s documented trash or reversible-delete behavior.

Read orders with filters

Collection endpoints accept query parameters documented for that resource. For example, request a limited page of orders and ask for a particular status:

curl 'https://example.com/wp-json/wc/v3/orders?status=processing&per_page=20&page=1' 
  -u "$WC_CONSUMER_KEY:$WC_CONSUMER_SECRET"

Handle pagination explicitly. A collection response represents one page, not necessarily the complete store history; record the page size and advance the page number until the response is exhausted.

HTTP authentication when HTTPS is unavailable

WooCommerce documentation requires one-legged OAuth 1.0a signing for HTTP requests. Basic Auth over plain HTTP would expose the key and secret to interception, so do not treat HTTP as an equivalent alternative.

Rank #3

The Ultimate WordPress & WooCommerce Handbook: From Setup to Success in Online Selling

$12.90

Buy on Amazon

OAuth 1.0a requires a signature generated from the request method, URL, credentials, nonce, timestamp, and OAuth parameters. Use a maintained OAuth implementation for your language rather than writing the signing algorithm from scratch. The practical production recommendation is to enable HTTPS and use Basic Auth, which is simpler to configure and avoids sending secrets over an unencrypted connection.

Use the Store API for public storefront requests

The Store API is a separate unauthenticated surface for customer-facing product discovery, cart interactions, and checkout features. Its public design does not grant access to private orders, customer records, or administrative settings.

Put public storefront calls behind the Store API’s documented routes and keep the authenticated v3 key entirely on your server. If a browser needs private data, have your server authenticate to v3 and return only the minimum data that the current user is authorized to see. Do not proxy arbitrary v3 paths from a public URL, because that can turn your server into a credentialed data-exfiltration endpoint.

Permissions and credential design

Choose the narrowest key scope

• Read: use for catalog synchronization, reporting, or any job that never changes store data.
• Write: use only when the integration must create or modify records and does not need to read them through the same key.
• Read/Write: use when both directions are necessary, such as a system that creates products and then reads their assigned IDs.

Permissions on the key do not replace WordPress and WooCommerce capability checks. The selected user’s capabilities still determine what the request can do. A key can therefore be syntactically valid yet receive an authorization error for a resource the user is not allowed to access.

Protect and rotate secrets

• Store keys in environment variables or a secrets manager.
• Use separate keys for development, staging, and production.
• Give each integration its own key so you can revoke one connection without interrupting others.
• Revoke and replace a key if its secret appears in logs, a repository, a browser bundle, or a support message.
• Redact the Authorization header and query-string credentials from application and proxy logs.

Troubleshoot common failures

401 Unauthorized

A 401 normally indicates one of three problems:

1. The consumer key or secret is wrong, incomplete, revoked, or paired with the wrong environment.
2. The selected WordPress user or key permission does not allow the requested resource or operation.
3. A proxy, FastCGI layer, or web server is removing the Authorization header before WordPress receives it.

Retest with a known-good HTTPS cURL command, verify the exact key pair in the WooCommerce settings screen, and confirm that the request reaches the intended site’s hostname. If a read request works but a write returns 401 or 403, inspect the key scope and the selected user’s capabilities rather than generating another key immediately.

The consumer key appears to be missing

When server software does not pass the Basic Auth header, WooCommerce may report that the consumer key is absent even though the client supplied it. Check proxy and FastCGI authorization-header forwarding first. The official documentation describes query-string credentials as a constrained fallback:

https://example.com/wp-json/wc/v3/orders?consumer_key=ck_replace_me&consumer_secret=cs_replace_me

Use that fallback only over HTTPS and treat the complete URL as a secret. URLs can be stored in browser history, reverse-proxy logs, analytics systems, and server access logs, so header-based authentication remains preferable.

SSL errors on localhost

A local development site may use a self-signed certificate that your HTTP client does not trust. Configure certificate verification for that development client or install a trusted local certificate. Do not carry an option that disables certificate verification into staging or production; it removes the protection HTTPS is meant to provide.

POST, PUT, or DELETE is rejected

Some hosting or proxy configurations allow GET but block other HTTP methods. Inspect the web server, firewall, proxy, and security-plugin rules for method filtering. Where the server cannot pass the intended method, WooCommerce documentation mentions an _method fallback; use it only when the endpoint and environment support that pattern, and fix the server configuration when possible.

The endpoint returns a WordPress 404

Confirm that the URL includes /wp-json/wc/v3/, that pretty permalinks are enabled, and that the request is reaching the same WordPress installation where WooCommerce is active. Saving Settings > Permalinks can refresh rewrite rules after a migration or configuration change.

Version choices and the legacy API

Use wc/v3 for new integrations. Older v1 and v2 routes are legacy choices and should not be selected for a new build merely because an old code sample uses them.

The legacy REST API was removed from WooCommerce core. An existing integration that still depends on that legacy interface requires the separate WooCommerce Legacy REST API plugin. Treat that dependency as a migration constraint: isolate it, document the plugin requirement, and plan a move to v3 where the needed resource is available.

A practical implementation sequence

1. Prepare the site: confirm WordPress 4.4+, WooCommerce 3.5+, HTTPS, and a non-Plain permalink structure.
2. Create a dedicated user and key: select the minimum Read, Write, or Read/Write scope needed.
3. Store the secret safely: copy the one-time consumer secret into server-side secret storage immediately.
4. Smoke-test authentication: call GET https://example.com/wp-json/wc/v3/orders with Basic Auth over HTTPS.
5. Implement one resource: add explicit status handling, timeouts, pagination, and structured logging with credentials redacted.
6. Add writes cautiously: test POST, PUT, and DELETE in a non-production store and verify responses before updating local state.
7. Separate public and private traffic: use the Store API for browser-facing commerce flows and keep v3 credentials behind your server.
8. Monitor and rotate: alert on repeated 401 responses, revoke exposed keys, and keep a record of which integration owns each key.

Quick decision guide

The reliable default is straightforward: enable HTTPS, generate a narrowly scoped key in the WooCommerce settings, call the /wp-json/wc/v3/ route from a trusted server, and reserve the Store API for unauthenticated customer-facing functionality.

Quick Recap

SaleBestseller No. 1

WooCommerce Explained: Your Step-by-Step Guide to WooCommerce

$15.35

Bestseller No. 2

The Woocommerce playbook: The step-by-step guide to mastering Woocommerce and selling online

$25.00

Bestseller No. 3

The Ultimate WordPress & WooCommerce Handbook: From Setup to Success in Online Selling

$12.90

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.