What is CoCart?

CoCart, also written as co-cart, is a REST API for WooCommerce. Accessing the cart via the REST API was highly requested by mobile and app developers and was missing from the core of WooCommerce.

So I built it. Tada!

It allows you to use WooCommerce’s REST API to its full potential providing the option to create a full web or mobile app 📱 for your store powered by WooCommerce.

The current WooCommerce REST API is version v2. The same for CoCart. The namespace matches with the current version to keep all endpoints together when viewing the index.

The cart endpoint also registers before WooCommerce endpoints in order for the index of WC REST API to be in alphabetical order.

Requirements

To use the latest version of the CoCart you must be using:

WordPress 4.4 or later.
WooCommerce 3.0.x or later.
Pretty permalinks in Settings > Permalinks so that the custom endpoints are supported. Default permalinks will not work.
You may make requests over either HTTP or HTTPS, but HTTPS is recommended where possible.

Request/Response Format

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Some general information about response:

Resource IDs are returned as integers.
Other amounts, such as item counts, are returned as integers.
Blank fields are generally included as null instead of being returned as blank strings or omitted.

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code	Error Type
`400 Bad Request`	Invalid request, e.g. using an unsupported HTTP method
`401 Unauthorized`	Authentication or permission error, e.g. incorrect API keys
`404 Not Found`	Requests to resources that don't exist or are missing
`500 Internal Server Error`	Server error

{
  "code": "rest_no_route",
  "message": "No route was found matching the URL and request method",
  "data": {
    "status": 404
  }
}

{
  "code": "wc_cart_rest_clear_cart_failed",
  "message": "Clearing the cart failed!",
  "data": {
    "status": 500
  }
}

Errors return both an appropriate HTTP status code and response object which contains a code, message and data attribute.

Parameters

Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. POST /cart/?cart_item_key=270edd69788dce200a3b395a6da6fdb7&quantity=2. All parameters are documented along each endpoint.

Libraries and Tools

Official libraries

Node.js Library
PHP Library
Python Library
Ruby Library

Third party libraries

Angular Library
Java Library
.NET Library
Swift Library

Tools

Some useful tools you can use to access the API include:

Postman - A multi platform REST API GUI client (using Google Chrome or installing the app on Mac OS X or Windows).
Insomnia - Similar to Postman using an app on Mac OS X, Windows or Ubuntu.
CocoaRestClient - A Mac OS X GUI client for interacting with the API.
Paw HTTP Client - Another HTTP client for Mac OS X.
RESTClient, a debugger for RESTful web services - Free Firefox add-on.
Advanced REST client - Free Google Chrome extension.
RequestBin - Allows you test web hooks.
Hookbin - Another tool to test web hooks.

Error Responses

You might encounter errors when using CoCart. These error responses explain what might have happened.

Error Status	Error Response
`wc_cart_rest_clear_cart_failed`	Clearing the cart failed!
`wc_cart_rest_product_id_required`	Product ID number is required!
`wc_cart_rest_product_id_not_numeric`	Product ID must be numeric!
`wc_cart_rest_quantity_not_numeric`	Quantity must be numeric!
`wc_cart_rest_product_does_not_exist`	Warning: This product does not exist!
`wc_cart_rest_product_sold_individually`	You cannot add another "%s" to your cart. %s is the product name
`wc_cart_rest_cannot_be_purchased`	Sorry, this product cannot be purchased.
`wc_cart_rest_product_out_of_stock`	You cannot add "%s" to the cart because the product is out of stock. %s is the product name
`wc_cart_rest_not_enough_in_stock`	You cannot add that amount of "%1$s" to the cart because there is not enough stock (%2$s remaining). %1$s is the product name. %2$s is the stock remaining.
`wc_cart_rest_not_enough_stock_remaining`	You cannot add that amount to the cart — we have %1$s in stock and you already have %2$s in your cart.
`wc_cart_rest_cannot_add_to_cart`	You cannot add "%s" to your cart. %s is the product name
`wc_cart_rest_can_not_remove_item`	Unable to remove item from cart.
`wc_cart_rest_can_not_restore_item`	Unable to restore item to the cart.
`wc_cart_rest_cart_item_key_required`	Cart item key is required!
`wc_cart_rest_can_not_update_item`	Unable to update item quantity in cart.

Cart API

The cart API allows you to add, view, update, and delete individual items for the cart.

View Cart Contents

This API helps you view the contents of the cart.

Attribute	Type	Description
`thumb`	bool	Returns the product thumbnail for the product.

HTTP request

GET

/wp-json/wc/v2/cart

curl -X GET https://example.com/wp-json/wc/v2/cart \
    -H "Content-Type: application/json"

{
  "404dcc91b2aeaa7caa47487d1483e48a":{
    "key":"404dcc91b2aeaa7caa47487d1483e48a",
    "product_id":32,
    "variation_id":0,
    "variation":[],
    "quantity":1,
    "line_tax_data":{
      "subtotal":[],
      "total":[]
    },
    "line_subtotal":18,
    "line_subtotal_tax":0,
    "line_total":18,
    "line_tax":0,
    "data":{}
  }
}

Clear Cart

This API helps you clear the contents of the cart.

HTTP request

POST

/wp-json/wc/v2/cart/clear

curl -X POST https://example.com/wp-json/wc/v2/cart/clear \
    -H "Content-Type: application/json"

"Cart is cleared."

Count Items

This API helps you count the items in the cart.

HTTP request

GET

/wp-json/wc/v2/cart/count-items

curl -X GET https://example.com/wp-json/wc/v2/cart/count-items \
    -H "Content-Type: application/json"

Calculate Cart Totals

This API helps you calculate the cart totals.

HTTP request

POST

/wp-json/wc/v2/cart/calculate

curl -X POST https://example.com/wp-json/wc/v2/cart/calculate \
    -H "Content-Type: application/json"

"Cart totals have been calculated."

Get Cart Totals

This API helps you get the cart totals.

HTTP request

GET

/wp-json/wc/v2/cart/totals

curl -X GET https://example.com/wp-json/wc/v2/cart/totals \
    -H "Content-Type: application/json"

{
  "subtotal":"42.00",
  "subtotal_tax":0,
  "shipping_total":"0.00",
  "shipping_tax":0,
  "shipping_taxes":[],
  "discount_total":0,
  "discount_tax":0,
  "cart_contents_total":"42.00",
  "cart_contents_tax":0,
  "cart_contents_taxes":[],
  "fee_total":"0.00",
  "fee_tax":0,
  "fee_taxes":[],
  "total":"42.00",
  "total_tax":0
}

Add to Cart

This API helps you to add an item to the cart.

Add item properties

Attribute	Type	Description
`product_id`	integer	The product ID is required in order to add a product to the cart. mandatory
`quantity`	integer	Set the quantity of the product you want to add to the cart. Default is 1
`variation_id`	integer	Used to set the variation of the product being added to the cart. optional
`variation`	array	Attribute values
`cart_item_data`	array	Used to apply extra cart item data we want to pass into the item. optional

HTTP request

POST

/wp-json/wc/v2/cart/add

curl -X POST https://example.com/wp-json/wc/v2/cart/add \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 32,
    "quantity": 1
  }'

{
  "404dcc91b2aeaa7caa47487d1483e48a":{
    "key":"404dcc91b2aeaa7caa47487d1483e48a",
    "product_id":32,
    "variation_id":0,
    "variation":[],
    "quantity":1,
    "line_tax_data":{
      "subtotal":[],
      "total":[]
    },
    "line_subtotal":18,
    "line_subtotal_tax":0,
    "line_total":18,
    "line_tax":0,
    "data":{}
  }
}

Remove Item from Cart

This API helps you to remove an item from the cart.

Remove item properties

Attribute	Type	Description
`cart_item_key`	string	The cart item key of the product in the cart. mandatory

HTTP request

DELETE

/wp-json/wc/v2/cart/cart-item

curl -X DELETE https://example.com/wp-json/wc/v2/cart/cart-item \
    -H "Content-Type: application/json" \
  -d '{
    "cart_item_key": 404dcc91b2aeaa7caa47487d1483e48a
  }'

"Item has been removed from cart."

Restore Item to Cart

This API helps you to restore an item to the cart.

Restore item properties

Attribute	Type	Description
`cart_item_key`	string	The cart item key of the product that was in the cart recently. mandatory

HTTP request

GET

/wp-json/wc/v2/cart/cart-item

curl -X GET https://example.com/wp-json/wc/v2/cart/cart-item \
    -H "Content-Type: application/json" \
    -d '{
        "cart_item_key": 404dcc91b2aeaa7caa47487d1483e48a
    }'

"Item has been restored to the cart.""

Update Item in Cart

This API helps you to update an item in the cart.

Update item properties

Attribute	Type	Description
`cart_item_key`	string	The cart item key of the product in the cart you want to update. mandatory
`quantity`	integer	Set the quantity of the product you want to update in the cart. Default is 1

HTTP request

POST

/wp-json/wc/v2/cart/cart-item

curl -X POST https://example.com/wp-json/wc/v2/cart/cart-item \
    -H "Content-Type: application/json" \
    -d '{
        "cart_item_key": "404dcc91b2aeaa7caa47487d1483e48a",
        "quantity": 2
    }'

"The quantity for 'Woo T-Shirt' has increased to '2'."

Changelog

The Documentation is updated only when needed. Below is the changelog for "CoCart" documentation that matches with the version of the plugin release.

Doc Version 0.5

Added attribute table for view cart.
Added missing examples for count items and get cart totals.

Doc Version 0.4 - Plugin Release 1.0.5

Project renamed to CoCart.
Changed support to contribution.
Updated links.
Added Insomnia as another tool you can use to access the API with.
Removed all languages except for cURL showing examples on how to use with official library wrappers due to authentication required whic CoCart does not.

Doc Version 0.3 - Plugin Release 1.0.4

Official libraries are not supported as they require authentication which this API does not.
Removed installation instruction for official libraries.
Replaced logo to prevent confusion with the official REST API documentation.

Doc Version 0.2 - Plugin Release 1.0.1

Updated endpoint for updating, restoring and removing items.

Doc Version 0.1 - Plugin Release 1.0.0

Initial Commit