Using the WooCommerce REST API – Orders Endpoint February 28 2014
Last week we posted an introduction to the WooCommerce REST API, which detailed basic request/responses and authentication. In this article, we’ll go in-depth with a hands-on look at the Orders endpoint. You’ll learn all the different ways order information can be fetched from the API, as well as how to update the status of an order via the API.
Setup
If you’re using the PHP class, you’ll want to setup your script with this first:
<?php
require_once 'class-wc-api-client.php';
$consumer_key = 'ck_fcedaba8f0fcb0fb4ae4f1211a75da72'; // Add your own Consumer Key here
$consumer_secret = 'cs_9914968ae9adafd3741c818bf6d704c7'; // Add your own Consumer Secret here
$store_url = 'https://www.skyverge.com/'; // Add the home URL to the store you want to connect to here
// Initialize the class
$wc_api = new WC_API_Client( $consumer_key, $consumer_secret, $store_url );
?>
Feel free to use the example script as a starting point for your own.
Otherwise if you’re using cURL (remember cURL only works over SSL), make sure to include your API consumer key and consumer secret in every request (by using the -u consumer_key:consumer_secret argument). We’ll omit them in the examples below for brevity.
Getting Orders
Retrieving a list of orders is easy using the GET /orders endpoint (note the responses are omitted here for brevity, but included for the single order section below):
PHP
$orders = $wc_api->get_orders(); print_r( $orders );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders
You can retrieve orders with a specific status using the ?status parameter, using commas to separate multiple statuses. Custom order statues are supported in addition to the default pending, on-hold, processing, completed, refunded, failed, and cancelled statuses.
PHP
$completed_orders = $wc_api->get_orders( array( 'status' => 'completed' ) ); print_r( $completed_orders );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders?status=processing,completed
10 orders are returned by default, but you can specify more using the filter[limit] parameter:
PHP
$lots_of_orders = $wc_api->get_orders( array( 'filter[limit]' => 50 ) ); print_r( $lots_of_orders );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders?filter[limit]=50
Want to retrieve orders created between specific dates? Use the filter[created_at_min] and filter[created_at_max] parameters. You could also use the updated_at_min and updated_at_max to retrieve orders updated between specific dates.
Note that your dates should be provided in RFC3339 format in the UTC timezone, so YYYY-MM-DDTHH:MM:SSZ. You can omit time/timezone if needed.
PHP
$january_orders = $wc_api->get_orders( array( 'filter[created_at_min]' => '2014-01-01`, 'filter[created_at_max]' => '2014-01-31' ) ); print_r( $january_orders );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders?filter[created_at_min]=2014-01-01&filter[created_at_max]=2014-01-31
Parameters and filters can be used together, so for example you could get processing orders updated in January:
PHP
$january_completed_orders = $wc_api->get_orders( array( 'status' => 'completed', 'filter[created_at_min]' => '2014-01-01`, 'filter[created_at_max]' => '2014-01-31' ) ); print_r( $january_completed_orders );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders?status=completed&filter[created_at_min]=2014-01-01&filter[created_at_max]=2014-01-31
Occasionally you might not need all the information about an order, perhaps you only need the order ID and status. Use the fields parameter to limit which fields are returned in the response. Multiple fields should be comma-separated.
PHP
$order_ids_statuses = $wc_api->get_orders( array( 'fields' => 'id,status' ) ); print_r( $order_ids_statuses );
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders?fields=id,status
Getting an Order Count
If you need a simple count of orders, use the GET /orders/count endpoint. This accepts the same parameters as the GET /orders endpoint so think of it as a shortcut to fetching and counting the orders yourself.
PHP
<br />// request
$order_count = $wc_api->get_orders( array( 'fields' => 'id,status' ) );
print_r( $order_count );
/* response
stdClass Object
(
[count] => 110
)
*/
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders/count
{"count":110}
Getting a Single order
You can retrieve a single order specified by it’s ID:
PHP
<br />// request
$order = $wc_api->get_order( 777 );
print_r( $order_order );
/* response
stdClass Object
(
[order] => stdClass Object
(
[id] => 777
[order_number] => #777
[created_at] => 2013-01-17T18:56:16Z
[updated_at] => 2013-01-17T18:56:16Z
[completed_at] => 2013-01-18T17:00:31Z
[status] => completed
[currency] => USD
[total] => 29.25
[subtotal] => 24.30
[total_line_items_quantity] => 1
[total_tax] => 0.00
[total_shipping] => 4.95
[cart_tax] => 0.00
[shipping_tax] => 0.00
[total_discount] => 0.00
[cart_discount] => 0.00
[order_discount] => 0.00
[shipping_methods] => Flat Rate (UPS Mail Innovations)
[payment_details] => stdClass Object
(
[method_id] => braintree
[method_title] => Credit Card
[paid] => 1
)
[billing_address] => stdClass Object
(
[first_name] => Walter
[last_name] => White
[company] =>
[address_1] => 308 Negra Arroyo Lane
[address_2] =>
[city] => Albuquerque
[state] => NM
[postcode] => 87104
[country] => US
[email] => heisenberg@gmail.com
[phone] => 505-555-1258
)
[shipping_address] => stdClass Object
(
[first_name] => Walter
[last_name] => White
[company] =>
[address_1] => 308 Negra Arroyo Lane
[address_2] =>
[city] => Albuquerque
[state] => NM
[postcode] => 87104
[country] => US
)
[note] =>
[customer_ip] =>
[customer_user_agent] =>
[customer_id] => 0
[view_order_url] => https://www.skyverge.com/your-account/view-order/777
[line_items] => Array
(
[0] => stdClass Object
(
[id] => 13824
[subtotal] => 24.30
[total] => 24.30
[total_tax] => 0.00
[price] => 24.30
[quantity] => 1
[tax_class] =>
[name] => Los Pollos Hermanos Fry Patter
[product_id] => 91
[sku] => LPH-FRYBATTER
)
)
[shipping_lines] => Array
(
)
[tax_lines] => Array
(
)
[fee_lines] => Array
(
)
[coupon_lines] => Array
(
)
[customer] => stdClass Object
(
[id] => 0
[email] => heisenberg@gmail.com
[first_name] => Walter
[last_name] => White
[billing_address] => stdClass Object
(
[first_name] => Walter
[last_name] => White
[company] =>
[address_1] => 308 Negra Arroyo Lane
[address_2] =>
[city] => Albuquerque
[state] => NM
[postcode] => 87104
[country] => US
[email] => heisenberg@gmail.com
[phone] => 505-555-1258
)
[shipping_address] => stdClass Object
(
[first_name] => Walter
[last_name] => White
[company] =>
[address_1] => 308 Negra Arroyo Lane
[address_2] =>
[city] => Albuquerque
[state] => NM
[postcode] => 87104
[country] => US
)
)
)
)
*/
cURL
$ curl https://www.skyverge.com/wc-api/v1/orders/777
{
"order":{
"id":777,
"order_number":"#777",
"created_at":"2013-01-17T18:56:16Z",
"updated_at":"2013-01-17T18:56:16Z",
"completed_at":"2013-01-18T17:00:31Z",
"status":"completed",
"currency":"USD",
"total":"29.25",
"subtotal":"24.30",
"total_line_items_quantity":1,
"total_tax":"0.00",
"total_shipping":"4.95",
"cart_tax":"0.00",
"shipping_tax":"0.00",
"total_discount":"0.00",
"cart_discount":"0.00",
"order_discount":"0.00",
"shipping_methods":"Flat Rate (UPS Mail Innovations)",
"payment_details":{
"method_id":"braintree",
"method_title":"Credit Card",
"paid":true
},
"billing_address":{
"first_name":"Walter",
"last_name":"White",
"company":"",
"address_1":"308 Negra Arroyo Lane",
"address_2":"",
"city":"Albuquerque",
"state":"NM",
"postcode":"87104",
"country":"US",
"email":"heisenberg@gmail.com",
"phone":"505-555-1258"
},
"shipping_address":{
"first_name":"Walter",
"last_name":"White",
"company":"",
"address_1":"308 Negra Arroyo Lane",
"address_2":"",
"city":"Albuquerque",
"state":"NM",
"postcode":"87104",
"country":"US"
},
"note":"",
"customer_ip":"",
"customer_user_agent":"",
"customer_id":"0",
"view_order_url":"https://www.skyverge.com/your-account/view-order/777",
"line_items":[
{
"id":13824,
"subtotal":"24.30",
"total":"24.30",
"total_tax":"0.00",
"price":"24.30",
"quantity":1,
"tax_class":null,
"name":"Los Pollos Hermanos Fry Patter",
"product_id":91,
"sku":"LPH-FRYBATTER"
}
],
"shipping_lines":[
],
"tax_lines":[
],
"fee_lines":[
],
"coupon_lines":[
],
"customer":{
"id":0,
"email":"heisenberg@gmail.com",
"first_name":"Walter",
"last_name":"White",
"billing_address":{
"first_name":"Walter",
"last_name":"White",
"company":"",
"address_1":"308 Negra Arroyo Lane",
"address_2":"",
"city":"Albuquerque",
"state":"NM",
"postcode":"87104",
"country":"US",
"email":"heisenberg@gmail.com",
"phone":"505-555-1258"
},
"shipping_address":{
"first_name":"Walter",
"last_name":"White",
"company":"",
"address_1":"308 Negra Arroyo Lane",
"address_2":"",
"city":"Albuquerque",
"state":"NM",
"postcode":"87104",
"country":"US"
}
}
}
}
You can use the same fields parameter as noted above to restrict the fields returned in the response.
Updating the status of an order
You can update the status of an order using the PUT /orders/#{id} endpoint. All actions that are triggered normally when changing the status of an order in the admin (e.g. sending emails, granting download permissions) are also triggered when changing the order status via the API.
PHP
<br />// request $updated_order = $wc_api->update_order( 777, array( 'status' => 'completed' ) ); print_r( $updated_order ); // the updated order object will be returned
cURL
$ curl -X PUT -H 'Content-Type: application/json'
-d '{"status":"completed"}'
https://www.skyverge.com/wc-api/orders/777
# the updated order JSON will be returned
Getting notes for a Single Order
Order notes are typically added for order status changes and other relevant information about the order. These can be fetched via the API using the GET /orders/#{id}/notes endpoint:
PHP
<br />// request
$order_notes = $wc_api->get_order_notes( 777 );
print_r( $order_notes );
/* response
stdClass Object
(
[order_notes] => Array
(
[0] => stdClass Object
(
[id] => 35389
[created_at] => 2013-01-18T17:00:31Z
[note] => Order status changed from processing to completed.
[customer_note] =>
)
[1] => stdClass Object
(
[id] => 35390
[created_at] => 2013-01-18T17:00:31Z
[note] => Tracking number added: 910290323213081
[customer_note] =>
)
[2] => stdClass Object
(
[id] => 35391
[created_at] => 2013-01-18T17:00:31Z
[note] => Order shipped via UPS Mail Innovations
[customer_note] => 1
)
[3] => stdClass Object
(
[id] => 35296
[created_at] => 2013-01-17T18:56:16Z
[note] => Order status changed from pending to processing.
[customer_note] =>
)
[4] => stdClass Object
(
[id] => 35297
[created_at] => 2013-01-17T18:56:16Z
[note] => Credit Card Transaction Approved: Amex ending in 7777 (07/2017)
[customer_note] =>
)
)
)
*/
cURL
$ curl https://www.skyverge.com/wc-api/orders/777/notes
{
"order_notes":[
{
"id":"35389",
"created_at":"2013-01-18T17:00:31Z",
"note":"Order status changed from processing to completed.",
"customer_note":false
},
{
"id":"35390",
"created_at":"2013-01-18T17:00:31Z",
"note":"Tracking number added: 910290323213081",
"customer_note":false
},
{
"id":"35391",
"created_at":"2013-01-18T17:00:31Z",
"note":"Order shipped via UPS Mail Innovations",
"customer_note":true
},
{
"id":"35296",
"created_at":"2013-01-17T18:56:16Z",
"note":"Order status changed from pending to processing.",
"customer_note":false
},
{
"id":"35297",
"created_at":"2013-01-17T18:56:16Z",
"note":"Credit Card Transaction Approved: Amex ending in 7777 (07/2017)",
"customer_note":false
}
]
}
Putting it all together
Now that we’ve gone through each Order endpoint available in the WooCommerce REST API, let’s put together a quick example of what you can do. Let’s say you wanted to encourage customers that abandon their pending orders to come back and complete their order. We’d need to fetch pending orders and email each customer with a link to visit where they can pay for their order. Here’s some sample code using the PHP library:
<?php
require_once "class-wc-api-client.php";
$consumer_key = 'ck_67c51fb44d4610c71f0e12aee113346d';
$consumer_secret = 'cs_aea7b62348fd3ed8f7d24aca705c941e';
$store_url = 'https://www.skyverge.com/';
$wc_api = new WC_API_Client( $consumer_key, $consumer_secret, $store_url );
// get store info for name, etc
$store_info = $wc_api->get_index();
// get pending orders
$pending_orders = $wc_api->get_orders( array( 'status' => 'pending' ) );
foreach ( $pending_orders->orders as $order ) {
// skip guest orders (e.g. orders with customer ID = 0)
if ( ! $order->customer->id ) {
continue;
}
$subject = "Please complete your order on {$store_info->store->name}";
$message = "Hi {$order->customer->first_name}, it looks like you haven't completed your order yet! Finish your order here: {$order->view_order_url}";
mail( $order->customer->email, $subject, $message );
}
This is a simple example, but it should get you thinking about the sort of cool things you can do with the orders endpoint of the WooCommerce REST API. Have any ideas? Share them in the comments!
The post Using the WooCommerce REST API – Orders Endpoint appeared first on SkyVerge.