 Okay. Thank you. Welcome to the WooCommerce REST API integration session. I'm going to be talking through the benefits of integrating with the WooCommerce REST API. Just a quick show of hands. Who's currently using WooCommerce on a WordPress website? Okay. And anyone currently doing any work with a WooCommerce API? A few of you. Great. Okay. So just a bit, oops, a bit about me. My name is Andrew Duncan. I'm the CEO, owner, developer, cleaner, and everything else at a kind of called Databuzz. We're a Sydney-based software development company. I started my software journey almost 30 years ago now. So that makes me feel very old at this moment in time. I actually started here back at UTS back in the late 1980s. And when I was here at UTS, all this talk of Gutenberg and printing presses jogged a few memories in me. And this building was actually owned by Fairfax. And this whole basement was actually one big massive printing press. And you'd come here and they'd be printing off the Herald and the Australian Financial Review of a night. And those days are long gone. So it's a bit of a sign of the times. Okay. So we're going to be talking about WooCommerce. Just a quick bit about WooCommerce for those who are not familiar with it. It's the plug-in for WordPress. It turns your WordPress site into an online shop. It's open source. It's free. It's customizable. There's over 400 extensions for WooCommerce alone, both paid and free. It was started in September 2011. And as you can see, they've had gazillions of downloads since then. And it's now part of the automatic family. Okay. So I just want to talk a bit about my journey to how I got here to be doing some doing a lot of work with the WooCommerce API. So I'm a WordPress user. My company's got two WordPress sites. And about five or six years ago, we sell software products. About five or six years ago, we realized Winnie's have a better online shopping experience. We were just using some big chunky PayPal buttons, Pay Now buttons, back then. And customers would click the button and go to the PayPal site, fill in the details. And we'd get an email. Someone had bought something. That was, firstly, that was very exciting. But we then had to reply to an email, attach the thing that bought, send them a tax invoice. Often that email would bounce. Of course, the attachment was too big. And if someone bought it in, say, Friday, US time, they wouldn't get their software until Monday, Australian time. And often they would think that we'd sort of scan them, share their money. So it wasn't a great experience for anyone. So about five or six years ago, yeah, I looked into what was out there and found WooCommerce. And within a short period of time, we had two WooCommerce sites up and running. And we were doing online orders, online software downloads, instant tax invoices. We didn't have to do anything. So life was really good. The only missing piece of the puzzle for us was we needed to get the data out of WooCommerce into our internal company systems and ultimately into our accounting systems, because we don't use WooCommerce to run our business. We use WooCommerce to run our online shop. But we have other software applications to run the business, like a CRM and an accounting system. So being software developers, we thought, let's use SQL. Most of you probably know that WordPress and WooCommerce have got a MySQL back end. And it made sense to us at the time. So we did a bit of research and worked out how to create a sort of complicated SQL view with lots of joins. That looks terrible on the slide for some reason. And it sort of worked. But if you've ever worked with the back end tables, there's no orders table. There's no customers table. There's no products table. There's no order line items table. So you got to sort of use the post and the post meta table and work all that out yourself. I'm not sure why that looks terrible. My rest of my slides don't. OK, so that led us to the WooCommerce API. And we're not sure why we didn't start with the WooCommerce API in the first place, because our company specializes in integration and we work with APIs sort of all day, every day. So for those who are not familiar with what an API is, so API stands for Application Programming Interface. There's the definition from Wikipedia. I essentially like to think of as a document that sets out the rules for getting my software talking to your software. And APIs are everywhere these days. There's companies built on APIs. There's some of the companies you would have heard of. They're all sort of got APIs. So Twilio is a company built around APIs for messaging and voice. In the accounting space in Australia, Zealand, Xero and MYB have got APIs and big developer ecosystems built around those. And of course WordPress itself and WooCommerce. So why would you use the WooCommerce API? So for a lot of people, it all comes down to one word and that's integration. In our business, we want to get the orders out of WooCommerce into our Serum system, and then we want to get them into our Xero, which is our accounting software. And the whole point of this is here to remove any sort of double data entry, double handling. That all leads to mistakes and that's not the most rewarding work to do in the world. We've got lots of customers that have very complex sort of inventory systems, and they've been using that for years, and they want to get their inventory data pushed up into WooCommerce. They don't want to have to maintain two separate inventory systems. They just want to have a single source of truth. You might want to be doing bulk updates, so you might want to have a sale, drop the price of certain products, change their descriptions, and you've got all that in the inventory system and you just want to make that and push them all up in one go without having to go and recreate those changes in WooCommerce. We've also got some other sort of interesting use cases. We've got some customers that want their customers to pay for an order, but they don't want their customer to go to the WooCommerce site, find the products, add them to the cart, go to the checkout page and go to the payment page. They just want to send them to a page where they pay. So using the WooCommerce API, you can actually create an order, add the line items, put in the customer details, upload it, get the payment page link and just send that to the customer and they're just going to pay for it. It seems strange, but that's how some customers roll. So the benefits of all this is saving time, saving money, getting stuff away from sort of manual repetitive tasks, double data entry, and that all leads to a state of peace and calm and Zen-like state that I like to think about it. In our business, it's a good feeling when we wake up in the morning and we've had some orders overnight and we know that they've automatically ended up in our Serum system and they've automatically ended up in our accounting system and we haven't had to do anything, essentially. So let's get into the details of the WooCommerce API itself. So there's the URL for the Github, the documentation. It's very well documented. Version 2 is the current version. Now, you don't need to install the API or enable it, it's just in WooCommerce, everyone gets it automatically. At the moment, everyone gets version 1 and version 2. Version 2 came out with WooCommerce 3, so version 1's been deprecated as of what they call their previous legacy API, so don't use version 1 or the legacy ones. Start with version 2, it's the only one being maintained. It's fully integrated into the WordPress REST API, so it's a RESTful API. You can use standard HTTP verbs, which many of you are probably familiar with, like getPostPutDelete to make requests and get a response back and it uses REST API authentication. On the docs, you'll see code samples for a lot of the popular programming languages like Curl, Nages, PHP, Python and Ruby. So, I think I missed a slide there, let me go back. Yes, so when you're working with an API for the first time, no matter what API it is, the first thing you're normally going to do is work out how to authenticate. I can't upload or download until I've solved the authentication piece of the puzzle. And with WooCommerce API, you get two ways to authenticate, and that depends whether your site's been served over HTTP or HTTPS. I'm not going to talk about authentication over HTTP. It's this complex OAuth 1.01-legged authentication system. It's quite a lot of series of steps. And the reason essentially is if you're using WooCommerce, you're capturing customer data, order data and payment data. Your site really shouldn't be served over HTTP unless you're just developing locally. And authentication is much easier over HTTPS and SSL certificates are extremely cheap these days and you renew them for 30 days and it takes 20-30 minutes to install. So there's really no reason why in my mind at least you shouldn't be using HTTPS and SSL. So the way it works with HTTPS is you generate a set of REST API keys. You use the name of a consumer key in a consumer secret and they become your username and password when you use the HTTP basic auth header. So every request you send to the API, you've got to include your authentication header and that's simply your REST API keys. So how do you generate your REST API keys? Well, you go into the WooCommerce admin and I'll show you this in a minute and you go and generate some REST API keys and they'll generate a consumer key and a consumer secret. Sorry, my screenshots look really bad. Okay. So now that you've got your REST API keys and your authentication part is solved, I just want to talk through each of the different types of common requests that you might make. So there's, broadly speaking, there's two types. There's the upload request to WooCommerce and there's the download request from WooCommerce to your application. So let's start with uploading and talk about creating a recording WooCommerce. So you might want to upload a customer, a product, a category, a tag, whatever it might be. So you'll be doing a post to an endpoint. So in this case I've got an example for doing a post to the customer's endpoint. So to do that you need to include your authentication header. We're going to be sending all the data for the APIs in JSON format. So you're going to be sending a JSON payload of your record that you're going to upload and so you need to include the content type application JSON header as well. So here's an example of what a create customer request would look like. So we're doing a post to the customer's endpoint. We've got our consumer key, consumer secret authentication header and our content type header and then it's just the JSON data of the payload that we're uploading. When you create a recording in WooCommerce you're going to get back the recording in response and that's going to include the WooCommerce ID and you're typically going to want to pass out that ID and capture it and store it because if you ever want to do anything to this record again, whether it's deleting it or retrieving it, you need to know the ID. So the ID will be included as an additional field so you just got to be able to grab that and store it in your system. So an update request is very similar to a create request except this time we're doing an HTTP put. So an API well post is normally create a resource puts normally an update a resource. This is where you need to know the ID because you're going to append the ID to the end of the URL and you're going to be uploading to and you're going to be authenticating in the same way, content type editor in the same way and we're going to be sending an adjacent payload as well. Here's an example of an update request very similar to a create request. The difference here is you only have to send the changes if you want to you don't have to send the full record so you can have a much smaller payload in our business we just the process for creating a record and updating is exactly the same because for us programmatically it's easy just to send the whole thing again not have to try and work out the differences and capture the delta and just upload that. But if we were to update the status of an order in WordCommerce we just send up the status in that case because it's easy just to send up the status rather than the whole order record with all the line items and text lines and so on. Okay so that's uploading create an update now I'll talk a bit about downloading with downloading there's two broad types of requests you're going to make you want to make a request to get a single record or you might want to make a request to get a lot of records so give me all the orders from yesterday or give me all my products in this category or give me all my customers. So to request data you're going to be doing an HTTP get and that's going to go to so let's talk about a single record first so once again you need to know the idea of the record that you want to get when you're doing a single request and we're not sending any data any payload JSON data we're just saying go to that URL and get me that record so all we have to do is pass in the authentication header only no content type header or JSON payload and the response will be the same as for a put or an update you'll get the full record back with all the data returned and that's what a get request might look like and you can see that's the same for a post and update the IDs part of the payload there so when you're doing a postal request that's where the idea comes in and you go and grab that okay so it's a single record request now talk a bit about getting multiple records so in our business we often want to download all the orders between a particular date range so once again you do an HTTP get request to the particular endpoint so orders in this case same as a single record there's no authenticate there's no payload content type header just the authentication header and in this case you're going to get a JSON array so a series of records are going to come back and once you start working with multiple record requests you can start to use parameters and pagination which I'll talk about a bit more in a second but if we look at my example here I'm saying get me all the orders after this timestamp and before this timestamp and give me page one and order them by the ID and in ascending order so that's an example of some of the parameters that you can include and they're all on the work on this document API docs pages okay so pagination is important most APIs when you make a request to get a lot of records I'm going to return every single record because that could potentially be thousands of records that's going to swamp your connection and something's going to crash or run out of memory at some point so there's normally limits of how much data records you can get at any one time with WorkCommerce the default is 10 items per page and you can override that by specifying a value for the per page parameter so you can increase that or decrease that as your needs fit and you can choose which page you want to get using the page parameter so combining the page parameter and the per page parameter leads to which records can be returned now when you get all the records back you could go through and count how many you got and try and work out if you need to make another request or you can just look in the response headers that will come back from the API and there's two in particular the XWPTotal and the XWPTotal pages response headers which I'll show in a sec and they tell you how many records were found in your request and how many pages you're going to need to get them all and it also includes what's called the link header rather than you trying to work out what the URL for the next request for page 2 might be it'll include that and give it to for you so here's what the response headers look like I've hollered a few things in red so at the top is the response code so generally with any API when you're making a request you want to check the response code and see if it was successful so the 200 series are the successful requests and talk a bit more about that in a minute and in the middle there's the XWPTotal and the XWPTotal pages so my request led to 21 records been found and with the default of 10 items per page I'm going to have to make 3 requests to get those so page 1 is records 1 to 10, page 2 11 to 20 and page 3 is record 21 and because there's another page it tells me what the link to that second page that I could then go to and that's page 2 there so I just would need to retrieve that and that becomes my URL for my second next request and so on okay so the final type of request I want to talk about is the delete request in this case you're going to be doing an HTTP delete to the particular end point very similar to the get and the update in that you're going to need the ID of the record that you want to delete and you're not uploading any data you're just saying delete this record essentially so you just need to pass in the authentication header the only difference here is some resources and it's all in the WooCommerce API documentation don't support the concept of Trash in where you delete something that just goes into the Trash the documents will tell you this but sometimes you've got to include this four sequels true parameter and that will permanently delete the record straight away so check the docs and it'll tell you whether you need to include that four sequels true parameter and if so the record gets deleted immediately you'll get the full authentication record back but it's gone at that point okay so just some tips that I've sort of picked up over the years of working with the various WooCommerce APIs timestamps are always in the ISO 8601 format so year month, date and then the time as I mentioned earlier you should always be checking the response code to see if your request was successful you can't rely on anything else essentially so 201 are the success codes for a creator and update if you get a 400 error for example it's a bad request Jason was invalid or you had an authorized error issue with your API keys 500 series means you've got some sort of server error and so on so always be checking for the response code if you're going to be uploading products and product images the WooCommerce API you can upload an image by passing the URL to that image so it can pull it down and ingest it or you can pass in the WooCommerce Media Library ID for that particular image if it's already in WordPress Media Library sorry if you want to upload local files the WooCommerce API doesn't support that you've got to use the WordPress Media API to upload the file first get the ID and then you can upload that reference that in your file most of my customers you need custom fields for their WooCommerce sites they they need more fields than the WooCommerce core provides so they need fields for customers for orders for products and there's various ways you can create those custom fields you can do it in PHP or you can use one of many custom field plugins out there so the WooCommerce API has no knowledge about any custom fields that you might have in the data section and I'll show an example of that shortly so just keep that back in mind if you create custom fields WooCommerce won't know about them but the metadata will yep, encourage you to report bugs if you find any I've found about a dozen over the years and I've reported them and I've been very impressed with how quickly they've been fixed they're normally getting included in the next release of WooCommerce in my experience so please report your bugs via the GitHub page if you're not sure where to work recommend a tool like Postman it's a free HTTP client that you can use to create these requests send them and check the response so just go to getpostman.com and I'll give you a quick demo of one of those in a minute and finally webhooks complement the API very nicely anyone using webhooks with WooCommerce at the moment yep so in our business when we get a new order we have a webhook that fires off and that sends that order to one of our servers we then use the API to pull down the full details of that order and then we send it off to zero okay in software so webhooks and the API work very nicely hand in hand together okay so let's have a quick few demos okay so this is Postman it's a free HTTP client and I won't go into the details of how Postman works but essentially you can create a request so I'm saying I want to create a post request and I'll put in the URL of my site so I'm going to say I'm going to use the products tag so I'm going to create a new product tag in my WooCommerce site and if I go to authorization I'll set I want to use basic auth and I'll put in my consumer key and consumer secret for my REST API keys and then I just need to put in the body so the documentation tells me how I need to construct the body so in this case I just need to pass in the name of the tag I want to create so I'm going to call it WordCamp Sydney and I'll go and send that off and assuming I'm on the internet there we go so you'll see it's come back with the JSON response so it's created a tag ID number 93 it's given it a name a slug I left the description blank it's given me the URL it's given me all this data data for it but that's how easy it is to create a product tag and you can obviously do that in bulk and create lots of tags okay so that's a quick demo of Postman so here's the here's what the documentation looks like on the WooCommerce site so my screen's got very truncated here it takes you through all the authentication and so on and then you can jump into the details for each of the particular endpoints so let's have a look at uploading a let's have a look at downloading so I'm going to switch over to it's very small here this is a solution let's just see if I can zoom out no I can't oh it's okay excellent hopefully that's not too small but this is a solution we do a lot of work with the file maker platform file makers of Apple subsidiary they make a platform for Mac windows iOS and the cloud and it's popular with small businesses and a lot of small businesses use FileMaker and WooCommerce but they use FileMaker to run the business and they've got to get data out of FileMaker into WooCommerce and orders out of WooCommerce into FileMaker so this is an example of how it might work I'm going to go to my little orders tab and I'm going to say get me all the orders these two dates and I'm just going to hit import orders and that's going to go and make a request to the API get a date range of orders and they will download it successfully so if we have a look at one of those you can see it's pulled down the order it would have got all the order line items as well and all the taxes and so on and if I look at my metadata tab so I've just passed out the whole sort of order array that's come back there's an example of a custom field that's called shipping phone number there is no shipping phone number field in WooCommerce so we've credit a custom field for that and that's how we can capture that okay if I wanted to upload a product I've got a credit a blank product here filled in all the mandatory fields such as the status and the price and the description and the name and the inventory settings and that's pretty much it for the mandatory stuff and I've said I've got an image and the ID is 3.5.6 that's already in my WordPress media library so now if I go and push that up to WooCommerce that's been uploaded so if I switch over to my WooCommerce site look at my products just refresh that zoom out there you can see the product is being created and it's got the image so that's how easy it is to upload a single product and obviously I could do that in bulk and upload a whole series of products and I meant to show how to create the API keys so here I'm in WooCommerce in the so go to WooCommerce I go to the advanced section and then I just go to so don't confuse it with the legacy API just ignore that just go to the rest API and click the add key and basically you give it a description so demo choose the use you want to associate with the key then you need to set the permission so you can make it read, write or read and write whether you're going to be just retrieving data or you want to be updating data as well and then you click generate API key and there's your keys now at this point you've got to go and copy and paste them and store them somewhere else because as soon as you leave this screen you'll never be able to see them again and you'll have to go and create a new set as well so once you go back and leave this page there's my keys that I just created but if I go into it again it's not going to show me the keys it'll tell me the last few digits of the consumer key and I can go and work out what they are if I had them stored somewhere but if you didn't make a note of them delete and start again or evoke the key yeah okay I think that was it for my demos yeah at this point I'm happy to open up for questions if you've got any questions out there hi thanks I'm curious about how you build in resilience against failure especially when you're talking about webhook triggered API calls if you've got network problems the request times out you're likely facing a unsynchronized or unmatched data in your two systems I'm wondering about how you approach that yeah that's a tricky one we don't have a perfect solution for that the webhook won't continue to try X number of times over X period of time I think it's a once only from memory so if that doesn't work the only way we know about that order is the email that we get from WooCommerce to say you've got a new order and it's someone's job in our office to go and just check the orders in our system and make sure everything's there so we'll sort of pick it up quickly but if it's not there the email has the WooCommerce order ID so we just copy and paste that into a field and hit download order from WooCommerce and we get it that way and we're not doing large volumes of orders so we can live with that process some customers have gone down the road where they use a better destination for receiving the webhook like an AWS hosted service or something that's very unlikely to ever go down and always be accessible they pull the orders down from there but yeah it's a tough one that one when things break and they don't work and then you got to manually pull them down and yeah yeah thank you any other questions yeah just about the year old when you said like you get it from a third party link for the images does it import it into the WordPress media library it does yes so yeah you want to avoid duplicates because if you include that year old you can't upload the product it'll just keep downloading that so yeah that photo for example has to be publicly accessible by so WooCommerce can download it and yeah it's going to add it to the media library and create a record in there and you can always reference it by it'll return the idea of that image as part of the product record that comes back so you can sort of capture that and store that in your system so you don't have to so it'll never upload it again but yes every new image that you upload will get imported into WordPress yeah cool and will the slides be like posted somewhere yeah I don't know if the slides are centrally posted anywhere but I'll certainly put them on my website in the next couple of days thank you anyone else more questions I had one about capabilities does the if you authenticate using the the customer key and secret do you get full capabilities or is it restricted to like an admin role or a shop owner role well it's when you create I'll just create a new one these are the two settings here that determine that it's whether you say read, write or read and write and which user you want to associate the API keys with so if you just say read it'll never be able to update records if you say write it'll only ever be able to update records and if you say read and write it can do anything in the back end of WordCommerce yeah so it's a little bit separated from WordPress's capabilities yeah the WordPress API and the WordCommerce API are two separate endpoints at the end of the day apart from images they sort of have nothing to do with each other even though the data is post and post meta and all that sort of stuff yeah got it thanks well thank you very much Andrew thanks everyone for coming we could just thank you