Store API

On the test store GET /products/collection-data?calculate_price_range=true&calculate_stock_status_counts=true answered with a price_range of {"min_price": "0", "max_price": "4900", ...} in minor units and an instock count, and /products/categories listed the categories with their count.

The routes that change the cart (add-item, update-item, remove-item, coupons, update-customer, select-shipping-rate, extensions) return the whole cart, so a client can replace its state with the response.

The shopper-lists routes added in 10.9.0 are not registered on the test store (they sit behind a feature) and are not covered here.

Source: WooCommerce developer documentation: Store API cart endpoints and Checkout endpoint

A batch with a good and a bad sub-request returned HTTP 207 and one result per request, and a path outside the Store API was refused outright (observed):

The path check is the fix for CVE-2026-3589, a cross-site request forgery through the batch endpoint of WooCommerce 5.4.0 to 10.5.2 that let an unauthenticated visitor make a logged-in administrator’s browser call non-store REST routes; the fix shipped in 10.5.3 on 2026-03-02. Keep stores updated: the Store API is public and attackers read the same source.

Since 11.1.0 the client can send the total it displayed to the shopper as expected_total (a string in the smallest currency unit). If the recalculated total is higher, the API refuses the order with 409, before any order is created, and returns the current cart so the app can show the new price. Omit the field for flows that cannot know the final total. A request that sent 100 for a cart of 22.30 EUR was refused like this:

Source: WooCommerce developer documentation: Checkout endpoint

These are the results of the access attempts on the test store (observed, add-item on a fresh guest cart):

The official documentation says all checkout requests need a nonce or token, and that only cart writes (not cart reads) do; the table above matches that.

Every successful cart or checkout response carries these headers; error responses caused by a failed cart session load do not include Cart-Token and Cart-Hash.

A Cart-Token is a JSON Web Token (HS256) signed with a key derived from the site’s salts. Its payload holds the session customer ID (user_id, which for a guest is a generated value starting with t_), the expiry (exp), the issuer (iss, always store-api) and the issue time (iat). The expiry is the WooCommerce session lifetime, two days by default and adjustable with the wc_session_expiration filter. Decoding the token of the test store gave (the user ID is a throw-away guest identifier):

exp minus iat is 172800 seconds, two days. A token that does not validate is ignored: a request that sent a garbage value in Cart-Token was answered 200 with a new token and a new, empty cart, so a client must compare tokens and detect that its cart was lost. If a store changes its salts, all tokens in the wild stop validating.

On development sites the check can be turned off for testing REST clients:

Source: WooCommerce developer documentation: Nonce tokens

Never enable that on a production store: the nonce is the protection against cross-site request forgery for cookie sessions. For the Cart-Token the documentation is at Cart tokens.

Store API responses carry their own CORS headers, because some routes return personal data. The default WordPress allow-all behaviour is replaced: an origin gets Access-Control-Allow-Origin only if it is an allowed origin (the WordPress allowed_http_origins filters extend the list), or the request has a valid Cart-Token, or it is a preflight request. The test store answered a preflight like this and gave a cross-origin GET /cart without a token no allow-origin header (observed):

Only Cart-Token is exposed to browser scripts, not Nonce, so a headless front end on another origin is expected to use the Cart-Token flow.

Source: WooCommerce developer documentation: Cart tokens

Source: WooCommerce developer documentation: Store API rate limiting

When a client is over the limit, the API answers 429 with the code rate_limit_exceeded, the message "Too many requests. Please wait N seconds before trying again." and rate-limit headers. The headers are sent on every counted request:

The test run (limit 5 per 20 seconds, a guest client, requests to apply-coupon with an unknown code, all of which answered 400 until the limit) printed:

The documentation says only POST requests are limited. On 11.2.1 the general limit counted every request that reached the Store API: three GET /products requests lowered RateLimit-Remaining from 5 to 2, a GET /cart and a POST /batch took it to 0, and GET requests were answered 429 once the limit was reached. What the documentation describes (POST only, and not requests sent with X-HTTP-Method-Override) is the behaviour of the separate checkout limit below. Plan the limit with that in mind, and test it on a staging site with real client traffic before enabling it in production.

Two more rules from the source apply. Users who can edit_posts (administrators, shop managers, editors) are never rate limited: the same loop with an application password of an administrator returned 200 seven times and no RateLimit-* headers. And requests are grouped by the user ID when logged in, otherwise by a hash of the client IP address.

With proxy_support set to true the client IP is read from X-Real-IP, Client-IP, X-Forwarded-For (first address), then Forwarded; without it, all clients behind a load balancer or CDN share the proxy’s address and one visitor can lock out everyone. Enable it only when the proxy overwrites those headers, because a client can otherwise spoof them. An invalid IP is grouped as 0.0.0.0. To group differently (by a hash of other request properties), return a string from the filter woocommerce_store_api_rate_limit_id:

Source: WooCommerce developer documentation: Store API rate limiting

WooCommerce, Settings, Advanced, Features has an option "Rate limit Checkout" (feature rate_limit_checkout, off by default). When on, only POST /checkout (the place-order action of the Checkout block) is limited, to 3 requests per 60 seconds, and requests sent with an X-HTTP-Method-Override header (the Gutenberg apiFetch way of sending PUT and PATCH) are not counted. The filter above still applies for everything else, and the settings option does not need the filter. This feature was not switched on during the run because it is a global setting of the shared test store, and the behaviour is described from the 11.2.1 source and the documentation.

woocommerce_store_api_register_endpoint_data() adds a namespaced object to the extensions key of a response. The extensible endpoints are identified by the IDENTIFIER constant of their schema class.

The arguments:

Register on the woocommerce_blocks_loaded action, because the dependency injection container is not available earlier. The function returns true, or a WP_Error when the arguments are wrong. The class ExtendSchema is one shared instance of the Store API container: never create it with new. Three global helpers wrap it: woocommerce_store_api_register_endpoint_data(), woocommerce_store_api_register_update_callback() and woocommerce_store_api_register_payment_requirements(), plus woocommerce_store_api_get_formatter() which returns a formatter (money, currency, html, default) that converts a value to the shape the API uses, for example a decimal amount to the string of minor units.

If a callback throws or returns something that is not an array, the error is written to the WooCommerce logs and the response carries an empty or missing object for that namespace; the exception is re-thrown only when WP_DEBUG is on and the current user can manage_woocommerce, so a shopper never sees it and a bug can stay unnoticed in production. Check the logs when an extension "does not show up". Never put secrets or personal data of other people in the data: the responses are public.

Source: WooCommerce developer documentation: Exposing your data in the Store API and Available extensible endpoints

This plugin was installed and run on the test store. It registers the roast date on products and cart lines, the gift wrap flag on the cart, the update callback that toggles gift wrap, a fee that follows the flag, a copy of the flag to the order, and a rate limit. It passes phpcs --standard=WooCommerce-Core with no findings. During the tests the rate limit filter was hooked only for requests carrying a test header, so that other requests to the shared test store were not throttled; the code below is the unguarded version.

Source: WooCommerce developer documentation: Exposing your data in the Store API

The observed results of the registrations:

A client cannot write to the extensions object. Changes go through POST /cart/extensions, which runs the update callback registered for the namespace, then recalculates the cart and returns it with fresh extension data. One callback exists per namespace, a second registration under the same namespace replaces the first, so route several actions through one callback with an action key in the data, as the plugin does.

The request and response observed on the test store (the gift-wrap action, trimmed):

The error paths:

A callback may throw Automattic\WooCommerce\StoreApi\Exceptions\RouteException with ( $code, $message, $http_status ) to answer a chosen 4xx, which is what the plugin does and what core routes do; any other exception from the callback becomes, according to the 11.2.1 source (not run), a 500 woocommerce_rest_unknown_server_error. The exception class is internal to the Store API namespace, so check it on upgrade. Because only the route’s own argument validation runs before a callback, a callback must validate and sanitize every value in $data itself.

From a block, the client side is the JavaScript function extensionCartUpdate, which calls this same endpoint and then refreshes the block’s cart state. This is the official example (it was not run on the test store, which has no block build toolchain):

Source: WooCommerce developer documentation: Updating the cart on-demand

woocommerce_store_api_register_payment_requirements( array( 'data_callback' => ... ) ) registers a callback that returns extra payment requirement strings; the cart’s payment_requirements array (default ["products"]) is the union of the defaults and what the callbacks return, and a payment method declares which requirements it supports. It is how an extension (for instance subscriptions) tells the checkout that only some gateways can pay for the cart. It is documented with the other extension APIs and was not exercised here.

Source: WooCommerce developer documentation: Add payment requirements