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"
     }
   ]
 }