NAV Navbar
cURL jQuery PHP WP API

Introduction

CoCart allows the cart to be created, read, updated, and deleted using requests in JSON format and using WordPress REST API Authentication methods and standard HTTP verbs which are understood by most HTTP clients.

The current WP REST API integration version is v1 which takes a first-order position in endpoints.

The following table shows API versions present in each major version of CoCart:

API Version CoCart Version WC Version WP Version
v1 2.0.x or later 3.6.x or later 4.4 or later

Prior to WooCommerce v3.6, CoCart shared WooCommerce's REST API. You can find the documentation about cart support for /wc-api-v2 API separately.

API Version WC Version WP Version Documentation
wc-api-v2 3.0.x or later 4.4 or later wc-api-v2 docs

CoCart Pro

API Version CoCart Pro Version WC Version WP Version Documentation
v1 1.0.x or later 3.6.x or later 4.4 or later cocart pro docs

Work in Progress

This section provides documentation on future features that are in the works. Only view this section if you are testing beta releases and not using it on production sites.

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": "cocart_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 /cocart/v1/item?cart_item_key=270edd69788dce200a3b395a6da6fdb7&quantity=2. All parameters are documented along each endpoint.

Tools

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

Error Responses

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

Error Status Error Response
cocart_cannot_read_cart Cannot read cart!
cocart_customer_missing Customer ID is required!
cocart_clear_cart_failed Clearing the cart failed!
cocart_product_id_required Product ID number is required!
cocart_product_id_not_numeric Product ID must be numeric!
cocart_quantity_not_numeric Quantity must be numeric!
cocart_product_does_not_exist Warning: This product does not exist!
cocart_product_sold_individually You cannot add another "%s" to your cart. %s is the product name
cocart_cannot_be_purchased Sorry, this product cannot be purchased.
cocart_product_out_of_stock You cannot add "%s" to the cart because the product is out of stock. %s is the product name
cocart_not_enough_in_stock You cannot add a quantity of %1$s for "%2$s" to the cart because there is not enough stock. - only %3$s remaining! %1$s is the quantity requested, %2$s is the product name. %3$s is the stock remaining.
cocart_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.
cocart_cannot_add_to_cart You cannot add "%s" to your cart. %s is the product name
cocart_can_not_remove_item Unable to remove item from cart.
cocart_can_not_restore_item Unable to restore item to the cart.
cocart_can_not_update_item Unable to update item quantity in cart.
cocart_cart_item_key_required Cart item key is required!
cocart_no_items No items in cart.
cocart_item_not_in_cart Item specified does not exist in cart.

Index

By default, the API provides information about all available endpoints on the site. Authentication is not required to access the API index.

HTTP request

GET
/wp-json/cocart/v1
curl -X GET https://example.com/wp-json/cocart/v1 \
  -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1' );
$body = wp_remote_retrieve_body( $response );

JSON response example:

{
    "namespace": "cocart/v1",
    "routes": {
        "/cocart/v1": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "namespace": {
                            "required": false,
                            "default": "cocart/v1"
                        },
                        "context": {
                            "required": false,
                            "default": "view"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1"
            }
        },
        "/cocart/v1/add-item": {
            "namespace": "cocart/v1",
            "methods": [
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "product_id": {
                            "required": false,
                            "description": "Unique identifier for the product ID.",
                            "type": "integer"
                        },
                        "quantity": {
                            "required": false,
                            "default": 1,
                            "description": "The quantity amount of the item to add to cart.",
                            "type": "integer"
                        },
                        "variation_id": {
                            "required": false,
                            "description": "Unique identifier for the variation ID.",
                            "type": "integer"
                        },
                        "variation": {
                            "required": false
                        },
                        "cart_item_data": {
                            "required": false
                        },
                        "refresh_totals": {
                            "required": false,
                            "default": false,
                            "description": "Re-calculates the totals once item has been added or the quantity of the item has increased.",
                            "type": "boolean"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/add-item"
            }
        },
        "/cocart/v1/calculate": {
            "namespace": "cocart/v1",
            "methods": [
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "return": {
                            "required": false,
                            "default": false,
                            "description": "Returns the cart totals once calculated.",
                            "type": "bool"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/calculate"
            }
        },
        "/cocart/v1/clear": {
            "namespace": "cocart/v1",
            "methods": [
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "POST"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/clear"
            }
        },
        "/cocart/v1/count-items": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "return": {
                            "required": false,
                            "default": "numeric"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/count-items"
            }
        },
        "/cocart/v1/get-cart": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "thumb": {
                            "required": false,
                            "default": false,
                            "description": "Returns the URL of the product image thumbnail.",
                            "type": "boolean"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/get-cart"
            }
        },
        "/cocart/v1/get-cart/(?P<id>[\\d]+)": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "id": {
                            "required": true,
                            "description": "Unique identifier for the customer.",
                            "type": "integer"
                        },
                        "thumb": {
                            "required": false,
                            "default": false,
                            "description": "Returns the URL of the product image thumbnail.",
                            "type": "boolean"
                        }
                    }
                }
            ]
        },
        "/cocart/v1/item": {
            "namespace": "cocart/v1",
            "methods": [
                "GET",
                "POST",
                "DELETE"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "cart_item_key": {
                            "required": false,
                            "description": "Unique identifier for the item in the cart.",
                            "type": "string"
                        },
                        "refresh_totals": {
                            "required": false,
                            "default": false,
                            "description": "Re-calculates the totals once item has been updated.",
                            "type": "boolean"
                        },
                        "return_cart": {
                            "required": false,
                            "default": false,
                            "description": "Returns the whole cart to reduce requests.",
                            "type": "boolean"
                        }
                    }
                },
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "cart_item_key": {
                            "required": false,
                            "description": "Unique identifier for the item in the cart.",
                            "type": "string"
                        },
                        "refresh_totals": {
                            "required": false,
                            "default": false,
                            "description": "Re-calculates the totals once item has been updated.",
                            "type": "boolean"
                        },
                        "return_cart": {
                            "required": false,
                            "default": false,
                            "description": "Returns the whole cart to reduce requests.",
                            "type": "boolean"
                        },
                        "quantity": {
                            "required": false,
                            "default": 1,
                            "type": "integer"
                        }
                    }
                },
                {
                    "methods": [
                        "DELETE"
                    ],
                    "args": {
                        "cart_item_key": {
                            "required": false,
                            "description": "Unique identifier for the item in the cart.",
                            "type": "string"
                        },
                        "refresh_totals": {
                            "required": false,
                            "default": false,
                            "description": "Re-calculates the totals once item has been updated.",
                            "type": "boolean"
                        },
                        "return_cart": {
                            "required": false,
                            "default": false,
                            "description": "Returns the whole cart to reduce requests.",
                            "type": "boolean"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/item"
            }
        },
        "/cocart/v1/totals": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "html": {
                            "required": false,
                            "default": false
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals"
            }
        },
        "/cocart/v1/calculate/fees": {
            "namespace": "cocart/v1",
            "methods": [
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "set_session": {
                            "required": false,
                            "default": false,
                            "description": "Sets the cart fees in session once calculated.",
                            "type": "bool"
                        },
                        "return": {
                            "required": false,
                            "default": false,
                            "description": "Returns the cart fees once calculated.",
                            "type": "bool"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/calculate/fees"
            }
        },
        "/cocart/v1/calculate/shipping": {
            "namespace": "cocart/v1",
            "methods": [
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "country": {
                            "required": true,
                            "description": "Country is a required minimum to calculate shipping.",
                            "type": "string"
                        },
                        "state": {
                            "required": false,
                            "description": "State is optional but maybe required under some circumstances.",
                            "type": "string"
                        },
                        "city": {
                            "required": false,
                            "description": "Enter City to specify location in country.",
                            "type": "string"
                        },
                        "postcode": {
                            "required": false,
                            "description": "Enter postcode / ZIP to narrow down location for more accurate shipping cost.",
                            "type": "string"
                        },
                        "return_methods": {
                            "required": false,
                            "default": false,
                            "description": "If set to true it will return shipping methods available once shipping is calculated.",
                            "type": "bool"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/calculate/shipping"
            }
        },
        "/cocart/v1/customer": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/customer"
            }
        },
        "/cocart/v1/coupon": {
            "namespace": "cocart/v1",
            "methods": [
                "GET",
                "POST",
                "DELETE"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                },
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "coupon": {
                            "required": true,
                            "description": "Coupon to apply to the cart.",
                            "type": "string"
                        }
                    }
                },
                {
                    "methods": [
                        "DELETE"
                    ],
                    "args": {
                        "coupon": {
                            "required": true,
                            "description": "Coupon to remove from the cart.",
                            "type": "string"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/coupon"
            }
        },
        "/cocart/v1/check-coupons": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/check-coupons"
            }
        },
        "/cocart/v1/cross-sells": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "thumb": {
                            "required": false,
                            "default": false,
                            "description": "Returns the URL of the product image thumbnail.",
                            "type": "boolean"
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/cross-sells"
            }
        },
        "/cocart/v1/fees": {
            "namespace": "cocart/v1",
            "methods": [
                "GET",
                "POST",
                "DELETE"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                },
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "name": {
                            "required": true,
                            "description": "Name of the fee.",
                            "type": "string"
                        },
                        "amount": {
                            "required": true,
                            "description": "Amount for the fee.",
                            "type": "string"
                        },
                        "taxable": {
                            "required": false,
                            "default": false,
                            "description": "Determins if the fee is taxable.",
                            "type": "bool"
                        },
                        "tax_class": {
                            "required": false,
                            "description": "The tax class the fee applies to.",
                            "type": "string"
                        }
                    }
                },
                {
                    "methods": [
                        "DELETE"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/fees"
            }
        },
        "/cocart/v1/payment-methods": {
            "namespace": "cocart/v1",
            "methods": [
                "GET",
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                },
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "gateway_id": {
                            "required": true
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/payment-methods"
            }
        },
        "/cocart/v1/quantities": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/quantities"
            }
        },
        "/cocart/v1/removed-items": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/removed-items"
            }
        },
        "/cocart/v1/shipping-methods": {
            "namespace": "cocart/v1",
            "methods": [
                "GET",
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "recurring_cart_key": {
                            "required": false,
                            "description": "Recurring cart key is required only to get shipping methods for that subscription.",
                            "type": "string"
                        }
                    }
                },
                {
                    "methods": [
                        "POST"
                    ],
                    "args": {
                        "method_id": {
                            "required": true
                        },
                        "instance_id": {
                            "required": true
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/shipping-methods"
            }
        },
        "/cocart/v1/totals/discount": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/discount"
            }
        },
        "/cocart/v1/totals/discount/coupon-totals": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/discount/coupon-totals"
            }
        },
        "/cocart/v1/totals/discount/coupon-tax": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/discount/coupon-tax"
            }
        },
        "/cocart/v1/totals/fee": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/fee"
            }
        },
        "/cocart/v1/totals/fee/tax": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/fee/tax"
            }
        },
        "/cocart/v1/totals/shipping": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "calculate": {
                            "required": false,
                            "default": false
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/shipping"
            }
        },
        "/cocart/v1/totals/shipping/tax": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "calculate": {
                            "required": false,
                            "default": false
                        }
                    }
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/shipping/tax"
            }
        },
        "/cocart/v1/totals/subtotal": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/subtotal"
            }
        },
        "/cocart/v1/totals/subtotal/tax": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/subtotal/tax"
            }
        },
        "/cocart/v1/totals/tax": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/tax"
            }
        },
        "/cocart/v1/totals/total": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/totals/total"
            }
        },
        "/cocart/v1/weight": {
            "namespace": "cocart/v1",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": []
                }
            ],
            "_links": {
                "self": "https://example.com/wp-json/cocart/v1/weight"
            }
        }
    },
    "_links": {
        "up": [
            {
                "href": "https://example.com/wp-json/"
            }
        ]
    }
}

Authentication

CoCart can be authenticated by various methods with the WP REST API, first being via the REST API keys in WooCommerce. Though this method is designed for the backend, with some custom coding you can make it work for the frontend.

Checkout my guide on how to authenticate with WooCommerce.

It is also possible to authenticate using any of the following WP REST API authentication plugins or methods.

Cart

The cart API is powerful and allows you to view the cart in session, add new items, update the quantity of an item and delete individual items from the cart.

Using the individual endpoints and their properties, you can control what you need and what is returned when the request is finished.

Retrieve Cart Contents

This API returns the contents of the cart from a logged in customer or guest customer.

Properties

Attribute Type Description
id integer Unique identifier for the customer. read-only
thumb bool Set as true to return the product thumbnail for each item.

HTTP request

GET
/wp-json/cocart/v1/get-cart
curl -X GET https://example.com/wp-json/cocart/v1/get-cart \
  -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/get-cart",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/get-cart",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/get-cart' );
$body = wp_remote_retrieve_body( $response );

JSON response example

{
  "19ca14e7ea6328a42e0eb13d585e4c22":{
    "key":"19ca14e7ea6328a42e0eb13d585e4c22",
    "product_id":36,
    "variation_id":0,
    "variation":[],
    "quantity":1,
    "data_hash":"b5c1d5ca8bae6d4896cf1807cdf763f0",
    "line_tax_data": {
      "subtotal": {
        "12": 8.4
      },
      "total": {
        "12": 8.4
      }
    },
    "line_subtotal":18,
    "line_subtotal_tax":8.4,
    "line_total":14.4,
    "line_tax":8.4,
    "data":{},
    "product_name":"Vneck Tshirt",
    "product_title":"Vneck Tshirt",
    "product_price": "£18"
  }
}

Here is what to do to include the product thumbnail.

curl -X GET https://example.com/wp-json/cocart/v1/get-cart \
  -H "Content-Type: application/json" \
  -d '{
    "thumb": true
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/get-cart",
  "method": "GET",
  "data": {
    "thumb" : true
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'thumb' => true
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/get-cart",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'thumb' => true
);
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/get-cart', $args );
$body = wp_remote_retrieve_body( $response );

JSON response example

{
  "19ca14e7ea6328a42e0eb13d585e4c22":{
    "key":"19ca14e7ea6328a42e0eb13d585e4c22",
    "product_id":36,
    "variation_id":0,
    "variation":[],
    "quantity":1,
    "data_hash":"b5c1d5ca8bae6d4896cf1807cdf763f0",
    "line_tax_data": {
      "subtotal": {
        "12": 8.4
      },
      "total": {
        "12": 8.4
      }
    },
    "line_subtotal":18,
    "line_subtotal_tax":8.4,
    "line_total":14.4,
    "line_tax":8.4,
    "data":{},
    "product_name":"Vneck Tshirt",
    "product_title":"Vneck Tshirt",
    "product_price": "£18",
    "product_image":"https://example.com/wp-content/uploads/2019/06/vneck-tee.jpg"
  }
}

Retrieve a Customers Cart Contents

This API returns the cart contents for a specific registered customer. To use this you must authenticate. You can also use the Get Cart Content properties.

HTTP request

GET
/wp-json/cocart/v1/get-cart/<id>
curl -X GET https://example.com/wp-json/cocart/v1/get-cart/123 \
  -u consumer_key:consumer_secret \
  -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/get-cart/123",
  "method": "GET",
  "headers": {
    'Authorization', 'Basic ' + btoa( consumer_key + ':' + consumer_secret ) )
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'thumb' => true
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/get-cart/123",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    'Authorization: Basic ' . base64_encode($consumer_key . ':' . $consumer_secret)
  ],
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'headers' => array(
    'Authorization' => 'Basic ' . base64_encode( consumer_key . ':' . consumer_secret )
  )
);
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/get-cart/123', $args );
$body = wp_remote_retrieve_body( $response );

The JSON response returns the same as the examples above.

Clear Cart

This API helps you clear the contents of the cart.

HTTP request

POST
/wp-json/cocart/v1/clear
curl -X POST https://example.com/wp-json/cocart/v1/clear \
  -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/clear",
  "method": "POST"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/clear",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_post( 'https://example.com/wp-json/cocart/v1/clear' );
$body = wp_remote_retrieve_body( $response );

JSON response example

"Cart is cleared."

Count Items

This API helps you count the items in the cart.

HTTP request

GET
/wp-json/cocart/v1/count-items
curl -X GET https://example.com/wp-json/cocart/v1/count-items \
 -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/count-items",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/count-items",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/count-items' );
$body = wp_remote_retrieve_body( $response );

JSON response example

1

Calculate Cart Totals

This API helps you calculate the cart totals. You can also request to return the totals once calculated to reduce API requests and use the Get Cart Totals properties.

Properties

Attribute Type Description
return bool Set as true to return the totals once calculated. optional

HTTP request

POST
/wp-json/cocart/v1/calculate
curl -X POST https://example.com/wp-json/cocart/v1/calculate \
    -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/calculate",
  "method": "POST"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/calculate",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_post( 'https://example.com/wp-json/cocart/v1/calculate' );
$body = wp_remote_retrieve_body( $response );

JSON response example

"Cart totals have been calculated."

Retrieve Cart Totals

This API helps you retrieve the cart totals. You can also return the totals pre-formatted to save you time applying the currency symbol.

Properties

Attribute Type Description
html bool Set as true to return the totals as strings with currency symbol. optional

HTTP request

GET
/wp-json/cocart/v1/totals
curl -X GET https://example.com/wp-json/cocart/v1/totals \
 -H "Content-Type: application/json"
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/totals",
  "method": "GET"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/totals",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/totals' );
$body = wp_remote_retrieve_body( $response );

JSON response example

{
  "subtotal":"123.00",
  "subtotal_tax":8.4,
  "shipping_total":"33.00",
  "shipping_tax":6.6,
  "shipping_taxes": {
    "12": 6.6
  },
  "discount_total":24.6,
  "discount_tax":0,
  "cart_contents_total":"98.40",
  "cart_contents_tax":8.4,
  "cart_contents_taxes": {
    "12": 8.4
  },
  "fee_total":"0.00",
  "fee_tax":0,
  "fee_taxes":[],
  "total":"146.40",
  "total_tax":15
}

Here is what to do to return the totals formatted with currency symbol.

curl -X GET https://example.com/wp-json/cocart/v1/totals \
  -H "Content-Type: application/json" \
  -d '{
    "html": true
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/totals",
  "method": "GET",
  "data": {
    "html" : true
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'html' => true
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/totals",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'html' => true
);
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/totals', $args );
$body = wp_remote_retrieve_body( $response );

JSON response example

{
  "subtotal":"£123.00",
  "subtotal_tax":"£8.40",
  "shipping_total":"£33.00",
  "shipping_tax":"£6.60",
  "shipping_taxes": {
    "12": 6.6
  },
  "discount_total":"£24.60",
  "discount_tax":"£0.00",
  "cart_contents_total":"£98.40",
  "cart_contents_tax":"£8.40",
  "cart_contents_taxes": {
    "12": 8.4
  },
  "fee_total":"£0.00",
  "fee_tax":"£0.00",
  "fee_taxes":[],
  "total":"£146.40",
  "total_tax":"£15.00"
}

Items

The most important part of CoCart is adding items to the cart.

Once items are in the cart, customers always make decisions on which items they want to buy now, change the quantities of a particular item and which items they should remove.

The following API's help with all of that.

Add Item to Cart

This API helps you to add an item to the cart. You can also request to return the whole cart once item is added to reduce API requests and use the Get Cart Content properties.

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 with the item. optional
refresh_totals bool Set as true to refresh the cart totals once item is added. optional
return_cart bool Set as true to return the whole cart once item added. optional

HTTP request

POST
/wp-json/cocart/v1/add-item
curl -X POST https://example.com/wp-json/cocart/v1/add-item \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 1722,
    "quantity": 1
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/add-item",
  "method": "POST",
  "data": {
    "product_id" : 1722,
    "quantity" : 1
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'product_id' => 1722,
  'quantity' => 1
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/add-item",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'product_id' => 1722,
  'quantity' => 1
);
$response = wp_remote_post( 'https://example.com/wp-json/cocart/v1/add-item', $args );
$body = wp_remote_retrieve_body( $response );

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. You can also request to return the whole cart once item is removed to reduce API requests and use the Get Cart Content properties.

Properties

Attribute Type Description
cart_item_key string The cart item key of the product in the cart. mandatory
return_cart bool Set as true to return the whole cart once item is removed. optional

HTTP request

DELETE
/wp-json/cocart/v1/item
curl -X DELETE https://example.com/wp-json/cocart/v1/item \
  -H "Content-Type: application/json" \
  -d '{
    "cart_item_key": 404dcc91b2aeaa7caa47487d1483e48a
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/item",
  "method": "DELETE",
  "data": {
    "cart_item_key" : "404dcc91b2aeaa7caa47487d1483e48a"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a'
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/item",
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'method' => 'DELETE',
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a'
);
$response = wp_remote_request( 'https://example.com/wp-json/cocart/v1/item', $args );
$body = wp_remote_retrieve_body( $response );

JSON response example

"Item has been removed from cart."

Restore Item to Cart

This API helps you to restore an item to the cart. You can also request to return the whole cart once item is restored to reduce API requests and use the Get Cart Content properties.

Properties

Attribute Type Description
cart_item_key string The cart item key of the product that was in the cart recently. mandatory
return_cart bool Set as true to return the whole cart once item is restored. optional

HTTP request

GET
/wp-json/cocart/v1/item
curl -X GET https://example.com/wp-json/cocart/v1/item \
  -H "Content-Type: application/json" \
  -d '{
    "cart_item_key": 404dcc91b2aeaa7caa47487d1483e48a
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/item",
  "method": "GET",
  "data": {
    "cart_item_key" : "404dcc91b2aeaa7caa47487d1483e48a"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a'
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/item",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a'
);
$response = wp_remote_get( 'https://example.com/wp-json/cocart/v1/item', $args );
$body = wp_remote_retrieve_body( $response );

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. You can also request to return the whole cart once item is updated to reduce API requests and use the Get Cart Content properties.

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
refresh_totals bool Set as true to refresh the cart totals once item quantity has updated. optional
return_cart bool Set as true to return the whole cart once item is updated. optional

HTTP request

POST
/wp-json/cocart/v1/item
curl -X POST https://example.com/wp-json/cocart/v1/item \
  -H "Content-Type: application/json" \
  -d '{
    "cart_item_key": "404dcc91b2aeaa7caa47487d1483e48a",
    "quantity": 2
  }'
var settings = {
  "url": "https://example.com/wp-json/cocart/v1/item",
  "method": "POST",
  "data": {
    "cart_item_key" : "404dcc91b2aeaa7caa47487d1483e48a",
    "quantity" : 2
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$curl = curl_init();

$args = array(
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a',
  'quantity' => 2
);

curl_setopt_array( $curl, array(
  CURLOPT_URL => "https://example.com/wp-json/cocart/v1/item",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $args,
  CURLOPT_RETURNTRANSFER => true
) );

$response = curl_exec($curl);

curl_close($curl);

echo $response;
<?php
$args = array(
  'cart_item_key' => '404dcc91b2aeaa7caa47487d1483e48a',
  'quantity' => 2
);
$response = wp_remote_post( 'https://example.com/wp-json/cocart/v1/item', $args );
$body = wp_remote_retrieve_body( $response );

JSON response example

{
  "message":"The quantity for 'Woo T-Shirt' has increased to '2'.",
  "quantity":2
}

Hooks

The cart API has a number of action hooks that you can use to extend the API to your needs.

See the tweaks plugin for examples.

Get Cart

Perhaps you need to apply something to the whole of the cart before it returns or send a notification. The choice is yours.

Use hook name: cocart_get_cart

Parameter Type Description
$cart_contents array An array of items added to the cart.

Clear Cart

Could be used to send a registered customer an email once they have emptied their cart. 😢

Use hook name: cocart_cart_cleared

Item Added

You can do something once an item has been added to the cart.

Use hook name: cocart_item_added_to_cart

Parameter Type Description
$item_key string The cart item key of the product in the cart.
$item_added array The details of the added item.

Item Removed

Use hook name: cocart_item_removed

Parameter Type Description
$current_data array The details of the item removed.

Item Restored

Use hook name: cocart_item_restored

Parameter Type Description
$current_data array The details of the item restored.

Item Quantity Changed

Should you need to change some other detail for the updated item.

Use hook name: cocart_item_quantity_changed

Parameter Type Description
$cart_item_key string The cart item key of the product in the cart.
$new_data array The details of the item updated.

Filters

The cart API has a number of filters that you can use to extend or change the API.

See the tweaks plugin for more examples.

Change thumbnail size

By default the size of the thumbnail uses woocommerce_thumbnail. You can change this by filtering the size using cocart_item_thumbnail_size filter.

add_filter( 'cocart_item_thumbnail_size', 'thumbnail_size' );

function thumbnail_size() {
  return 'thumbnail';
}

Return more item details

Sometimes you just need more product data for the items added. You can do so using cocart_cart_contents filter.

Parameter Type Description
$cart_contents array An array of items added to the cart.
$item_key string Unique generated ID for the item in cart.
$cart_item array An array of details of the item in the cart.
$_product object The product data of the item.
add_filter( 'cocart_cart_contents', 'return_product_weight', 15, 4 );

function return_product_sku( $cart_contents, $item_key, $cart_item, $_product ) {
  $cart_contents[$item_key]['sku'] = $_product->get_sku();

  return $cart_contents;
}

OK to add item?

Want to stop an item being added and return a custom message should it require an item not in the cart first.

Use the cocart_ok_to_add and cocart_ok_to_add_response filters.

Parameter Type Description
$status bool The status of adding an item to cart.
$response string The returned message.
$product_data object The product data of the item.
add_filter( 'cocart_ok_to_add', 'requires_specific_item', 10, 2 );

function requires_specific_item( $status, $product_data ) {
  $cart_contents = isset( WC()->cart ) ? WC()->cart->get_cart() : WC()->session->cart;

  $required_product_id = '123'; // Replace with real product ID number.

  foreach ( $cart_contents as $item_key => $cart_item ) { 
      // If required product ID does not exist return false.
      if ( $cart_item['id'] != $required_product_id ) {
        $status = false;
      }
  }

  return $status;
}
add_filter( 'cocart_ok_to_add_message', 'requires_specific_item', 10, 2 );

function requires_specific_item_response( $response, $product_data ) {
  $response = __( 'This item requires a specific item to be added first to the cart.' );

  return $response;
}

Return cart contents

If you are in need to change the formatting of the returned cart data, this filter is for you.

Use the cocart_return_cart_contents filter. In CoCart Pro you can filter the same results for removed cart contents.

// Returns the cart contents without the cart item key as the parent array.
add_filter( 'cocart_return_cart_contents', 'remove_parent_cart_item_key', 0 );

function remove_parent_cart_item_key( $cart_contents ) {
  $new_cart_contents = array();

  foreach ( $cart_contents as $item_key => $cart_item ) {
    $new_cart_contents[] = $cart_item;
  }

  return $new_cart_contents;
}

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 1.3

Doc Version 1.2

Doc Version 1.1

Doc Version 1 - Plugin Release v2

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 purchasing CoCart Pro where you not just get the full cart experience but also support me directly so I can continue maintaining CoCart and keep evolving the project.

Please also consider starring ✨ and sharing 👍 the project repo! This helps the project getting known and grow with the community. 🙏

Thank you for your support! 🙌