/store/v1/cart/add-item not reflected on Cart Page

[phil-sola]

Prerequisites

• I have carried out troubleshooting steps and I believe I have found a bug.
• I have searched for similar bugs in both open and closed issues and cannot find a duplicate.

Describe the bug

I have been testing out the store API this evening for an upcoming project I’m working on, and have hit a stumbling block fairly quickly.

I am able to send a successful POST request to the /store/v1/cart/add-item?id=39&quantity=1

I get a 201 created success response with the cart object back, however if I go to the cart page on the WordPress site to test the items have indeed programmatically been added to cart, the cart page is empty. No items whatsoever.

I can tried clearing down all cache, transients etc. but it never updates on the cart page.

Expected behavior

I would expect the cart page to reflect the API cart data as they should be the same thing essentially. The only difference being, I’m adding the items programmatically via the API.

Actual behavior

I am getting the updated cart data back from the API, however I’m seeing 0 items in the cart page on WordPress.

I appreciate I wouldn’t be using the WooCommerce cart page on this project, it would be a headless site using Next Js but I would expect the data to be in sync so it is concerning the cart page shows zero items.

Steps to reproduce

Install a clean install of WP using the 2024 theme.
Install WooCommerce plugin
Make a POST request to the add-item endpoint
Refresh the cart page and see no items added despite a success response from the API.

WordPress Environment

I will add later - not at my computer now.

Isolating the problem

• I have deactivated other plugins and confirmed this bug occurs when only WooCommerce plugin is active.
• This bug happens with a default WordPress theme active, or Storefront.
• I can reproduce this bug consistently using the steps above.

[jonathansadowski]

Hi @phil-sola,

Thanks for your report. Could you please include information from your system status report? You can get this under WooCommerce > Status, then select "Get system report" followed by "Copy for support".

According to the documentation for the Store API:

Data returned from the API is reflective of the current user (customer). Customer sessions in WooCommerce are cookie-based.

Are you using the same session cookie when making the API call as you're using while viewing the cart?

[senadir]

Hey! we discussed this on twitter but just for future people coming to this issue:

You need to link the cart you created in Postman to something, an account, or a session. This is either done via authentication, cookies, or cart token header. In your case, you're mixing 2 different things, the WooCommerce theme site, and the API, and you're not sharing any session data between them.

[phil-sola]

Thanks @senadir, though that's not entirely true. I have tried sending the POST request with an application password for my account, I have tried sending back the Cart-Token heeader as well with no joy getting this to work.

I seem to have got this working just now, trying different things. It seems that the store API does require authentication for a headless site, whereas the docs seem to indicate it doesn't: https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/src/StoreApi

Under Requirements and limitations it states: This is an unauthenticated API. It does not require API keys or authentication tokens for access.

When I remove the App PW from postman, the POST request no longer works, despite using the same Nonce header and Cart-Token header.

When I use Basic Auth again, it doesn't matter if I have the Cart-Token header or not, it still works.

If I remove the Nonce header, it doesn't work regardless of if I am using basic auth or not.

So the only for this to work it seems is to use the Nonce header + App PW (or JWT etc) if using this remotely without a cookie which isn't indictaed anywhere in the docs....

Pretty frustrating documentation around this to be honest and it's wasted a lot of my time. If it clearly stated somewhere the need for an App PW / JWT I could have done that 2 days ago.

Cart-Token seems irrelevant in that case and not sure what it's purpose is?

Cart-Tokens again, aren't mentioned anywhere in the docs from what I can see...

[senadir]

The API is unauthenticated in a sense that you don't need to be authenticated to use it, you can have it work with guest sessions just fine, I'm sure of that because I built a store with it already

https://github.com/senadir/headless-woocommerce, it's an old repo so the code might not work anymore.

At that time, to get guest sessions to work, you needed to exchange cookies back and forth with the website, to fix that, we introduced Cart Token later on.

So to summarize:

Logged-in/registered customer:

For a logged-in customer to work, you need one of the following:

• Basic Auth.
• JWT.
• Application password (thou I didn't test this).
• OAuth.

Sending a request, that is authenticated with any of the above, would work, you would get the cart back.

If you log in to your website after that, you would see your cart there as well, because the session is saved to that user account.

Guest customer:

For a guest customer to work, you need one of the following:

• Pass session cookies back and forth, mainly the woocommerce_cart_hash and wp_woocommerce_session_* cookies.
• Pass a Cart token back and forth.

[senadir]

For a guest customer, you cannot except to create a cart in postman, and have it appreciate when you navigate to the website, as the website has no way to know which session to load.

[senadir]

I do agree that the docs are lacking in that area, and it's my goal to fully expand them.

[phil-sola]

Thank you @senadir that information breakdown in black and white is exactly what I was looking for on the documentation. This would help a lot of other people as well I think.

it makes total sense and I now understand as well the use of the Cart Token - thank you! I think I read somewhere the cart token changes on each request. Do I need to update that Header every time or using the previous one for the same user will still work? Seems clunky if I have to change that token every single time they do something.

As you mentioned on Twitter I would love to see a full tutorial on this from start to finish with a checkout and payment process. I will also look through the repo you shared!

I really appreciate you going above and beyond to help me with this and remaining patient. I am a full time developer and use the core REST API and custom routes a fair bit, but the documentation for this API is lacking to say the least.

I’m very grateful!

[senadir]

it makes total sense and I now understand as well the use of the Cart Token - thank you! I think I read somewhere the cart token changes on each request. Do I need to update that Header every time or using the previous one for the same user will still work? Seems clunky if I have to change that token every single time they do something.

So the token is a JWT and if you decode it here in jwt.io, you should see the payload:

https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidF9kY2E0ZmZjNjQyNzFiZDRlMzIzZTA1Y2FmODMzZGEiLCJleHAiOjE3MTQ2ODU3MzksImlzcyI6IndjXC9zdG9yZSIsImlhdCI6MTcxNDUxMjkzOX0.-_HvzHrXgagrerxvU-_CS729jTUFbN-y_pR2DY0ybwE

{
  "user_id": "t_dca4ffc64271bd4e323e05caf833da",
  "exp": 1714685739,
  "iss": "wc/store",
  "iat": 1714512939
}

What changes is the values in exp (expiration date) and iat (issued at), as the token is refreshed on each request, so does the nonce, as it's linked to the current session and can change if you log in or create a new session.

What people usually do is create a middleware in your fetching library (axios interceptors for example, like here), so you would save the token and nonce in local storage, and on each request, you add them, and in each response, you read them and save them to the cache.

The link above for my repo shows how to use it for most part, and this diff shows how you can get WooCommerce Payments working.

Though I personally think that we should build checkout urls functionality, so that a shopper can build their cart in your headless website, but get redirected to your hosted store for Checkout, more or less how Shopify, BigCommerce, and Magento does it, so that you don't have to build the payment UI yourself.

[phil-sola]

I do agree that the docs are lacking in that area, and it's my goal to fully expand them.

Wow, you've explained the details of this API more in the last 30 mins than I was able to get from the docs in the last 2 days!!

We (the community) need you and I can't wait to see what can be done to expand the documentation to clearly explain some of this. There is absolutely no way for anyone to know these things if it's not documented somewhere to learn from.

the payment_data array is another big one that needs far more documentation when it comes to the ordering process and checkout.

I'm starting to finally see how this API may actually be suitable for me going forwards thanks to you.

Please carry on your mission to improve all of this - it's greatly needed!

[senadir]

Thank you! I really appreciate your feedback :D

One last point is that when it comes to payment_data, it's a blackbox for me, because it's meant for the payment processor, I can get some people (like I did back in the headless store) and have explain what data their payment method need and how to collect it, but each payment method has its own thing.

Offline ones like Cash on Delivery, bank transfer, and Check payments have nothing in that field, WooCommerce Payments and WooCommerce Stripe have 3-4 fields in that section (as well as needing to initiate a payment intent server side), I have no idea what PayPal needs for example, and so on. This would be some sort of reverse engineering process, though my goal is to have the WooCommerce Payments team publish some sort of helper tools/functions/UI to collect those fields and send them back.

[phil-sola]

Honestly, thank you. It's amazing what speaking to someone knowledgeable, helpful and patient can do. Everything you've said makes complete sense.

I did raise some support tickets recently on .org with a couple of payment gateways around what was required for this field, WooCommerce Stripe for example, and they were as helpful as they could me via the support channel on .org but did say for developer support I'd need to contact offline.

Again, ideally, these APIs shouldn't be black boxes for anyone wishing to use them - especially APIs built on WordPress as an open source platform. Some work needs to be done to get other payment gateways on board as you say and get some clearer documentation on this, otherwise the only other option as you say is to reverse engineeer the thing and waste a ton of time in the process. I know many people to whom the ordering process is almost unusable with the lack of docs around the payment_data array.

[lanej0]

@senadir I'm just going to assign this to your team for triage purposes. If you've already dealt with this issue/are tracking documentation updates separately, feel free to close it.

[opr]

Thanks all who were involved in this discussion, I'll close this issue as I don't believe we have anything actionable here, besides documentation updates, which we'll take care of as we're looking to expand our tutorials.