woocommerce / woocommerce-rest-api-docs

WooCommerce REST API Documentation

WooCommerce REST API Docs

Repository of documentation REST API WooCommerce.

This project is based on Slate.

Usage

To generate docs run:

./build.sh

To deploy generated docs:

./deploy.sh

woocommerce-rest-api-docs's Issues

Product property dimensions has incorrect type

In the documentation type of the Product property "dimensions" is array but actual (in the result json) type is object. Please notice that Variations property also has "dimensions" property and it also has incorrect type (array instead object).

Property documentation:
dimensions array Product dimensions. See Dimensions properties.

Actual result:
"dimensions": {
"length": "",
"width": "",
"height": ""
},

Variation Properties Docs - Don't Mention "visible" Attribute

The Product Variations docs at:

http://woocommerce.github.io/woocommerce-rest-api-docs/#variation-properties

Don't mention the "visible" boolean type attribute that can be set for a variation (true/false). This is required to be set to for the variation to display as 'enabled' in the WordPress Admin screen.

Create product: unable to set featured image with WooCommerce REST API v3

I'm kind of freaking out with this issue.

We have a huge CSV file and the products should be automatically imported with the rest api.

Everything works fine (Thank you very much, that's pretty awesome):

• the product has been created
• all variations, attributes, price etc. are succesfully imported
• the images were uploaded succesfully and they've also been set to the gallery (with title and alt attributes)

but we still have one issue:

• Setting image['position'] = 0 to featured image is not working although the image have also been succesfully uploaded.

All other positions are working perfect, it's only about position = 0. Everything is in his place, but the connection between image and featured image of the product is missing/not working.

Notes (if it helps to find the solution):

• in some cases the position=0 image is uploaded AFTER position = 1 (if it's important)
• functions the handle this feature (class-wc-api-products.php):
  create_product (250) -> save_product_images (2259) -> upload_image_from_url (2348) -> set_uploaded_image_as_attachment (2437) -> set_post_thumbnail (called in line 2279)

`
<?php

$url = "http://myshop.com/";
$ck = "consumer_key";
$cs = "consumer_secret";

require_once( 'lib/woocommerce-api.php' );

$options = array(
    'debug'           => true,
    'timeout'         => 30,
    'ssl_verify'      => false,
);

try {

    $client = new WC_API_Client( $url, $ck, $cs, $options );
    $data = array(
        //'product' => array(
            'title' => 'Notebook',
            'type' => 'simple',
            'regular_price' => '21.99',
            'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
            'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
            'categories' => array("Notebook"),
            'images' => array(
                array(
                    'src' => 'https://www.it-guenstiger.net/uploads/ipad_1.png',
                    'position' => 0,
                    'title' => 'Notebook',
                    'alt' => 'Notebook'
                ),
                array(
                    'src' => 'https://www.it-guenstiger.net/uploads/home-pc-system.png',
                    'position' => 1,
                    'title' => 'Notebook',
                    'alt' => 'Notebook'
                )
            )
         //)
    );

    print_r($client->products->create($data));

} catch ( WC_API_Client_Exception $e ) {

    echo $e->getMessage() . PHP_EOL;
    echo $e->getCode() . PHP_EOL;

    if ( $e instanceof WC_API_Client_HTTP_Exception ) {

        print_r( $e->get_request() );
        print_r( $e->get_response() );
    }
}

?>

`

I'm testing the code with kloon's rest api client: https://github.com/kloon/WooCommerce-REST-API-Client-Library (changed kloon's version to v3)

WordPress v4.4.2
WooCommerce v2.5.2
nginx v1.8

Docs for 2.4

List of pending docs to for API 3.0 and WC 2.4:

• woocommerce/woocommerce#8406
• woocommerce/woocommerce#8415
• woocommerce/woocommerce#8019
• woocommerce/woocommerce#7922
• woocommerce/woocommerce#8053
• woocommerce/woocommerce#7592
• woocommerce/woocommerce#7915
• woocommerce/woocommerce#8298
• woocommerce/woocommerce#8342

wp-api/v1: _links

Product properties: '_links' not part of documentation. Should be?

Bad param in NodeJS example wp_api should be wpAPI

The exemple given at this URL : http://woothemes.github.io/woocommerce-rest-api-docs/?javascript#libraries-and-tools mentions a parameter wp_api.
However, when you use it as such, even the Index request fails with error 400:

WooCommerce.get('', function(err, data, res) {
  console.log(data);
});

When we look in data at the path it tries to access we see it tries to talk to /wc-api/wc/v1.
However the documentation for index (http://woothemes.github.io/woocommerce-rest-api-docs/?javascript#index) mentions /wp-json/wc/v1

When we look in the code https://github.com/woothemes/wc-api-node/blob/master/index.js#L99
we see that this wp-json vs. wc-api switch is conditioned by this.wpAPI and we follow it to the init https://github.com/woothemes/wc-api-node/blob/master/index.js#L44
we see that is looks at the wpAPI parameters in the options and NOT wp_api.

Indeed, when we change to the proper wpAPI, then the index call above now works.

http://woothemes.github.io/woocommerce-rest-api-docs/?javascript#libraries-and-tools should instead give the following proper exemple:

// Install:
// npm install --save woocommerce-api

// Setup:
var WooCommerceAPI = require('woocommerce-api');

var WooCommerce = new WooCommerceAPI({
  url: 'http://example.com', // Your store URL
  consumerKey: 'consumer_key', // Your consumer key
  consumerSecret: 'consumer_secret', // Your consumer secret
  wpAPI: true, // Enable the WP REST API integration
  version: 'wc/v1' // WooCommerce WP REST API version
});

Woocommerce REST API v2 Brake changes

we are doing a migration of an ionic app using Woocommerce REST API v1 (WC v2.6) to Woocommerce REST API v2 (WC v3), so we are are looking for a list of breaking changes and we didn't find anything list those BC !! so please can someone share with us.

wp-api/v1: Image name or title?

Product image properties: 'name' used in documentation, 'title' in examples. I get 'title' from my api

Index - Meta properties - 'thousand_separator' description is incorrect

On the API Index page there is the Meta Properties section which contains the table with attributes' descriptions.

Description for the thousand_separator attribute says:

The unit set for product weights. Valid units are kg, g, lbs, oz

Instead, it should say something like:

Thousands separator, e.g .

Variable Product - Attributes Properties: options will not accept Cyrillic letters

If you add Cyrillic attributes options from Wordpress - there is no problem:

GET :

"attributes": [
{
"name": "Размер",
"slug": "size",
"position": 0,
"visible": true,
"variation": true,
"options": [
"36",
"37",
"38",
"39",
"40"
]
},
{
"name": "Цвят",
"slug": "colors",
"position": 1,
"visible": true,
"variation": false,
"options": [
"Бежов", <--------------------------------- Great
"Жълт" <--------------------------------- Great
]
},
{
"name": "Тип",
"slug": "product-type",
"position": 3,
"visible": true,
"variation": false,
"options": [
"Боти", <--------------------------------- Great
"Ботуши", <--------------------------------- Great
"Ниски" <--------------------------------- Great
]
}
],

Screenshot:
http://s23.postimg.org/51705tgij/Screenshot_from_2015_10_23_16_45_03.png

But after an update trough the API v3 with the following array: ['тест','тестинг', "test", "danish æøåø"]

I get :
http://s3.postimg.org/if59pbaf7/Screenshot_from_2015_10_23_17_08_51.png

I tried with Postman, I tried unicode,string,ascii ......... Please investigate.

Thank you !

Wrong route to reports top sellers

The route to reports top sellers is describes as being reports/sales/top_sellers whereas it looks to me as it should be reports/top_sellers, right ?

Coupons in Rest API

Hi,

I am using coupons rest api to get the discount in the create order.

Here is what i am passing to create order service
"coupon_lines": [{
"id":4334,
"code":"cstore",
"discount":5
}],

After applying the code i am not getting the discount in order section in admin. Please suggest me what is wrong.

Thanks

UPDATE PRODUCT Method sets price and regular_price to 0.00 ( API v2 + API v3)

GET
{
"product": {
"title": "Дамски боти в черно с връзки и заден цип",
"id": 47655,
"price": "199.00", - THE PRICE IS CORRECT
"regular_price": "199.00", - THE PRICE IS CORRECT
etc .....
etc ...........
}
}

"PUT" :
https://website.com/wc-api/v3/products/47655/?consumer_key=ck&consumer_secret=cs

DATA:

{
"product": {
"regular_price" : "106.00"
}
}

RESPONSE:
{
"product": {
"title": "Дамски боти в черно с връзки и заден цип",
"id": 47655,
"price": "0.00", ???????????? why is it 0 ?
"regular_price": "0.00", ?????????????? why is it 0 ?
etc .....
etc ...........
}
}

I also get frequent GATEWAY TIMEOUT error ........

Please advice or investigate as soon as possible.

Thanks for your efforts.

Best,
Yordan

Login Customer

Hi I'm totally new in woocommerce, I'm trying to do an iOS app using this api. I think all fits except for the login for a customer.

What endpoint should I use if a customer would like to login with his user(or email) and password in the server to get all his details.

Thanks.

is there any API for add To cart

I couldn't find any API for Add to cart in Latest API version v1 & any API Version.

Wrong customer batch PHP example in REST API v1.

Catalog Visibility is set to visible by default

When I create a product the catalog visibility is set to visible, not hidden (but docs say that it is hidden by default - I think it's better to be visible by default anyway).

http://woothemes.github.io/woocommerce-rest-api-docs/?shell#products-properties

@claudiosmweb

Category ID's or names?

In the docs about product properties it says List of product categories names (string). In write-mode need to pass a array of categories IDs (integer) (uses wp_set_object_terms()) But in the examples on how to create a simple product there are lists of names.

Edit: I just tried with ID's and it started creating new categories with the names and slugs of the numbers. So I guess the correct way is to use the category titles. If that is the case then the docs doesn't explain how to assign a product to a sub category like Books/History

Oauth Spec Note

In the Oauth Tips section, the docs say:

Some OAuth libraries add an ampersand to the provided secret key before generating the signature. This does not adhere to the OAuth spec and the ampersand should be removed prior to generating the signature.

I think this is incorrect, though, given the spec at http://oauth.net/core/1.0a/#anchor15:

The HMAC-SHA1 signature method uses the HMAC-SHA1 signature algorithm as defined in RFC2104 where the Signature Base String is the text and the key is the concatenated values (each first encoded per Parameter Encoding) of the Consumer Secret and Token Secret, separated by an '&' character (ASCII code 38) even if empty.

Since Token Secret isn't used by WooCommerce I believe that the standard indicates that the & should be there anyway. So shouldn't the docs indicate that this is against spec? The Guzzle library I was using uses an & in the middle even if empty and had to be patched to make it work against the WooCommerce API.

Variation properties - duplicate property

The property "purchasable - boolean - Shows if the variation can be bought" has been written twice in the properties list for Products => Variation properties.

Webhook request header properties documentation

In the documentation, the webhooks are spelled like this X-WC-Webhook-ID and what we actually receive is X-Wc-Webhook-Id camel case version.

Also, there seems to be a missing one, X-Wc-Webhook-Source.

Document order refunds property

https://github.com/woothemes/woocommerce/blob/master/includes/api/class-wc-rest-orders-controller.php#L163

Authentication endpoint docs

Java Library

Hi, I've created Java library for working with WooCommerce REST API, so probably we can add it to the REST API documentation. Please let me to know what do you think about it.
Library repo: https://github.com/icoderman/wc-api-java

Variations Properties -> 'images' should be 'image'

According to the class-wc-api-products.php file, the Variations section has an Attribute that is 'image' for the (single) image for the variation.

However, the documentation labels this attribute "images". Spent a while tracking down why my image wasn't uploading for the Variation!

Create refund line_item data

The data required to create a refund with line_items is not documented correctly. It suggests that the data should be line item properties, eg:

{
  "order_refund": {
  ...
  "line_items": [{"id":1, "total": "10", ...}]
  }
}

but the data that the API expects is:

{
  "order_refund": {
  ...
  "line_items": {1: {"refund_total": "10", "refund_tax": "0", "qty": 1}]
  }
}

(http://woothemes.github.io/woocommerce-rest-api-docs/#create-a-refund-for-an-order)

failed with status 400

I am using the exact example provided here:

http://woothemes.github.io/woocommerce-rest-api-docs/?shell#create-an-order

Which failes horribly:

Error: call to URL https://foo.com/wc-api/v3/orders?consumer_key=ck_bc4fd38b21ae4f5c44da3cb8a64ed5a0951e0902&consumer_secret=cs_d6cfb1faf914534955ba1b5e6063577e90610bc3 failed with status 400, response {"errors":[{"code":"woocommerce_api_missing_order_data","message":"Ingen order data angivet for at oprette order"}]}, curl_error , curl_errno 0

The PHP code used is this:

$url = 'https://foo.com/wc-api/v3/orders?consumer_key=ck_bc4fd38b21ae4f5c44da3cb8a64ed5a0951e0902&consumer_secret=cs_d6cfb1faf914534955ba1b5e6063577e90610bc3';

$json_string =
'{
"order": {
"payment_details": {
"method_id": "bacs",
"method_title": "Direct Bank Transfer",
"paid": true
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address_1": "969 Market",
"address_2": "",
"city": "San Francisco",
"state": "CA",
"postcode": "94103",
"country": "US",
"email": "[email protected]",
"phone": "[phone]"
},
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"address_1": "969 Market",
"address_2": "",
"city": "San Francisco",
"state": "CA",
"postcode": "94103",
"country": "US"
},
"customer_id": 2,
"line_items": [
{
"product_id": 1389,
"quantity": 1
}
],
"shipping_lines": [
{
"method_id": "flat_rate",
"method_title": "Flat Rate",
"total": 10
}
]
}
}';

$content = json_encode($json_string);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json"));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);

$json_response = curl_exec($curl);

$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ( $status != 201 ) {
die("Error: call to URL $url failed with status $status, response $json_response, curl_error " . curl_error($curl) . ", curl_errno " . curl_errno($curl));
}

curl_close($curl);

$response = json_decode($json_response, true);

It is so poorly documented how to do this that it is extremely annoying!

Customers endpoint seems broken

So when searching for a customer by e-mail I noticed the WooCommerce docs seem broken

/wp-json/wc/v1/customers returns a wordpress 404

/wc-api/v3/customers works, however appending [email protected] or ?filter[email][email protected] returns all customers, which seems undesirable and contrary to the documentation https://woothemes.github.io/woocommerce-rest-api-docs/?shell#list-all-customers

WooCommerce 2.6.2, WordPress 4.5.3

Small typo on the API doc

In the "Order Properties" section, "shipping" and "billing"'s type is set to "array" but it should be "object"

Attributes Properties: options - description improvement

I'd like to propose improvement for Attributes Properties section. When updating product, options attribute can be either string or array: https://github.com/woothemes/woocommerce/blob/master/includes/api/class-wc-api-products.php#L1283

Attributes:

• passed in array should be slugs (otherwise eg. 11.11.2015 becomes 11-11-2015),
• passed as string should be separated with |.

Thanks!

Change prices float to string in v3

meta_data documentation missing for orders

The (very useful) meta_data attribute documentation is missing for create order and update order in the _orders.md file. (WooCommerce 2.6.4, wp-json/wc/v1).

(Also, being able to retrieve this would be nice).

error 400 bad request

how to fix this error?
this error only show on customer
http://mydomain.org/index.php/wc-api/v3/customers/email/[email protected]…=1475246337&oauth_signature=LqRrSfz0hG3icL2BTuYRpLYZUjfDKTv6bGIawc1xJpU%3D

Docs for 2.5

• Support for product shipping classes
• Support to POST, PUT, and DELETE categories
• product/tags endpoints
• Product attribute terms endpoints
• Filter products by tag, category, shipping classes or attributes
• Producs image properties alt and title writable
• Tax endpoint
• expand filter for orders
• Product menu_order

Refund property on Order Object

Header should be "Refund line properties", not "Coupon line properties".

Refund Attribute "reason" is returned as "refund".

Variation properties dimensions has incorrect type

Actually I mentioned about this issue in the issue #58 but looks like It was missed :)
In the documentation type of the Variations property "dimensions" is array but actual (in the result json) type is object.

Filter Products

Hi, how about I have a doubt to filter a serious product, when filter for example by name all very well

` this.wooService.getProducts({ 'filter[name]' : 'Book Discount', }).then((products: Array) => {

  console.log(products);
  this.products = products;
  

  this.loadingModal.dismiss();
}, (reson) => {
  this.loadingModal.dismiss();
  this.errorModal.present();
});

`

But for some strange reason when I write 'filter [on_sale]': 'true' does not search for products with that status

That I have to do to configure the search well, since when I look for po on_sale does not bring anything or there is another way to perform the searches

A greetings and thanks for your time

Documentation for product properties incomplete

In the file class-wc-api-products.php there's this code at line 330

// Product name (slug).
if ( isset( $data['name'] ) ) {
    wp_update_post( array( 'ID' => $id, 'post_name' => sanitize_title( $data['name'] ) ) );
}

It's nowhere in the official documentation that 'name' is a property for a product and that it can be used to set the post_name, that's responsible for the product's url.

IMHO it's definitely worth mentioning in the docs, since modifying the post_name is an urgent feature, and I accidentally found it in the code.

btw. maybe it should also be implemented in the product create function

Auto generating API keys using our Application Authentication Endpoint

I created my wordpress with woo commerce web site. (wordpress 4.7.3, woocommerce 3.0.1)

I'm trying to test the wc-auth endpoint to generate api keys but the endpoint is not even there. In the Wiki it says v1 and on the website v2 and there's a bunch of 404 pages in the Wiki.

Could someone tell how can I enable the endpoint /wc-auth/v2/authorize please?

Include "description" item to product attribute terms in v1

See #13721

Get alternate image sizes from product?

Is it possible to get other image sizes than just the original from the REST API?
As i can figure out, the only way would be to get media ID and make another request using the WP API to wp-json/wp/v2/media/ endpoint.
But that seems like an awful lot of get requests, if you're looping through products from woo rest api, and just want to present a smaller image than the uploaded to the user.

So to sum it up - am i missing some obvious way to solve this?

Best regards

wp-api/v1: grouped_products_ids -> grouped_products

Product properties: The grouped_products_ids no longer exists. Is replaced by grouped_products array.

Product property grouped_products has incorrect type

In the documentation type of the Product property "grouped_products" is string but actual (in the result json) type is array (probably array of integers).

Property documentation:
grouped_products string List of grouped products ID, only for group type products.

Actual result:
... "grouped_products": [], ...

Creating categories and tags using the woocommerce REST api issue(V3)

Looks like the new V3 does not allow creating of product categories and tags when creating a product using the api:

print_r( $client->products->create( array( 'title' => 'product_name','sku' => 'sku_value', 'type' => 'simple', 'regular_price' => '1000', 'short_description'=>'short description', 'categories' => Array ('category1','category2','category3' ), 'tags'=> array('product_tag'))));

all the other properties are still created but not categories and tags. returns an empty array:

["categories"]=>
array(0) {
}
["tags"]=>
array(0) {
}

so question is: how are categories and tags created using the REST api V3?

Webhook creation requires 'secret' field

Using WooCommerce 2.6.8, Wordpress 4.6.1 on Apache

Calling /wp-json/wc/v1/webhooks with basic-authentication with this payload:

{
  "name": "Any name is valid",
  "topic": "product.created",
  "delivery_url": "http://requestb.in/tizasutj"
}

Returns a 400 response asking for a secret param.
It's stated in the documentation that's optional, and will use the default user's consumer secret

Sort products by price

Hi,

I am using woocommerce rest api for android app. I need to sort products by the price. How can I do that?

I have tried filter but it's not working.

Create Product

I want to create a product with oauth anf javascript (my website protocol is http).
I must use WooCommerce.post('products', data, function(err, data, res)...
but what is the library of "WooCommerce.post" to know this function?

Attributes properties - position duplicate

In Attributes properties attribute position is duplicated

Oauth Tips Clarification

I would recommend a bit of text like this added to the Oauth Tips section:

If including filter fields in your request, it saves a lot of trouble if you can order your filter fields alphabetically before submitting. Many Oauth libraries won't order subquery fields properly, resulting in invalid signatures.

This took me a long time to figure out.

Product fee in Rest API

Hi,

Great plugin for product fees in woocommerce. How can we connect the Rest API in node?

I added product fee for 2 products. I want to know how we can pass keys in the node api for create order api

http://woocommerce.github.io/woocommerce-rest-api-docs/#create-an-order

Thanks
Basanth