CoCart

I’m excited to announce that CoCart v3 Beta 2 is now available for beta testing! You can either download it directly from GitHub or install the CoCart Beta Tester plugin.

It’s a big update but one that is backwards compatible. You can still use API v1 while still enjoy some of the new features and improvements to CoCart.

In this release a new API providing more than before thanks to the feedback users have given. CoCart v3 brings a much better cart response with new options for developers to utilize.

Updating to the new API is easy. Some parameter defaults have changed while other parameters have changed for the better. Simply follow the upgrade guide and your good to go.

What’s New in CoCart v3?

In addition to a new API, new routes are also added to provide store information and administrator API for viewing carts in session and more.

• Get Store Details [GET] – wp-json/cocart/v2/store
• Add Grouped Products [GET] – wp-json/cocart/v2/cart/add-items
• Delete Cart [DELETE] – wp-json/cocart/v2/cart/{cart_key}
• Cart in Session [GET] – wp-json/cocart/v2/session/{session_id}
• Cart Items in Session [GET] – wp-json/cocart/v2/session/{session_id}/items
• Sessions [GET] – wp-json/cocart/v2/sessions

? NEW: Better cart response based on the experimental free add-on “Get Cart Enhanced“, improved REST API naming convention and a much better flow as most routes now return the cart by default.

? NEW: Basic Authentication now built in with the ability to authenticate via email address instead of username. ? No longer do you have to use the basic authentication handler by WP-API which is also outdated. See article for more information.

? NEW: Each route can be forced to check if the user (meaning only a logged in user) has permission to use the API. This requires the use of a new filter introduced. See article for more information.

NEW: Grouped products can now be added to the cart. See article for more information.

? NEW: Browse and Search CoCart add-ons or supported extensions from the plugin install page. See how to use plugin suggestions.

NEW: Support for TaxJar for WooCommerce plugin if you have v3.2.5 or above installed.

? NEW: Support for WooCommerce Advanced Shipping Packages extension.

? NEW: Support for WooCommerce Free Gift Coupons extension.

Notable fixes and improvements

• Tweaked: Session data now handled by new abstract to gain more control over it.
• Tweaked: Cart key now returns in the cart response the first time round. ?
• Tweaked: The loading of the session handler for better initialization by filtering it outside the action hook woocommerce_loaded.
• Tweaked: WooCommerce System Status Tools are made available even if COCART_WHITE_LABEL is set to true.

Admin notices have also been re-written for better management and improve on dismissing them.

API error validation has also be improved so even the smallest of errors caused by human error can get a clear explanation as to what went wrong.

Performance has also improved and while CoCart supports the minimum of PHP v7.0, I would recommend bumping to PHP v8.0 or above to give it a real boost in speed.

Minimum Requirements

As always security is important so support will available if you have WordPress v5.4 or above.

Filters and actions

This release introduces so many filters and action hooks that I need a new post just for them. 33 in total I think. I lost count. There maybe a few more I have not yet documented.

Extras

On top of the large number of newly introduced filters and action hooks. There are also newly introduced shared functions that can be used to develop your own extension for CoCart or add support for CoCart in a previously developed WooCommerce extension. More on that later.

Database Changes

The session table has two additions. Upon installing CoCart v3 you will be asked to upgrade the database. Please backup your site before proceeding. See article for more information.

Testing

If you discover any bugs during the testing process, please let me know by logging a report on the GitHub repository.

When using a REST-API, sometimes you don’t want all the routes to be available for public use and while CoCart is designed for the public, you may need a reason to restrict public use for certain routes.

Maybe you don’t support guest customers on your store so you need to restrict all the public routes.

Forcing API permissions doesn’t mean that only administrators or shop managers can access them. It’s not forced by user role. It just means that the routes can not be used unless the API is requested while being authenticated.

How do you force API permission?

It’s actually pretty easy. All you need to do is apply a filter based on the method of the routes you want to force permission on.

There are no parameters required. Just return an array of the API routes you wish to force permission on.

Filter name: cocart_api_permission_check_{method}

Replace {method} with get, post, put, delete or options. See example.

add_filter( 'cocart_api_permission_check_get', function() {
  return array(
  	'v1/count-items',
    'v2/cart/items/count',
    'v2/cart/totals',
    'v2/store'
  );
} );

This also works with the previous CoCart API and CoCart Pro. Just return the version of the API followed by the route. That’s it.

The core of CoCart needs to have all the basic requirements for any developer to have the base of the API ready to work out of the box for their development and authentication is one of them.

With CoCart v3, basic authentication is now built in and works like a charm.

Considering your web host allows authentication. If not, a little configuration to your .htaccess file will do the trick.

Simply add this to your .htaccess file and the authentication header will pass.

<IfModule mod_rewrite.c>
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
</IfModule>

As for security, basic authentication is recommended to be used on secure sites that have SSL enabled, so if you or anyone attempts to use the API on the site without it being secured. Then it will simply fail.

Unless you are testing on a local or development environment, CoCart will not allow you to authenticate via the basic method.

In addition to being able to authenticate via basic method. Unlike the basic authentication plugin provided by WordPress (which is also outdated a little), CoCart identifies email addresses as a username.

curl -X POST https://example.com/wp-json/cocart/v1/add-item \
  -u addtocart@cocart.xyz:password \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "35",
    "quantity": 1
  }'

This is helpful should the customer forget the username they created or was assigned when registering as a customer and use their email address (along with their password) instead.

Oh and one more thing. Should it not be possible to authenticate the right way using the headers, you can authenticate the user via URL.

https://example.com/wp-json/cocart/v1/add-item?username=addtocart@cocart.xyz&password=password

Please keep your sites secure!

One question I get asked from time to time is “Why does CoCart have it’s own session handler / database table?”

The reason for this is the default session handler is not designed to support guest customers outside of the site. It’s designed for the purpose of handling session requests with your browser.

Although guest customers were given a unique generated ID, this could only be tracked using the cookie WooCommerce stores on your device when browsing the store.

This does not help for a headless architect/setup when handling the cart outside of the site. So a new session handler was created in order to support guest customers for better tracking.

But why a new session table?

Well to begin with it was only experimental to test the new session handler but after sometime developing the new handler, I decided to keep it place for future developments.

This would allow me to alter the session table after without interfering with WooCommerce default session table structure.

This secures CoCart by making sure it still works should WooCommerce decide to change how their session table is structured in the future.

Now for the improvements

Although small, these additions I think are a great help to store managers and developers.

The new additions to the session table are “Cart Source” and “Cart Created“.

Now carts can be identified if they were created via CoCart or WooCommerce with the date and timestamp for when the cart was created the moment the first item was added to the cart.

I think this is a great addition and with that a new free add-on will be available that will allow you to view carts in session from your WordPress dashboard.

This is something users have been asking for and it has defiantly helped me with testing CoCart during it’s development.

Hope you like the new additions and add-on coming soon.

If you been wanting to add grouped products to the cart, well now you can in CoCart v3.

Bare in mind this is not the same as adding products in bulk. You are required to pass the product ID of the container product that is a grouped product along with the items it contains you wish to add to the cart.

Simply adding the container product to the cart will not automatically assume you want to add one of every item in the grouped product to the cart.

Adding a grouped product to the cart via CoCart acts exactly the same as you would on a normal WooCommerce store setup.

You need a minimum of one item in the grouped product along with the quantity of that item in order to successfully add the product to the cart.

curl -X POST https://example.com/wp-json/cocart/v2/add-items \
  -H "Content-Type: application/json" \
  -d '{
	"id": "91", /* Grouped product container. */
	"quantity": {
		"71": 2, /* Product ID: Quantity. */
		"72": 1
	}
}'

Each item from the grouped product added is validated. Any item that has restrictions from stock to quantity limits gone over will return an error response detailing which products could not be added.

So that is grouped products.

What about other bundled product types?

Support for developers have also been added to the API in order for extensions to add support for their product bundle types.

More product types will be supported in CoCart Pro in the future.