NAV Navbar
cURL

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:

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:

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

WP REST API error example

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

CoCart error example

{
  "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

Third party libraries

Tools

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

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"

JSON response example

{
  "404dcc91b2aeaa7caa47487d1483e48a":{
    "key":"404dcc91b2aeaa7caa47487d1483e48a",
    "product_id":1722,
    "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"

JSON response example

"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"

JSON response example

1

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"

JSON response example

"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"

JSON response example

{
  "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": 1722,
    "quantity": 1
  }'

JSON response example

{
  "404dcc91b2aeaa7caa47487d1483e48a":{
    "key":"404dcc91b2aeaa7caa47487d1483e48a",
    "product_id":1722,
    "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
  }'

JSON response example

"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 DELETE https://example.com/wp-json/wc/v2/cart/cart-item \
    -H "Content-Type: application/json" \
    -d '{
        "cart_item_key": 404dcc91b2aeaa7caa47487d1483e48a
    }'

JSON response example

"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
    }'

JSON response example

"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

Doc Version 0.4 - Plugin Release 1.0.5

Doc Version 0.3 - Plugin Release 1.0.4

Doc Version 0.2 - Plugin Release 1.0.1

Doc Version 0.1 - Plugin Release 1.0.0

Contribute

If you or your company use CoCart or appreciate the work I’m doing in open source, please consider supporting me directly so I can continue maintaining it and keep evolving the project. It's pretty clear that software actually costs something, and even though it may be offered freely, somebody is paying the cost.

You'll be helping to ensure I can spend the time not just fixing bugs, adding features, releasing new versions, but also keeping the project afloat. Any contribution you make is a big help and is greatly appreciated.

If you want to do a one-time donation, you can donate to my PayPal.

Thank you for your support! 🙌