- Using the WooCommerce REST API – Introduction
- Using the WooCommerce REST API – Orders Endpoint
My favorite feature from the recent WooCommerce 2.1 release is the REST API. I may be a bit biased, since it was my core contribution during the 2.1 release cycle, but it lays important groundwork. A platform like WooCommerce is strongest when shop data can be pushed or pulled from other systems, like a mobile app (spoiler: a WooCommerce iPhone app is coming soon!) or a complex integration with a backend accounting system.
In this series we’ll dive into each aspect of the WooCommerce REST API, starting with a general overview of the API, followed by a post on each type of resource that’s available. Before we begin, remember that the REST API is only available in version 2.1 or greater, so if you’re on an older version you’ll need to upgrade first. Let’s get started!
The REST API is read-only, with the exception of a single endpoint for updating order status. Data is available in either JSON (default) or XML format. There are 5 primary resources, each with a related set of endpoints:
The API can be accessed at
https://www.example.com/wc-api/v1 — note the
v1 version which takes a first-order position in every endpoint URL. This will only change for major releases and backwards compatibility is planned for at least one major version back, so you can safely build integrations against the version without worrying about a newer version of WooCommerce breaking your code 🙂
You can access the API over HTTP or HTTPS. I strongly recommend using HTTPS wherever possible, as it makes authentication significantly easier. The API Index (discussed below) will indicate if the site support SSL or not.
The default response format is JSON, which can be changed to XML by setting the HTTP
ACCEPT header to
application/xml. A successful request will return a
200 OK HTTP status, while unsuccessful responses will return non-200 statuses — a detailed listing of errors is available in the REST API documentation.
There are two ways to authenticate with the API, the easy way (over HTTPS) or the hard way (over plain HTTP using OAuth). If you’re developing an integration designed to work with any WooCommerce store, you’ll need to support authentication schemes, as you can’t guarantee that every store will have SSL enabled. The API Index endpoint will indicate if the site supports SSL.
With that in mind, login into your WP-Admin and go to your user profile to generate your API keys. You should see something like this:
Keys inherit the permissions of the user that generates them, so if you’d like to have more granular control over the permissions you can create a new user specifically for the API.
Simply use HTTP Basic Auth by providing the API Consumer Key as the username and the API Consumer Secret as the password:
$ curl https://www.example.com/wc-api/v1/orders -u consumer_key:consumer_secret
If you’re manually setting the HTTP Authorization header, remember that you must Base64 encode the keys first, like so:
php > $authorization = base64_encode( $consumer_key . ':' . $consumer_secret );
Over HTTP with OAuth
HTTP Basic authentication cannot be used over plain HTTP as the keys are susceptible to interception. The API uses OAuth 1.0a “one-legged” authentication to ensure your API keys cannot be intercepted. This process involves generating a signature and including it with your request. The API then generates it’s own signature and compares it against the one provided. If they match, the request is authenticated.
The process for generating this signature is not difficult, but it must be followed exactly. The best way is to use an existing library in your language of choice to handle OAuth authentication. If you’re a glutton for punishment and want to generate the signature manually, have a look at RFC 5849 which describes how to generate the signature.
Most API endpoints accept optional parameters passed as HTTP query string parameters, e.g.
GET /orders?status=completed — but the most important parameter is the
filter parameter. This parameter is used for date filtering, searching, and pagination. See the full list, along with examples, in the REST API documentation.
The API index provides information about the store, as well as a listing of available endpoints. No authentication is required to access the index. The most important property is
ssl_enabled which will indicate if SSL is available or not. A sample response is available in the docs.
Next in the series we’ll detail how to get order information, along with how to update the status of an order. Until then, here’s some additional reading about the API: