The WooCommerce REST API lets an external application read or change store records through HTTP requests. A connection normally uses a consumer key and consumer secret tied to a WordPress user. Before connecting an export, reporting tool, or migration service, separate three questions: did authentication succeed, may this key read the requested records, and did the application receive everything it needs?
A successful product request does not prove that customer records are readable. A 401 response does not always prove that the secret was copied incorrectly. Those distinctions can save you from granting unnecessary write access or repeatedly replacing a valid key.
What the WooCommerce REST API connects
The API exposes store resources such as products, orders, customers, and coupons. An integration sends a request to a resource URL and receives structured JSON. Reading a product and updating its price are different operations, even when they use the same connection.
WooCommerce’s developer reference documents the WordPress-integrated API and its wc/v3 endpoints. For example, a product collection uses /wp-json/wc/v3/products on a store with the documented permalink setup. The reference also explains pagination. One returned page is not necessarily the whole catalog; collection responses include total-count and page-count headers.
Think about the job before choosing an integration. An export needs a defined set of records. A synchronization service also needs rules for later changes, deletions, and conflicts. Authentication alone proves neither completeness nor ongoing synchronization. For a migration, keep your product data checklist separate from the connection check.
Give the key the access the task needs
WooCommerce offers Read, Write, and Read/Write key permissions. The key is also linked to a WordPress user. Both the chosen permission and that user’s access matter. An application that only reads source records should not need permission to edit them merely to establish a connection.
Use WooCommerce’s key-management instructions as the setup reference. In WordPress, the documented path is WooCommerce > Settings > Advanced > REST API. Give the key a description that identifies the application, select the appropriate user and permissions, and store the generated credentials securely. The consumer secret is shown only once.
Before granting access, write down the required scope:
- Catalog export. Assess read access to products and required related records. Check variants, images, identifiers, and pagination for completeness.
- Order reporting. Assess read access to the required orders. Check the date range, status filters, currency, and refund handling.
- Customer transfer. Assess read access to the required customers. Approve privacy obligations and destination field mapping separately.
- Stock or price updates. Assess write access for the approved operation. Use a controlled test to confirm that only intended records change.
These are planning checks, not a promise that every connector supports every task. Confirm the connector’s requirements before creating the key. Never post the key, secret, authorization header, or an unredacted request URL in a public support thread.
Diagnose a refusal before replacing credentials
Start with the exact resource, HTTP status, and returned error code. Keep credentials out of the evidence you share. A JSON error from WooCommerce is different from an HTML login page or a hosting firewall response, even if the application calls all three a connection failure.
- Authentication or signature error. Check the key-secret pair and the client’s authentication configuration.
- A resource cannot be read. Check key permissions and the associated user’s access to that resource.
- Products work but another collection fails. Test that collection separately; do not infer store-wide access.
- A route is missing. Check the API path, version, permalink setup, and whether WooCommerce is active.
- Rate-limit or server error. Check the host’s response and retry guidance rather than changing credentials.
WooCommerce’s connection troubleshooting specifically notes that some servers do not parse the Authorization header correctly. It also asks users of FastCGI to check whether authorization headers are read. A key can be valid while the hosting path prevents it from reaching authentication correctly.
Keep HTTPS and certificate verification enabled for a real store. Do not put the consumer secret in a shared URL to make a test easier. Ask the host or integration maintainer to inspect header forwarding and authentication support. Our HTTPS explanation covers why a protected connection is a separate requirement from application permission.
A Runner source example: valid keys can need another path
Runner’s WooCommerce migration client illustrates the distinction. In the source inspected for this guide, WooCommerceRestClient starts with HTTP Basic authentication over HTTPS. If a 401 indicates that WooCommerce did not recognize a user, rather than an explicit key error, the client tries an OAuth-signed request. It retains a method that succeeds for subsequent requests in that client.
The signed request uses the consumer key and a signature, not the consumer secret in the URL. The source also accommodates a proxy that makes WordPress perceive the request as HTTP when constructing the signature. The outgoing request still uses the discovered HTTPS store address. This is not a reason to downgrade the public store to HTTP.
The accompanying regression cases cover a stripped authorization header, proxy scheme differences, invalid credentials, and secrets staying out of request URLs. Other cases cover partial access: products can be readable while customers or shipping are not. That is useful evidence for a connector’s design, not proof that every store will accept the same fallback.
Disclosure: Runner AI publishes this guide. This example describes inspected source and test cases, not a live migration or a claim that the WooCommerce connection interface is available to every account. The source pointer is WooCommerceRestClient in woocommerce-rest-client.ts, in the server package’s store-migration infrastructure service. Its companion authenticator tests cover the cases described above.
If you are evaluating a platform change, use the Runner WooCommerce alternative overview for that separate decision. For supported day-to-day Runner operations, the Store Operations guide owns the product instructions. Neither page replaces verification of a particular source-store connection.
Related questions
Does a 401 mean my WooCommerce API key is wrong?
Not necessarily. Wrong credentials are one possibility, but resource permissions and server handling of authentication also matter. Read the returned error code and compare the exact failing resource. If the host drops the authorization header, generating another key without fixing that path may produce the same failure.
Should I enable the legacy REST API?
Only when the integration explicitly requires it. WooCommerce’s merchant documentation says the legacy API was removed from core and needs a separate extension. The WordPress-integrated wc/v3 API is a different interface. Do not enable a legacy service merely because an old tutorial starts with that checkbox; confirm the endpoint your application uses.
Is a read-only key enough for a migration?
It can be enough to read the source data, provided the associated user can access the required resources. Destination writes are a separate permission decision. Confirm which source records the migration needs, test each required collection, and review missing or unsupported fields before interpreting a successful connection as a complete transfer.
How do I know the connection is ready?
Verify a small, authorized read from each required resource and inspect the expected JSON without exposing private records. Then check pagination, field coverage, and destination mapping separately. Keep a record of the tests and revoke credentials when the integration no longer needs them. The WooCommerce REST API connection is ready for a particular task, not automatically for every operation.