CoCart v4 Beta 1 Release Notes

CoCart v4 Beta 1 is ready for download and testing. This is the first release of the 4.0 cycle.

This version of the CoCart software is under development. Please do not install, run, or test this version on production or mission-critical websites.

CoCart 4.0 demonstrates incredible progress towards achieving the goals outlined in the Roadmap to v4. It has been an extensive journey, through more than a year of code restructuring, CoCart has evolved into the product we had envisioned, enabling WooCommerce stores to truly embrace a headless approach.

FYI: This post will focus on the Cart API experience but will list changes or additions to the Products API, Sessions API and WordPress dashboard. Some REST API changes are shared across.

So yeah… big update.

What’s New in CoCart v4?

• Added batch support and new batch endpoint to handle multiple cart requests to return a single cart response.
• Added the ability to add/update customer details to the cart with validation.
• Added ability to set customers billing phone number while adding item to the cart.
• Added ability to request product variations to return without the parent product.
• Added ability to filter the fields of the endpoint you request before they return, making the response faster. (Excludes Sessions API).
• Added ability to return the fields in the cart response based on a pre-configured option as alternative to filtering the fields individually.
• Added new endpoint to delete all items (only) in the cart.
• Added new endpoint to delete a session.
• New Settings Page to provide some control of default configurations and security.
• Added the ability to disable access to WordPress.
• Security to prevent price hijacking.
• New WP-CLI command wp cocart status shows the status of carts in session.
• Added package information of each plugin module to WooCommerce System Status.

For a recap of what’s coming in 4.0, please refer to the what’s coming post, which summarizes key features.

What’s Changed?

• Session handler now initiates faster without the need to lookup a cookie for the use of CoCart’s API while leaving the original handling for the native WooCommerce intact for the front-end.
• Monetary values improved and return all as a float value for better compatibility with JavaScript frameworks.
• Caching of the same item added to cart no longer loses previous custom price set before and has not changed.
• Error responses are now softer to prevent fatal networking when a request fails.
• Deprecated action hooks and filters return messages if actually triggered.
• Re-organized what routes are allowed to be cached i.e products API rather than prevent all CoCart routes from being cached.
• Sessions API now has pagination and order filtering.

Authentication

A few enhancements have been made for authentication. First is when the WordPress login cookies are set, they are not available until the next page reload.

Specifically for returning updated carts, we need this to be available immediately so now they are forced to be available without reload.

This is only to help with frameworks that have issues with or lack of support for Cookies where a developer chooses to use.

Second. Customers can now authenticate with their billing phone number and password. This is helpful for certain countries where they force customers to login with their phone number instead of username or email address.

Batch Supported

A long awaited requested feature is now available. While we could have just enabled batch support for all cart routes it wasn’t enough or perfect for the service that CoCart is providing to the developers.

We needed to be able to utilize what WordPress has built in while still providing the same cart flow. Now with our new batch endpoint added you can now make multiple requests and receive just the one cart response resulting all the requests together.

API v2 supported ONLY!

curl -L 'http://myawesome.store/wp-json/cocart/batch' \
-H 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "method": "POST",
            "path": "/cocart/v2/cart/add-item",
            "body": {
                "id": "1113",
                "quantity": "1"
            }
        },
        {
            "method": "POST",
            "path": "/cocart/v2/cart/add-item",
            "body": {
                "id": "61",
                "quantity": "1"
            }
        },
        {
            "method": "POST",
            "path": "/cocart/v2/cart/update?namespace=update-customer",
            "body": {
                "first_name": "Sebastien",
                "last_name": "Dumont",
                "email": "thatisnomoon@space.com",
                "phone": "01908672352",
                "company": "Darth Vadar LTD",
                "address_1": "70 The Crescent",
                "address_2": "",
                "city": "BELFAST",
                "state": "",
                "country": "UK",
                "postcode": "BT90 2PU",
            }
        }
    ]
}'

Capture Customer Information

Handling session information for the cart was a challenge but one that is finally complete so now we are able to capture customer information fully.

Our new cart callback allows you to do just that.

curl -L 'https://myawesome.store/wp-json/cocart/v2/cart/update?cart_key=guestcart123&namespace=update-customer' \
-H 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Sebastien",
    "last_name": "Dumont",
    "email": "thatisnomoon@space.com",
    "phone": "01908672352",
    "company": "Darth Vadar LTD",
    "address_1": "70 The Crescent",
    "address_2": "",
    "city": "BELFAST",
    "state": "",
    "country": "UK",
    "postcode": "BT90 2PU",
    "s_address_1": "515 Cherry Drive",
    "s_city": "San Pablo",
    "s_state": "CA",
    "s_postcode": "94806",
    "s_country": "US",
    "s_company": "Galaxy Ruler LLC",
    "ship_to_different_address": true
}'

Return only fields you need

Being able to return only the fields you need is defiantly important. Not all fields are required for every store or situation so data is only fetched if requested, not simply removed after the fact.

Fields of your choosing (for most of them) including only nested fields can be returned and no more. This will improve over time for the cart.

Here is an example of only returning the following fields for the cart: cart_key, customer, items and totals

curl -L 'https://myawesome.store/wp-json/cocart/v2/cart?fields=cart_key,customer,items,totals'

This returns a much lighter load making the responses faster.

There are also pre-configured options available which can be passed by another parameter config[fields] as an alternative to filtering the fields individually for the cart.

curl -L 'https://myawesome.store/wp-json/cocart/v2/cart?config[fields]=digital

Each option returns only the minimum fields suited to that configuration. The second configuration for digital or shipping simply returns the fees field on top should your store be using them.

• digital
• digital_fees
• shipping
• shipping_fees
• removed_items
• cross_sells

Improvements and Tweaks

• Use of Namespaces has now been applied to help extend CoCart, easier to manage and identify for developers.
• Fetch total count of all carts in session once when displaying the status under “WooCommerce → Status“.
• Plugin Suggestions now returns the results better the first time it’s viewed.
• Sub-menus in the WordPress dashboard now load faster. No redirects.
• Optimized the Products API response and updated schema.
• All endpoints with schema now have proper schema title for proper identification.
• The callback for cart update endpoint now passes the controller class so we don’t have to call it a new.
• Store route only returns the version, routes and link to documentation if WP_DEBUG is true.
• Session API has been updated to match the response of the Cart API without causing hiccups with the sessions it’s self.

Monetary values

All monetary values in the cart are formatted after giving 3rd party plugins or extensions a chance to manipulate them first and all return as a float value. This includes using the following filters at priority 99.

• cocart_cart_item_price
• cocart_cart_item_subtotal
• cocart_cart_item_subtotal_tax
• cocart_cart_item_total
• cocart_cart_item_tax
• cocart_cart_totals_taxes_total
• cocart_cart_cross_item_price
• cocart_cart_cross_item_regular_price
• cocart_cart_cross_item_sale_price
• cocart_cart_fee_amount
• cocart_cart_tax_line_amount
• cocart_cart_totals_taxes_total
• cocart_cart_totals
• cocart_session_totals

Now developers have consistent format that can be used with the likes of WooCommerce’s Number and Currency modules.

However, you can now config the cart to return all monetary values preformatted for you. See example here. ↴

curl -g 'http://myawesome.store/wp-json/cocart/v2/cart?config[prices]=preformatted'

...
"items": [
  {
    "item_key": "c92a10324374fac681719d63979d00fe",
    "id": 2026,
    "name": "Sword",
    "title": "Sword",
    "price": "£69.64",
    "quantity": {
      "value": 3,
      "min_purchase": 1,
      "max_purchase": -1
    },
    "totals": {
      "subtotal": "£208.92",
      "subtotal_tax": "£0.00",
      "total": "£208.92",
      "tax": "£0.00"
    },
    ...

Deprecation’s and Replacements

There are many deprecation’s made with this release but nothing that should affect you unless you were using certain functions directly within your code.

• Legacy API that extended wc/v2 when CoCart was only a prototype is gone.
• Session cookie is now reverted back to original WooCommerce session cookie for native support.
• Filter cocart_customer_id no longer used to override the customer ID for the session.
• Filter cocart_cookie no longer used as the session cookie has been reverted back to default.
• Filter cocart_no_items_message replaced with another filter cocart_no_items_in_cart_message that is shared in other endpoints.
• Filter cocart_empty_cart no longer used. If you wish to detect if the cart is empty to change the response, use filter cocart_cart with function $this->is_completely_empty().
• Function WC()->session->use_httponly() no longer used.
• Function WC()->session->cocart_setcookie() no longer used. Replaced with cocart_setcookie().
• Function WC()->session->get_cart_created() no longer used. Replaced with cocart_get_timestamp().
• Function WC()->session->get_cart_expiration() no longer used. Replaced with cocart_get_timestamp().
• Function WC()->session->get_cart_source() no longer used. Replaced with cocart_get_source().

For Developers

A lot more new filters and hooks have been introduced to help support or even extend CoCart. Some have parameters updated.

• Introduced new filter cocart_cart_item_extensions to allow plugin extensions to apply additional information.
• Introduced new filter cocart_is_allowed_to_override_price that by default will always allow overriding the price unless stated otherwise when an item/s is added to the cart.
• Introduced new filter cocart_cart_totals that can be used to change the values returned.
• Introduced new filter cocart_accessible_page_ids to allow you to set the page ID’s that are still accessible when you block access to WordPress.
• Introduced new filter cocart_validate_ip that can be used to validate if the IP address can access the API.
• Introduced new filter cocart_api_rate_limit_options to set the rate limit options.
• Introduced new filter cocart_after_get_cart to allow you to modify the cart contents after it has calculated totals.
• Introduced new action hook cocart_api_rate_limit_exceeded to allow you to include your own custom tracking usage.
• Added new parameters to filter cocart_cart so you can access the cart controller and requested data.
• Introduced new action hook cocart_added_item_to_cart that allows for additional requested data to be processed via a third party once item is added to the cart.
• Introduced new action hook cocart_added_items_to_cart that allows for additional requested data to be processed via a third party once items are added to the cart.

Database Changes

We now store the user ID and customer ID as a separate unique value to the cart session. We have to update the database structure in order to save it so an upgrade will be required.

This is a big change, so until your WordPress site has processed the update for CoCart it will fallback on a legacy session handler to not disrupt your store from working.

As always it is best to back-up before any database changes are made. When proceeding with the update, the cart session will not be active again until the upgrade is complete.

Support Changes

• No longer support stores running PHP 5.6, 7.0, 7.1, 7.2 and 7.3
• No longer supporting CoCart API v1. Only bug or security fixes will be provided (if any).

Following WooCommerce Requirement Changes

As we are a product that extends WooCommerce we must also follow suit to the PHP versions that they support. However, we understand not all stores are going to be upgrading to the latest version of WooCommerce just like that, which is why the minimum version CoCart will support is 6.9.

It’s important to know that WooCommerce develops at a fast pace and as much as we want to support those who have been using CoCart since the beginning, supporting older versions will phase out as we maintain our product.

FYI: If you are able to update or are starting a new store from scratch. It’s best that you run PHP 8.1 for best performance. You can go as high as PHP 8.2 but not all WooCommerce extensions that we know off (at the time of this post) has solved their deprecation issues which can make the REST API not return valid JSON responses.

Testing makes CoCart stronger!

Testing for issues is a critical part of developing any software, and it’s a meaningful way for anyone to contribute—whether you have experience or not.

While testing the upgrade process is essential, testing new features is too. Review the many new features listed above and focus your testing efforts on those areas in particular.

If you discover any bugs during the testing process, please let us know by logging a report in GitHub.

Get CoCart 4.0 Beta 1

You can test CoCart 4.0 Beta 1 in two ways:

• Option 1: Install and activate the CoCart Beta Tester plugin (select the “Beta Releases” channel if not all ready) and update the plugin. (Must already have stable plugin installed.)
• Option 2: Direct download the Beta 1 version (zip).

The current target for the final release is August 15th, 2023, which is about 2 and half weeks away. Your help testing this version ensures everything in this release is the best and ready to move to a release candidate next week with final corrections and tweaks.

Help translate CoCart

Do you speak a language other than English? ¿Español? Français? Português? Русский? 日本? Help translate CoCart into more than 100 languages.