wc-api-php is a thin PHP client with a surprising auth rule

A thin wrapper, and thin is the design

wc-api-php is a PHP wrapper for the WooCommerce REST API, and the word wrapper is meant literally. The library does not add an ORM, a queue, a retry layer or a cache. It gives you a client object, a set of HTTP verb methods and a small number of options, and everything else stays on the WooCommerce side of the wire. The audience is a developer with a WooCommerce store and a PHP application or script that has to read or write store data, orders and customers being the obvious cases. The installation is a single Composer dependency, and the package is published under the automattic/woocommerce name:

composer require automattic/woocommerce

The package itself is MIT licensed and the repository is not archived, with the last push on 2026-10-05. There is a single listed release, 3.1.1, published on 2026-01-30, which is worth noting because the default branch is trunk and the repository has moved since that tag, so the published version and the head of the branch are not the same thing. The working tree is small and conventional, with src/ and tests/ at the root, a composer.json and composer.lock, a phpcs.xml for coding standards, a phpunit.xml.dist for the test suite, a .scrutinizer.yml and a Scrutinizer quality badge, and a GitHub Actions workflow for continuous integration.

HTTPS gets BasicAuth, everything else gets OAuth

The authentication rule is the one piece of the client you have to understand before anything else, and the README states it in one sentence. If using a HTTPS connection the library uses BasicAuth, otherwise it uses OAuth to provide a secure connection to WooCommerce. The reasoning is straightforward. Over TLS the transport already protects the credentials, so a consumer key and secret can simply be sent as basic auth headers, while over plain HTTP the requests are signed with OAuth so that the credentials are not transmitted in the clear. Two options let you override that behaviour. The query_string_auth option forces Basic Authentication as a query string when it is true and the connection is under HTTPS, and the oauth_only option limits requests to OAuth only and disables Basic Auth entirely. A third, oauth_timestamp, lets you supply a custom OAuth timestamp instead of the default of time(), which is the kind of option that exists for testing and for replaying signed requests. If you deploy this against a store whose certificate chain your PHP install does not trust, the verify_ssl option can be set to false, which the README ties to testing with self-signed certificates, and that is a decision to make in a test environment rather than a production one.

The options table is where the real behaviour lives

The client options table is the most information-dense part of the README, and several entries change behaviour in ways that are easy to miss. The version option sets the API version and defaults to wc/v3. The timeout option sets the request timeout and defaults to 15, which is worth noting because a large product export over a slow link will hit it. The wp_api_prefix option overrides the WP REST API URL prefix, and the README says it exists to support custom prefixes created with the rest_url_prefix filter, so it is a compatibility hook rather than a convenience. The wp_api option, set to false, switches to the legacy WooCommerce REST API, which the README marks as deprecated and not recommended. The user_agent option sets a custom user agent with a default of WooCommerce API Client-PHP. The follow_redirects option decides whether the API call may follow redirects. Two of them exist purely to work around servers and proxies that refuse certain verbs. The method_override_query option masks all non-GET and POST methods by using POST with a query parameter, and method_override_header does the same with an X-HTTP-Method-Override header, which is what you reach for when a hosting environment blocks PUT and DELETE on the request path.

Five methods with one shape

The client surface is deliberately uniform, which is what makes it pleasant to use. There are five methods, get, post, put, delete and options, and they all take an endpoint string. The arguments table says the endpoint is a WooCommerce API endpoint, with examples such as customers or orders/12. For get and delete the second argument is a parameters array, which becomes the request query string. For post and put it is a data array, which is converted to JSON. The options method takes only the endpoint. The response contract is equally uniform, since all methods return arrays on success or throw HttpClientException errors on failure, and the exception class lives under the Automattic\WooCommerce\HttpClient namespace. The methods are as short as they look:

$woocommerce->get($endpoint, $parameters = []);
$woocommerce->post($endpoint, $data);
$woocommerce->put($endpoint, $data);
$woocommerce->delete($endpoint, $parameters = []);
$woocommerce->options($endpoint);

One consequence of that contract is worth stating plainly. A failed call is an exception, not an error code in the returned array, so a call site that reads products has to be inside a try block or it will take the whole request down, and a large batch job needs its own error handling per call.

Getting at the last request and the last response

Debugging an integration with an HTTP client is the part that eats evenings, and the client exposes the last request and last response through the http property. The README shows the shape of it:

  // Last request data.
  $lastRequest = $woocommerce->http->getRequest();
  echo '<pre><code>' . print_r($lastRequest->getUrl(), true) . '</code><pre>'; // Requested URL (string).
  echo '<pre><code>' .
    print_r($lastRequest->getMethod(), true) .
    '</code><pre>'; // Request method (string).

The same pattern continues for the parameters, the headers and the body, and the README then starts a last response section that is cut off part way through in the version available here, so the full accessor list for the response object is not documented in the text and you would need to read src/ to confirm it. The request accessors are shown in full, and they are the part you will reach for most often.

Where this client will not help you

There are three cases where wc-api-php is the wrong size of tool. The first is a single script that makes one or two calls, because the direct route is short. The WooCommerce REST API is a plain HTTP API with documented endpoints, so a call with curl and the consumer key and secret is a few lines, and adding a Composer dependency to a script that runs once a month is not obviously better. The second case is a non-PHP system, where this client is simply not applicable and you would be calling the same REST endpoints from another language. The third case is where you need behaviour the client does not have. There is no documented retry, backoff or rate-limit handling, the timeout is a flat 15 seconds with no per-endpoint override, and the README does not describe any cursor or pagination helper, so walking a large product catalogue means you handle the page parameters yourself. The options table is long, but it is long about transport rather than about business behaviour. There is also the security judgement to make deliberately. The verify_ssl option can disable certificate verification, and the query_string_auth option puts credentials in a URL, where they are far more likely to be logged by a proxy, so both are fine in a controlled test and bad defaults for production.

The direct REST call versus the client, and the plugin route

The realistic alternative is calling the WooCommerce REST API directly from your PHP code with your own HTTP client, and the difference in approach is mostly about who owns the details. Calling directly means you write the credential handling, the JSON encoding of the request body, the query string construction, the exception mapping and the request logging. The client does all of that, and adds the method masking options and the request and response introspection, which is what saves time when a store is misconfigured or an endpoint behaves differently than the documentation suggests. There is a second alternative worth naming, and it is architectural rather than a different library. A WooCommerce plugin runs inside the store itself, with direct access to the WordPress and WooCommerce internals, so it avoids the HTTP layer, the credentials and the API version entirely. The trade-off is that a plugin only exists inside a WooCommerce installation and cannot be called from outside it, while an API client can be called from anywhere, which is why integrations, migrations and reporting jobs reach for the REST client and anything that needs to act on the store itself reaches for a plugin. The client is the right answer when the work is outside the store and the plugin is the right answer when the work is inside it.

Editorial conclusion

wc-api-php suits a PHP codebase that already talks to WooCommerce and wants authentication handling, JSON encoding, method masking and exception-based failures handled in one place. It does not suit a one-off script, where calling the REST endpoints directly is shorter than adding a dependency, and the fact that the client is thin means every WooCommerce API change still lands in your code. Before adopting it, check that the wc/v3 endpoints you need exist, decide whether your connection will be HTTPS, since that choice determines the authentication path, and note the last push was on 2026-10-05 with the listed release 3.1.1 published on 2026-01-30.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. woocommerce/wc-api-php on GitHub