WooCommerce REST API Client Library

10 February

WooCommerce REST API Client Library

With WooCommerce 2.1 now out and about, it brings with it an array of new features and changes. One of these new features is the all new WooCommerce REST API.

The WooCommerce REST API comes bundled with WooCommerce 2.1+ and allows you all sorts of API calls to interact with your WooCommerce store data. You can get access to your Order, Customer, Coupon, Product and Reporting data all through the API.

Having it be a new API interacting with it can sometimes be a difficult task, that is why most software with API’s offer some sort of API Client Library which makes interacting with the API a breeze.

I have been spending quite a lot of time playing around and testing the API since its first commit into WooCommerce core and due to this built quite an easy to use and extendable API Client Library that I used to test and later on refined to make available to the public for use.

The WooCommerce REST API has two authentication methods, one legged oAuth 1.1, and Basic HTTP authentication, the method being used is all dependent on whether your WooCommerce store has a valid SSL certificate and if you have secure checkout enabled. I have developed the WooCommerce REST API Client Library to support both methods as the WooCommerce REST API require you to use oAuth when you have no valid SSL certificate and Basic authentication when you have secure checkout enabled with a valid SSL certificate.

Enabling the WooCommerce REST API

In order to enable the WooCommerce REST API and to start using it you will need to enable it in your WooCommerce settings.

This can be done by going to WooCommerce -> Settings -> General tab in the WordPress admin area, and then making sure the Enable the REST API option is checked. This should be checked by default.

Generating API Keys

In order to access data through the WooCommerce REST API you will require a Consumer Key and Secret. This is used to authenticate the API calls and to ensure that the call being made can access the data it is trying to access.

API Consumer Keys and Secrets are tied to users, which allows WooCommerce to restrict access to certain data based on the user role, so for instance if you set up the user to only have access to products and they try to access orders with their API details they will not be able to.

To generate API details head to either Users -> All Users or Users -> Your Profile in the WordPress admin area. If you followed the Users -> All Users path you will need to search for the user you want to generate API credentials for and edit it.

Once you are on the edit profile page, scroll down to the bottom of the page, there should be a checkbox to generate API Keys, check this and save the profile. Once the page refreshes, if you scroll down again there will be a Consumer Key and Consumer Password listed, and if you are a site admin you will also have the option to select read/write access.

Communicating with the WooCommerce REST API

Once you have the Consumer Key and Consumer Secret you are now ready to start interacting with the WooCommerce REST API.

This is where the WooCommerce REST API Client Library comes into play, you can now head to the WooCommerce REST API Client Library page on GitHub and download the PHP client library from there.

Once you have downloaded the PHP client library you will find a couple of file, the important one here is class-wc-api-client.php, this is the file you will need to use to be able to make use of the client library and make calls to the WooCommerce REST API. There is also a folder called example which shows you how to interact with the client library in order to make calls to your WooCommerce store.

Using the WooCommerce REST API Client Library

If the example code provided with the client library is not enough and the documentation listed on the GitHub page does not explain it well enough here is a quick intro on how to get started using the client library with the WooCommerce REST API.

Connecting to the REST API
In order to connect to the REST API of your store you will need to have the URL to your store as well as your Consumer Key and Consumer Secret ready. Use the following PHP code to include the client library and access the WooCommerce REST API of your store. Be sure to use https if you have secure checkout enabled on your site.

Making a call to the REST API
Once the client library has been initiated you can use the api object to make calls to the WooCommerce REST API, all the calls will return the data in JSON decoded format.

And that is it, for more documentation on all the available function calls, and how to call custom API endpoints added through extensions etc please see the README.md file on the GitHub page

Contributions are welcome, if you spot a bug or would like to add an enhancement feel free to fork and send a pull request.

Tags: , ,

Subscribe to my newsletter to receive the latest WooCommerce tutorials and news in your inbox. I promise I won't spam, I hate it as much as anyone else out there.

39 Responses to “WooCommerce REST API Client Library”

  1. Kathy 2014/03/03 at 15:44 #

    Hi Gerhard,

    I’m trying to wrap my head around this. Could you clarify something for me? The API Client Library is for building something on a 3rd party site to interact with your store? Whereas, if I want to handle notifications from a 3rd party site I you should extend the WC_API_Resource class?

    Thanks,
    -Kathy

    • Gerhard 2014/03/04 at 10:46 #

      Hi Kathy

      Yes this is exactly what this is for, for interacting with the WooCommerce API, if you want to build a custom API listener have a look at how the payment gateways do it.

      Eg.

      // This will trigger on http://example.com/wc-api/custom_api_call/
      add_action( 'woocommerce_api_custom_api_call', 'check_custom_api_call' );
      function check_custom_api_call() {
      // Do your API call stuff here
      }

      • Kathy 2014/03/04 at 11:05 #

        Awesome! Thanks Gerhard. That actually looks 100x simpler than what I was envisioning with end-points and much closer to what I had done previously.

  2. craig r 2014/03/03 at 18:57 #

    I feel like you should be given a little more credit for this than you have received. When I saw ‘no comments yet’ I was truly surprised. I was expecting a million stupid questions. :) . Anyways, thanks for working on this. It looks like it will be pretty cool.

    Thanks,
    Craig

    • Gerhard 2014/03/04 at 10:43 #

      Hi Craig, thank you very much.

  3. SimonR 2014/03/04 at 10:36 #

    Hello, I want to use the API, but my results always: {“errors”:[{"code":"404","message":"cURL HTTP error 404"}]}

    I created the keys and the url is http://localhost:81/wordpress/ . I enabled the RestAPI checkbox. Must i install more … ?

  4. August 2014/03/05 at 18:26 #

    Hey Gerhard. This is awesome. Thanks for the article.

    One question: when using get_order( $order_id ) in the API, does this call give access to any downloadable files that were attached to the order?

    I have a shop setup where I’ll need to give access to a third-party site to only specific orders, but I’d like for them to be able to get the same downloadable files from the original order. Is this possible with the current API?

    • Gerhard 2014/03/07 at 07:45 #

      Hi August

      At present no, however there is a open github issue on the WooCommerce github repo that is requesting an endpoint to get downloadable data from an order. This is something that WooCommerce will have to implement first before you can get access to that data.

  5. Kelowna 2014/03/07 at 04:28 #

    I’m trying to access my woocommerce store on a server from my local host and set up everything in the example php file and got:

    stdClass Object ( [errors] => Array ( [0] => stdClass Object ( [code] => 0 [message] => cURL HTTP error 0 ) ) )

    Any idea?

    • Gerhard 2014/03/07 at 07:43 #

      Hi Kelowna

      Under Settings -> Permalink, make sure it is not set to default. The REST API require permalinks to be enabled so try setting it to something like Day and name.

  6. Kelowna 2014/03/07 at 22:11 #

    Hey Gerhard,
    It is set to Day and Name and that is what I receive :( Any other possibility for that sort of error?
    thanks,
    –k

  7. Sivabalan 2014/03/27 at 11:31 #

    I got the error “stdClass Object ( [errors] => Array ( [0] => stdClass Object ( [code] => 404 [message] => cURL HTTP error 404 ) ) )". Idownloaded the code and replaced the keys. But i did get anything. Please help me

  8. Cesar 2014/04/01 at 21:26 #

    Hey Gerhard,

    Thank you very much for the article and congratulations for the work made.

    I am trying to work with your samples, and so far I am getting all products, but I would like to know how I can do to get the cart, login a user and finally process a payment.

    Any information or advice that you can provide in the subject would be very appreciated.

    Best,

    Cesar

    • Gerhard 2014/06/18 at 08:23 #

      Hi Cesar, sorry for the late response, however the API cannot be used to add items to a cart and process a payment. It is only meant to give you access to your WooCommerce store data from a 3rd party site/service/app.

      • Cesar 2014/06/18 at 16:47 #

        Thank you for your answer Gerhard.

        We found a different way to work with the Woocommerce classes inside jQuery Mobile to be able to add items to cart and process payment.

        Keep the good work.

        Best,

        Cesar

      • Kathy 2014/06/18 at 16:58 #

        Hi Gerhard, At WordCamp Chicago I heard there was a “create order” function in the works. Will you be posting about that any time soon? cheers!

  9. Keesjan 2014/04/15 at 09:39 #

    Hi Gerahard,
    is it possible to share woocommerce user-email name and passwords via the api with another application in a secure way?

  10. Christophe 2014/04/16 at 21:39 #

    I wish Woocommerce also added an API function to create coupons; seems there are only functions to get coupons at the moment.

    Nice work on the library though!

  11. Christophe 2014/04/16 at 22:07 #

    And seems you are involved in bringing this coupon functionality out as well. :-) Thanks!

    https://github.com/woothemes/woocommerce/pull/5044

    • Gerhard 2014/09/09 at 12:39 #

      Hi Christophe, that is correct I implemented the coupons PUT/POST/DELETE functionality that is due to be released with WC 2.2 in the next week or so :)

  12. babu lal 2014/05/09 at 09:27 #

    i ’m trying to access my woocommerce store on a server from my local host and set up everything in the example php file and got:

    stdClass Object
    (
    [errors] => Array
    (
    [0] => stdClass Object
    (
    [code] => 404
    [message] => cURL HTTP error 404
    )

    )

    )

    Any idea?

  13. Craig 2014/06/20 at 07:42 #

    Hi, is it possible to use the api to select products based on one or more assigned categories? Cheers Craig.

  14. Paul Singleton 2014/06/21 at 12:22 #

    Hi Gerhard,

    The direction of the Rest API seems to be guided towards store manager roles for backend analysis.

    I want to also contribute towards the Rest API, but wanted to ask if you think that this could be also designed to allow apps to call the API service for example: http://api.store.co.uk/products/add/productid=1234

    Thanks in advance,

    Paul

    • Gerhard 2014/09/09 at 12:28 #

      Paul, this is part of WooCommerce 2.2 which is due in the next week or two, which will enable you to add/remove/update products, orders, coupons etc.

  15. willy 2014/06/26 at 17:29 #

    Hello.. I have a problem, when try to getProducts returns only to 6 products, and i see 14 in thr getProducts/count
    Thanks

  16. Jack 2014/07/02 at 14:10 #

    Gerhard,

    While connecting to the REST API, I received the following disquieting response:

    stdClass Object ( [errors] => Array ( [0] => stdClass Object ( [code] => 301 [message] => cURL HTTP error 301 ) ) )

    I've already set the permalink as you suggested.

    Any suggestions would be appreciated.

    Thank you.

  17. Dinnae 2014/07/11 at 08:21 #

    Hi Gerhard!

    Please forgive me, I’m feeling confused. :) (that’s always a good way to start a post, isn’t it?) Wondering if you can help me understand why or why not (and WHERE) a woo shop should use the REST API? The documentation does not explain the parameters around situations we should or shouldn’t use it. I understand it’s used to access data via a 3rd party site, but which ones? There’s no specificity, and I’m feeling confuzzled. ;) And I understand it probably has very broad use, but even an example or two would help me get my head around it.

    Thank you!

    • David 2014/08/29 at 13:17 #

      Example: Our shop is on an external web server and we use the API to enable reading and manipulating orders directly from the ERP-system and the intranet.

  18. David 2014/08/07 at 15:24 #

    Hello Gerhard, very nice work, thank you.

    Our orders do contain custom fields – is it possible to get those via the API? I googled quite a bit for this, but did not find a solution.

    • David 2014/08/29 at 10:21 #

      Was simpler than I thought. In class-wc-api-orders.php I added

      ‘custom_field’ => get_post_meta($order->id, ‘custom_field’,true)

      to the $order_data array starting around line 113

      and everything works like a charm.

  19. Azamat 2014/08/13 at 11:58 #

    Kathy u can modify client api with original doc there http://docs.woothemes.com/wc-apidocs/source-class-WC_Cart.html#755-894.

  20. David 2014/08/29 at 17:45 #

    One more question.

    I can set customer notes using update_order – but it makes them private notes.

    What I need is to update the order with “real” customer notes so that the notification email is triggered.

    I found out that all notes have “customer_note”:true or false and those updated by the API are false, means private. I tried to hack class-wc-api-orders.php to make them all true but I couldn’t make it. If you, Gerhard or anyone else could give me a hint to the right direction how to do this, I would be very thankful. (Well, I already am for the API)

    • David 2014/09/01 at 11:26 #

      Made it: add in class-wc-api-orders.php around line 281:

      if ($data['kundenhinweis'] != ”) { $order->add_order_note( $data['kundenhinweis'], 1 ); }

      and of course, in my script, something like:

      $orders = $wc_api->update_order( $id, $data = array(‘status’ => $status, ‘note’ => ‘Via Intranet Script – ‘, ‘kundenhinweis’ => $kundenhinweis) );

  21. John 2014/09/10 at 17:20 #

    Hi Gerhard, thanks for this! I am trying to write a javascript (angular) application that can access the API. I’m trying to figure out how I can authenticate without exposing the client secret within my JavaScript. Could this library be used in some way to do that?

    • Gerhard 2014/09/11 at 11:04 #

      John I am pretty sure it is possible, this library takes care of the authentication, so if you can do a custom ajax endpoint that calls the library then you can just store the api credentials in the db and send it through when you call the library on the ajax action.

Leave a Reply