Upgrading API from v1 to v2

First thing you got to know is that the REST API naming convention has changed.

This helps categories the API and help you understand what request your trying to make a whole lot better. You will also find the majority of the routes return the cart response once complete.

This change allows you to get the cart data updated at all times.

Just a little heads up

Upgrading the API is pretty straight forward. What you will have to do once you have changed over is making sure that the data you get from the cart response is updated in your code.

A lot has changed so look at the comparison of the two API versions below.

Naming Convention and Notes

API v1API v2Notes
wp-json/cocart/v1/get-cartwp-json/cocart/v2/cartKeeping the parent route shorter was better.
wp-json/cocart/v1/add-itemwp-json/cocart/v2/cart/add-itemQuantity must be passed as a string not a number. Value is then validated when request is made. Variable products now only need to pass the product ID via the only ID parameter.
wp-json/cocart/v1/itemwp-json/cocart/v2/cart/item/{item_key}Now we specify the item key as part of the route. We don’t pass it as data.
wp-json/cocart/v1/logoutwp-json/cocart/v2/logoutNothing changed.
wp-json/cocart/v1/get-cart/{cart_key}wp-json/cocart/v2/session/{session_id}This is now under a new parent route and can only be accessed by those with permission.

What API’s are New?

The following API routes are all new. 3 are public and 3 require permission to access.

Post MethodAPI RoutesNotes
GETwp-json/cocart/v2/storeThis returns store information.
POSTwp-json/cocart/v2/cart/add-itemsThis allows you to add grouped products to the cart.
DELETEwp-json/cocart/v2/session/{cart_key}This allows those with permission to delete a cart.
GETwp-json/cocart/v2/cart/itemsThis allows you to view just the items in the cart.
GETwp-json/cocart/v2/session/{cart_key}/itemsThis allows those with permission to view just the items in the cart.
GETwp-json/cocart/v2/sessionsThis allows those with permission to view all carts in session.

The Cart Response

The cart response has improved a lot and does not require the use of “Get Cart Enhanced” add-on but that could change before v3 is ready for production use.

API v1

Without the Get Cart Enhanced add-on, the cart response returns mostly raw data that WooCommerce combines when an item is added to the cart. Besides a few additions at the bottom, the cart response is bare.

    "line_tax_data": {
      "subtotal": {
        "12": 8.4
      "total": {
        "12": 8.4
    "product_name":"Vneck Tshirt",
    "product_title":"Vneck Tshirt",
    "product_price": "£18"

API v2

In the new API the cart response is completely custom and provides a whole lot more than it’s previous version. From the cart key, currency of the store, customer information, coupons, shipping methods and more.

The items now return more information making it easier to get the information you need when developing your headless store.

It also supports developers who build extensions for WooCommerce that would change the cart template page to display more information to do exactly the same for the cart response.

	"cart_hash": "803b3394c768420752b4643179cd094e",
	"cart_key": "1",
	"currency": {
		"currency_code": "GBP",
		"currency_symbol": "£",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "£",
		"currency_suffix": ""
	"customer": {
		"billing_address": {
			"billing_first_name": "John",
			"billing_last_name": "Doe",
			"billing_company": "",
			"billing_country": "FR",
			"billing_address_1": "969 Market",
			"billing_address_2": "",
			"billing_postcode": "94103",
			"billing_city": "San Francisco",
			"billing_state": "CA",
			"billing_email": "john.doe@example.com"
		"shipping_address": {
			"shipping_first_name": "John",
			"shipping_last_name": "Doe",
			"shipping_company": "",
			"shipping_country": "FR",
			"shipping_address_1": "969 Market",
			"shipping_address_2": "",
			"shipping_postcode": "94103",
			"shipping_city": "San Francisco",
			"shipping_state": "CA",
			"shipping_phone": "(555) 555-5555"
	"items": {
		"2cbf9a9dad8524a6d1dbe6ea7a1e9bf3": {
			"item_key": "2cbf9a9dad8524a6d1dbe6ea7a1e9bf3",
			"id": 85,
			"name": "V-Neck T-Shirt - Blue",
			"title": "V-Neck T-Shirt",
			"price": "15.00",
			"quantity": {
				"value": 1,
				"min_purchase": 1,
				"max_purchase": -1
			"tax_data": {
				"subtotal": [],
				"total": []
			"totals": {
				"subtotal": 15,
				"subtotal_tax": 0,
				"total": 15,
				"tax": 0
			"slug": "v-neck-t-shirt",
			"meta": {
				"product_type": "variation",
				"sku": "woo-vneck-tee-blue",
				"dimensions": {
					"length": "",
					"width": "",
					"height": "",
					"unit": "cm"
				"weight": 0,
				"variation": {
					"Color": "Blue",
					"Size": "Small"
			"cart_item_data": [],
			"featured_image": "https://example.com/wp-content/uploads/2021/02/vnech-tee-blue-1-324x324.jpg"
	"item_count": 1,
	"items_weight": 0,
	"coupons": [
			"coupon": "freeshipping",
			"label": "Coupon: freeshipping",
			"saving": "Free shipping coupon",
			"saving_html": "Free shipping coupon"
	"needs_payment": true,
	"needs_shipping": false,
	"shipping": {
		"total_packages": 0,
		"show_package_details": false,
		"has_calculated_shipping": true,
		"packages": []
	"fees": [],
	"taxes": [],
	"totals": {
		"subtotal": "1500",
		"subtotal_tax": "0",
		"fee_total": "0",
		"fee_tax": "0",
		"discount_total": "0",
		"discount_tax": "0",
		"shipping_total": "0",
		"shipping_tax": "0",
		"total": "1500",
		"total_tax": "0"
	"removed_items": [],
	"cross_sells": [],
	"notices": []

If you need any help upgrading, come join the CoCart community in Slack and DM @seb