Store API and Native Hooks

Woo components send cart and checkout mutations through WooCommerce Store API. That is important because Store API still runs Woo's native cart, pricing, checkout, payment, order, and status hooks.

That means Etch-authored Woo screens still pass through WooCommerce's normal validation, pricing, payment, and order lifecycle.

Cart Requests

WooStoreApiClient sends cart requests with a nonce and cart token. One cart-only FIFO coordinator orders mutations so the UI is not racing multiple responses. Checkout keeps its separate request lane.

UI action	Store API request	Native behavior tested
Product add	POST /cart/add-item	Add-to-cart validation can block, add item data can be injected, and add actions fire.
Quantity change	POST /cart/update-item	Cart totals refresh after Woo recalculates cart state.
Remove item	POST /cart/remove-item	Cart item rows and totals refresh before empty state appears.
Apply coupon	POST /cart/apply-coupon	Discount totals and coupon rows update.
Remove coupon	DELETE /cart/coupons?code=...	Coupon rows and totals update.
Shipping selection	POST /cart/select-shipping-rate	Selected package rate and totals update.

Checkout Requests

WooCheckoutStore also queues requests:

UI action	Store API request	State
Boot checkout	GET /checkout	loading then idle.
Persist field changes	PUT /checkout?__experimental_calc_totals=true	updating then idle.
Place order	POST /checkout	processing then success or error.

If a payment result has a redirect URL, the checkout form redirects after the successful response.

Store API Session And Page Loads

Store API cart identity is held in the browser as a Cart-Token and Nonce, then sent as Store API request headers. A normal WordPress page request does not include those headers, so Woo's PHP cart can be empty while the browser still has a valid Store API cart session.

For OME-authored checkout pages, CheckoutRouteEntry keeps the configured checkout page renderable in that state. It only applies when the current request is the Woo checkout page and the page content contains OmeWooCheckoutProvider or OmeWooCheckoutForm. After the shell renders, the runtime sends GET /checkout with the saved Store API headers and hydrates the visible checkout from Woo's Store API response.

This does not add a custom endpoint, local storage fallback, or cookie bridge. Classic checkout pages keep Woo's native empty-cart redirect.

Native Hook Compatibility

These native Woo paths still apply:

Woo area	What can still happen
Add to cart	woocommerce_add_to_cart_validation can block mutation, cart item data can be injected, and add-to-cart actions can run.
Pricing	woocommerce_before_calculate_totals and woocommerce_cart_calculate_fees can change rendered totals.
Checkout	Store API checkout can update the order from the request, create the order, run payment processing, and reach an order-received flow.

Error Handling

Store API errors are converted into safe notices:

• Cart errors become cart notices with a source such as add-to-cart, quantity, remove, coupon, shipping, stock, or variation.
• Checkout errors become checkout notices and field error markers when Woo exposes field keys.
• Known Woo checkout error codes are mapped to field keys when Store API does not include data.params.
• Notice message text is normalized and rendered with text content, not injected as HTML.

Woo cart routes can return an error with a full authoritative cart under data.cart; native stale item-key conflicts use this shape with HTTP 409. The runtime captures fresh response nonce/cart-token headers first, commits that cart through the normal normalization/subscriber path, and still exposes the original safe error. It never issues a blind retry. Pending same-line work is cancelled or revalidated against the returned cart, and later independent operations can continue.

A transport failure has no authoritative cart. In that case the last confirmed shared cart remains unchanged, the owned control enters error, and the next operation still gets a clean turn in the FIFO lane.

Store API Extension Data

StoreApiExtension registers an ohmyetch namespace on the Store API cart endpoint when Woo Blocks APIs are available. It exposes capability metadata:

Capability	Meaning
cart_count	OME cart count components are supported for the response.
add_to_cart	OME add-to-cart components are supported for the response.

This metadata is read-only and does not replace Woo's native cart schema.