Load Cart from Session

This is a feature that is not part of the REST API. It’s purpose is to load a cart that is currently in session so guest customers can continue to shop or checkout via the native store.


It does not matter if your customer is logged in or not already via the native version of your store. Only the cart data will be loaded. Customer details are not transferred.

You can choose to override the cart (if anything is set) or merge the cart items together.

If a customer is already logged in via the native version of your store then items currently in the cart will merge together with the items in the guest customers cart.

There is one exception and that is if the same item already exists in the cart. It will not increase or decrease the quantity if the item in the cart has a matching cart item key.

How to load a cart from session?

To load a cart from session, you must use the parameters below to query your store. You can query any page you prefer your customer to land on as the cart is loaded in the background.

cocart-load-cartstringSet the cart key of the cart you wish to load. RequiredYou can rename this parameter if you like.
notifyboolSet as true to notify customers once arrived on the web version of your store. Default is false
keep-cartboolSet as false to merge cart data. Default is true

Here is an example of loading a guest customers cart on the native cart page.


If you are currently developing or debugging I recommend that you enable the notify parameter so that you can confirm if the session has not expired.

It’s also a good way to tell your customers that their cart has transferred over to your native store so they may continue there.



The notification will only appear if the theme or page displays them.

Notice: Success

You will see this notice if successully loaded a guest customers cart.

Your cart has been transferred over. You may continue shopping or checkout.

You can filter the success message if you like.

add_filter( 'cocart_cart_loaded_successful_message', function() {
    return sprintf( __( 'You may %1$scontinue shopping%3$s or %2$scheckout%3$s.', 'your-text-domain' ), '<a href="' . wc_get_page_permalink( 'shop' ) . '">', '<a href="' . wc_get_checkout_url() . '">', '</a>' )

Notice: Failed

Sorry this cart has expired!

You will see this notice if the cart has expired or never existed to begin with.

If you feel the cart in session has not expired then check that the cart key was correct, and check that it did not exceed 42 characters as that is the limit for allowing a cart session to save in the database.

Technical error made! See error log for reason.

If for some reason you get this notification with debug mode enabled, it’s because you tried to load a cart that belongs to a registered customer.

For security reasons we don’t load the cart session of a registered customer. They cannot be loaded as a guest.


What is a cart item key?

A cart item key is what identifies the item in the cart once added. It’s made of four key values: Product ID, Variation ID, Variation attributes and Cart item data.

Is the session in sync?

The session is always synced, (so long as you are using the same session) so if the customer was to continue via your headless store again after you loaded the session to the native store, the cart items would match. This is true for all customers, registered or guests.

Can I rename the cart action query name?

Yes you can. Just make sure the query name is not something that is already used on your native store.

add_filter( 'cocart_load_cart_query_name', function() {
    return 'hello-there';

Was this helpful to you?