Commit 6ef1eda4a16 for woocommerce
commit 6ef1eda4a168d10d49b7d4a2ea22080880675bfd
Author: Ahmed Ismail <105542236+ahmedevsaad@users.noreply.github.com>
Date: Wed Nov 18 17:31:15 2026 +0200
Fill gaps in the Store API docs (#69770)
diff --git a/docs/apis/store-api/README.md b/docs/apis/store-api/README.md
index efa88211401..1b17cabe558 100644
--- a/docs/apis/store-api/README.md
+++ b/docs/apis/store-api/README.md
@@ -163,3 +163,96 @@ If you're looking to add _new routes and endpoints_, rather than extending the S
* [`register_rest_route()`](https://developer.wordpress.org/reference/functions/register_rest_route/)
* [Rest API Permissions Callbacks](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#permissions-callback)
+
+### Accessing the customer's cart from a custom route
+
+WooCommerce doesn't load the cart for REST requests outside the Store API, so `WC()->cart` is `null` in a route registered with `register_rest_route()`. Load it in your callback before using it:
+
+```php
+add_action(
+ 'rest_api_init',
+ function () {
+ register_rest_route(
+ 'my-extension/v1',
+ '/cart-summary',
+ array(
+ 'methods' => 'GET',
+ 'permission_callback' => function () {
+ if ( ! is_user_logged_in() && wp_validate_auth_cookie( '', 'logged_in' ) ) {
+ return new WP_Error( 'rest_cookie_invalid_nonce', 'Send a valid X-WP-Nonce header.', array( 'status' => 403 ) );
+ }
+
+ return true;
+ },
+ 'callback' => function () {
+ if ( ! function_exists( 'wc_load_cart' ) ) {
+ return new WP_Error( 'cart_unavailable', 'WooCommerce is not active.', array( 'status' => 503 ) );
+ }
+
+ wc_load_cart();
+ WC()->cart->get_cart();
+ WC()->cart->calculate_totals();
+
+ $response = new WP_REST_Response(
+ array(
+ 'items_count' => WC()->cart->get_cart_contents_count(),
+ 'total' => WC()->cart->get_total( 'edit' ),
+ )
+ );
+ $response->header( 'Cache-Control', 'no-store, private' );
+
+ return $response;
+ },
+ )
+ );
+ }
+);
+```
+
+`wc_load_cart()` sets up the session and an empty cart. It doesn't read the cart items, so call `WC()->cart->get_cart()` next, which loads the items and totals from the session. Then call `calculate_totals()`, because the stored totals can be out of date. Nothing re-checks them on load, so they go stale when a price, tax rate, shipping rate or coupon changed since the cart was last updated. After that, other cart methods such as `get_cart_contents()` and `get_total()` return the customer's cart.
+
+The response is different for every customer, so the example sends `Cache-Control: no-store, private`. WordPress only sends no-cache headers for logged-in users, and a page cache could otherwise serve one guest's cart to another.
+
+The session is read from the customer's cookies, so call the route from the browser with `credentials: 'same-origin'`. Also send an `X-WP-Nonce` header created with `wp_create_nonce( 'wp_rest' )`. WordPress handles the nonce in two ways:
+
+* If the nonce is invalid, WordPress rejects the request with a `rest_cookie_invalid_nonce` error before your callbacks run.
+* If no nonce is sent, WordPress runs the request as a guest, even when the customer is logged in. Loading the cart as a guest would discard the customer's session, so the example's permission callback rejects a request that has a logged-in cookie but no nonce.
+
+Guests don't need a nonce, but WordPress checks any nonce that is sent. A stale nonce, for example from a cached page, gets a 403 for guests too. That response doesn't include a refreshed nonce, so check `response.ok` before reading the body.
+
+The Store API `Nonce` and `Cart-Token` headers only work on Store API routes.
+
+Pass the route URL and the initial nonce to your script from PHP, so the URL works on any install layout:
+
+```php
+wp_add_inline_script(
+ 'my-extension-script',
+ 'const myExtension = ' . wp_json_encode(
+ array(
+ 'cartSummaryUrl' => esc_url_raw( rest_url( 'my-extension/v1/cart-summary' ) ),
+ 'restNonce' => wp_create_nonce( 'wp_rest' ),
+ )
+ ) . ';',
+ 'before'
+);
+```
+
+```js
+let restNonce = myExtension.restNonce;
+
+async function getCartSummary() {
+ const response = await fetch( myExtension.cartSummaryUrl, {
+ credentials: 'same-origin',
+ headers: { 'X-WP-Nonce': restNonce },
+ } );
+
+ // Each response carries a refreshed nonce. Use it for the next request instead of the initial one.
+ restNonce = response.headers.get( 'X-WP-Nonce' ) || restNonce;
+
+ if ( ! response.ok ) {
+ throw new Error( `Cart summary request failed with status ${ response.status }.` );
+ }
+
+ return response.json();
+}
+```
diff --git a/docs/apis/store-api/nonce-tokens.md b/docs/apis/store-api/nonce-tokens.md
index c1f61d1346a..dc0331c639e 100644
--- a/docs/apis/store-api/nonce-tokens.md
+++ b/docs/apis/store-api/nonce-tokens.md
@@ -32,6 +32,49 @@ wp_create_nonce( 'wc_store_api' )
There is no other mechanism in place for creating nonces.
+## Sending the nonce from JavaScript
+
+Pass a nonce and the Store API URL to your script from PHP:
+
+```php
+wp_add_inline_script(
+ 'my-store-script',
+ 'const myStoreApi = ' . wp_json_encode(
+ array(
+ 'nonce' => wp_create_nonce( 'wc_store_api' ),
+ 'root' => esc_url_raw( rest_url( 'wc/store/v1/' ) ),
+ )
+ ) . ';',
+ 'before'
+);
+```
+
+Then send it in the `Nonce` header, and keep the updated value the response returns:
+
+```js
+let nonce = myStoreApi.nonce;
+
+async function addToCart( id, quantity ) {
+ const response = await fetch( `${ myStoreApi.root }cart/add-item`, {
+ method: 'POST',
+ credentials: 'same-origin',
+ headers: {
+ 'Content-Type': 'application/json',
+ Nonce: nonce,
+ },
+ body: JSON.stringify( { id, quantity } ),
+ } );
+
+ nonce = response.headers.get( 'Nonce' ) || nonce;
+
+ return response.json();
+}
+
+addToCart( 100, 1 );
+```
+
+`credentials: 'same-origin'` sends the cookies that identify the customer's cart session.
+
## Disabling Nonces for Development
If you want to test REST endpoints without providing a nonce, you can use the following filter:
diff --git a/docs/apis/store-api/resources-endpoints/cart.md b/docs/apis/store-api/resources-endpoints/cart.md
index fd47513736c..ae916e773e9 100644
--- a/docs/apis/store-api/resources-endpoints/cart.md
+++ b/docs/apis/store-api/resources-endpoints/cart.md
@@ -601,6 +601,33 @@ POST /cart/update-customer
| `shipping_address.postcode` | string | no | Zip or Postcode of the address being shipped to. |
| `shipping_address.country` | string | no | ISO code for the country of the address being shipped to. |
+Send the addresses as a JSON body. Only the fields you include are updated, with one exception: if the cart doesn't need shipping and you omit `shipping_address`, the shipping address is set to the billing address.
+
+```sh
+curl --header "Nonce: 12345" --header "Content-Type: application/json" --request POST https://example-store.com/wp-json/wc/store/v1/cart/update-customer --data '{
+ "billing_address": {
+ "first_name": "Jane",
+ "last_name": "Doe",
+ "address_1": "123 Main Street",
+ "city": "San Francisco",
+ "state": "CA",
+ "postcode": "94107",
+ "country": "US",
+ "email": "jane@example.com",
+ "phone": "555-0100"
+ },
+ "shipping_address": {
+ "first_name": "Jane",
+ "last_name": "Doe",
+ "address_1": "123 Main Street",
+ "city": "San Francisco",
+ "state": "CA",
+ "postcode": "94107",
+ "country": "US"
+ }
+ }'
+```
+
Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.
## Select Shipping Rate
diff --git a/docs/apis/store-api/resources-endpoints/checkout.md b/docs/apis/store-api/resources-endpoints/checkout.md
index e75c7ec3a73..d0f35298b55 100644
--- a/docs/apis/store-api/resources-endpoints/checkout.md
+++ b/docs/apis/store-api/resources-endpoints/checkout.md
@@ -251,40 +251,21 @@ curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc
There are many payment gateways available for merchants to use, and each one will be expecting different `payment_data`. We cannot comprehensively list all expected requests for all payment gateways, and we would recommend reaching out to the authors of the payment gateway plugins you're working with for further information.
-An example of the payment data sent to the Checkout endpoint when using the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) is shown below.
+The example below shows the payment data the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) sends for a card payment. Other Stripe payment methods send different data, and the gateway may change it between releases, so check [the gateway source](https://github.com/woocommerce/woocommerce-gateway-stripe) for the current implementation.
-For further information on generating a `stripe_source` please check [the Stripe documentation](https://stripe.com/docs).
+For cards, the gateway creates a [Stripe PaymentMethod](https://docs.stripe.com/api/payment_methods) in the browser with Stripe.js and sends its ID. The PaymentIntent is created and confirmed on the server when the order is processed, so you don't send a PaymentIntent yourself. The older `stripe_source` key used Stripe's deprecated Sources API.
```json
{
+ "payment_method": "stripe",
"payment_data": [
{
- "key": "stripe_source",
- "value": "src_xxxxxxxxxxxxx"
- },
- {
- "key": "billing_email",
- "value": "myemail@email.com"
- },
- {
- "key": "billing_first_name",
- "value": "Jane"
- },
- {
- "key": "billing_last_name",
- "value": "Doe"
- },
- {
- "key": "paymentMethod",
+ "key": "payment_method",
"value": "stripe"
},
{
- "key": "paymentRequestType",
- "value": "cc"
- },
- {
- "key": "wc-stripe-new-payment-method",
- "value": true
+ "key": "wc-stripe-payment-method",
+ "value": "pm_xxxxxxxxxxxxx"
}
]
}