WooCommerce 11.1 lets Store API clients submit expected_total as an integer. When the server total differs, checkout can return a 409 conflict. The mismatch may be legitimate after tax, shipping, coupon, stock, currency, fee, or session changes. A client that blindly resubmits can create duplicate payment attempts or hide a material price change from the customer.
Use this for block checkout, headless storefronts, mobile apps, custom Store API clients, and payment integrations adopting expected_total in WooCommerce 11.1.
Quick answer
Calculate expected_total from the final cart response using the Store API minor-unit contract, bind it to the cart token and checkout idempotency key, and submit once. On 409, stop payment progression, fetch the current cart, compare line, shipping, tax, fee, discount, and currency changes, then show the customer the new total. Resubmit only after explicit confirmation with a fresh expected total and the same logical checkout identity.
What to check first
- Record currency minor units, cart token, customer session, shipping package, coupon state, tax location, expected_total, and server total.
- Test price, stock, coupon, shipping, tax, fee, currency, and session changes between cart review and checkout submit.
- Verify that a 409 occurs before capture, authorization, order creation, inventory mutation, or irreversible email.
- Use one logical checkout idempotency key across the conflict and customer-confirmed retry.
- Explain the exact total change and preserve accessibility focus when the checkout refreshes.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Normalize expected_total with the currency minor-unit contract at the final cart boundary. | Record currency minor units, cart token, customer session, shipping package, coupon state, tax location, expected_total, and server total. | Matching totals create exactly one order and payment attempt. |
| Stop payment and order side effects when the Store API returns 409. | Test price, stock, coupon, shipping, tax, fee, currency, and session changes between cart review and checkout submit. | Every mismatch returns before irreversible checkout side effects. |
| Fetch and diff the authoritative cart by component, not total alone. | Verify that a 409 occurs before capture, authorization, order creation, inventory mutation, or irreversible email. | The refreshed cart identifies the component and amount that changed. |
| Ask the customer to confirm the changed amount with accessible focus and copy. | Use one logical checkout idempotency key across the conflict and customer-confirmed retry. | Double clicks, network retries, and customer-confirmed retries remain idempotent. |
Why this usually happens
- The browser total can become stale while server-side pricing remains authoritative.
- Minor-unit conversion can be wrong for zero-decimal or three-decimal currencies.
- Shipping and tax recalculation can happen after the last visible cart response.
- Payment retries and checkout retries are often implemented as one action even though they have different safety rules.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
checkout_request:
cart_token: cart_8f31
idempotency_key: checkout_0199
currency: USD
expected_total: 12900
conflict_response:
http: 409
server_total: 13400
changed_component: shipping
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| No change | Expected total equals server | One order and payment |
| Tax changed | Address update | 409 before payment |
| Stock or price changed | Catalog mutation | Refresh and explain |
| Retry race | Double click plus 409 | One logical checkout |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Normalize expected_total with the currency minor-unit contract at the final cart boundary.
- Stop payment and order side effects when the Store API returns 409.
- Fetch and diff the authoritative cart by component, not total alone.
- Ask the customer to confirm the changed amount with accessible focus and copy.
- Retry with the updated total and one logical checkout idempotency key.
Decision rule
Retry checkout only after the current authoritative cart is displayed and confirmed, and only when evidence proves the original conflict produced no charge, order, inventory, or email side effect.
Production verification checklist
- Matching totals create exactly one order and payment attempt.
- Every mismatch returns before irreversible checkout side effects.
- The refreshed cart identifies the component and amount that changed.
- Double clicks, network retries, and customer-confirmed retries remain idempotent.
Field notes
- Use synthetic IDs and examples that can be traced from the first request to the final record.
- Keep a before and after result for every changed setting or deployed version.
- Review the evidence again after caches, queues, and scheduled work have had time to settle.
Questions teams ask during testing
Can this be tested on production?
Use production for read-only confirmation and one narrow synthetic fixture that cannot charge a card, email a real customer, expose personal data, or alter inventory. Run upgrades, schema changes, cache changes, and destructive repairs on staging first.
What evidence should the report keep?
Keep exact versions, UTC timestamps, stable synthetic IDs, expected and actual results, the decision owner, rollback point, and final verification. Redact credentials, tokens, customer data, addresses, and private infrastructure details.
When is the task complete?
Complete it when the primary user path passes, downstream records reconcile, failure branches are understood, monitoring is active, and an established owner page links to the new guide in context.
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, stable fixture IDs, settings, and a reproducible baseline.
- Treating one successful screen as proof that APIs, caches, jobs, roles, reports, and downstream records agree.
- Testing only an administrator session instead of the devices, roles, networks, data states, and failure branches customers use.
- Closing the task without a named owner, rollback point, observation window, and contextual incoming link from an established guide.
What to tell the client or owner
Give the site owner the affected versions, exact synthetic fixture, UTC timeline, before and after evidence, cause class, decision, rollback point, unresolved risks, and next review date. State which measurements prove success and which observation window remains open.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, debug a WooCommerce Store API checkout.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references