LLMs in WooCommerce break at checkout—guard idempotency first
The 2:17 a.m. checkout incident I didn’t see coming
It started as a “harmless” AI feature request: a Fortune 500 apparel brand wanted an LLM helper that could recommend shipping options and apply promo codes when the customer’s cart context looked compatible. The UI was WooCommerce, but the AI lived outside—an agent service we called from the checkout flow. Everything looked clean in staging.
Then production hit, and at 2:17 a.m. support lit up. Customers weren’t getting wrong totals by a little—they were seeing discounts applied twice, and in a few cases tax changed between the initial confirmation and the final order placement. Not randomly. Consistently around peak traffic, with one clear pattern: when customers refreshed the checkout page quickly (or mobile browsers retried requests), the LLM tool calls re-ran.
We traced it to a race at the boundary between “LLM decided something” and “WooCommerce persisted something.” The agent was generating a sequence of tool calls (fetch cart context → compute promo suitability → apply discount → re-calc tax). But the checkout request/response cycle wasn’t guaranteed to be single-shot. PHP workers, browser retries, and WooCommerce’s own steps meant we could execute the same logical “apply promo” twice—sometimes in the same second.
In the first 40 minutes after deploy, we saw a measurable failure rate: ~0.9% of checkouts triggered duplicated promo application, and about 0.3% had tax mismatches that required manual admin corrections. That’s not a rounding error—that’s reputational damage territory.
My take: stop treating LLM tool calls like pure suggestions
Conventional wisdom says, “Make the agent deterministic and write strict prompts.” I disagree. Prompts don’t fix an architectural property: if state-mutating actions are not idempotent, retries will duplicate them. The real reason this breaks in production is that checkout is inherently a distributed retry system dressed up as a single request.
An LLM tool call is not a chat message. If the tool applies a coupon, updates shipping, creates an order note, or changes tax context, then you must assume it can run more than once. The LLM’s “helpfulness” is irrelevant if you don’t constrain side effects with an idempotency boundary.
Failure mode #1: checkout race conditions (the retry you can’t see)
Here’s how the race manifested in our stack (WooCommerce + PHP + external agent):
- Browser requests checkout summary.
- Backend calls the agent to decide tool actions.
- Agent returns:
apply_coupon: PROMO10, thenrecalculate_tax. - User refreshes or the network retries the summary call.
- Same cart snapshot, same checkout session, agent runs again.
Without an idempotency key, both summary calls applied the coupon twice. WooCommerce didn’t know they were duplicates because from its perspective: two different HTTP requests, both valid. The LLM just “did what it was asked.”
The fix that actually worked
We implemented idempotency at the state-changing boundary, not inside the agent logic.
- Generate an idempotency key tied to checkout session + cart hash + intended action list (not just session ID).
- Store a result record in a fast shared store (Redis/Memcached; MySQL works but adds latency).
- Before applying any coupon/tax mutation, acquire a short lock (e.g.,
SETNXwith expiry) or check “already applied” for that idempotency key. - If it already ran, return the cached computed totals instead of re-applying discounts.
This reduced duplicate coupon incidents from 0.9% to effectively zero (<0.01% of checkouts saw any duplicate application, limited to lock expiry edge cases during deploy restarts).
Tradeoff: you need a stable definition of “same action.” Cart contents can change due to concurrency (inventory/quantity adjustments). So we hashed the cart line items + selected shipping method + customer tax region signal and included the intended tool action identifiers. If anything changed, it correctly became a new idempotency operation.
Failure mode #2: stale pricing/tax responses from “smart” caching
The second issue was subtler: tax and pricing responses were sometimes stale by the time the customer hit “Place order.”
We initially cached pricing/tax computation results to keep checkout latency under control. In a regulated beverage portfolio (think: age-restricted goods, jurisdictional tax rules, and shipping surcharges), that cache paid off—until it didn’t.
The stale behavior came from two places:
- LLM tool calls were cached at the agent layer even when upstream inputs changed (shipping address fields completed after the first UI step).
- WooCommerce pricing was recomputed in different hooks depending on the checkout phase, so the “same” cart at the UI level wasn’t the same at the calculation phase.
Result: customers saw one tax amount in the checkout summary and another on final order confirmation. Even if the final numbers were “correct,” the discrepancy increased support tickets because users don’t trust totals that move.
What I changed
We stopped caching tool results blindly and started caching computation plans with strict input versioning.
- Every cached pricing/tax computation includes a version stamp derived from: currency, tax class rules version, shipping method, and a normalized representation of the tax address.
- No cache reuse across “summary” and “place order” phases unless the inputs match exactly.
- We added a short TTL (seconds, not minutes) for anything tied to address completion.
Pragmatic number: we kept median checkout overhead under 120ms added latency from the AI call by caching within a single checkout session flow, not globally. That’s the sweet spot: local reuse, strict invalidation.
Tradeoff: more misses under churn, but fewer user-visible inconsistencies. I’d rather miss and be consistent than hit and be wrong.
Failure mode #3: “helpful” tool calls that mutate state without an idempotency boundary
This one shows up in every agent team I meet. The model is optimized to be helpful. So it proposes actions like “apply the best promo code” or “adjust shipping” even when the user didn’t explicitly authorize those changes at that step.
In our case, the agent returned a tool sequence that included:
- create a “promo suggestion” note
- apply coupon
- recalculate totals
But we treated notes and coupon applications as the same category of side effect—meaning the note could be duplicated harmlessly, while the coupon application could not. Without an idempotency boundary per mutation type, retries duplicated both, and only one of them caused monetary issues.
My rule now
Segment tool calls into two classes:
- Read-only tools (cart introspection, pricing quotes, tax estimates) must be safe to retry.
- Mutation tools (apply coupon, modify order meta used for totals, change shipping selection) must be idempotent and keyed.
And if you can’t guarantee idempotency for a mutation tool, don’t let the agent run it during checkout. Queue it for a follow-up step after order placement, or require explicit user confirmation.
How this shows up in headless WP + WooCommerce + Laravel too
Even if you’re not calling the agent directly from WooCommerce PHP, the pattern persists:
- Headless WordPress feeds content and cart rules; your agent might ingest rule context from your WP API.
- Laravel might orchestrate the agent (common in our applied-AI stack), but the mutation still lands in WooCommerce or an order service.
- If your orchestration retries (queue workers, circuit breakers, upstream timeouts), state mutation duplicates unless you enforce idempotency at the target system boundary.
We’ve seen teams “fix it” by making the agent deterministic—only to hit a new failure when a queue job retries. Determinism doesn’t help if you re-run the same mutation job without an idempotency key.
Checklist I wish we’d written before shipping
- Idempotency key per mutation tool: coupon application, tax-affecting changes, shipping method changes. Not one generic key for the whole session.
- Cache with versioned inputs: address completion, tax region, shipping selection, and pricing-rule versions.
- Do not cache across checkout phases: summary vs place order must not reuse cached computed totals unless inputs match exactly.
- Separate read vs mutation tool contracts: mutation tools must accept idempotency tokens.
- Cap agent-side retries: treat the agent as a stateless planner; retries belong to your orchestration layer with deterministic idempotency behavior.
After implementing those boundaries, we recovered engineering time quickly: the support queue dropped, and in a follow-up deploy window we cut manual checkout corrections to near-zero. The most honest metric I can give: we spent hours—not days—debugging the incident because the failure mode was cleanly bounded. That’s what good idempotency design does: it shortens your blast radius.
One sentence for Monday morning
LLMs can be smart, but your checkout will still break unless every state-mutating tool call is idempotent and every cached pricing/tax result is versioned to the exact calculation inputs.
At Champlin Enterprises, we treat agent calls like distributed system operations: deterministic boundaries, strict side-effect controls, and production-oriented caching rules—because our work on WooCommerce modernization and our AI Showcase/MVPs are built to survive retries, not just demos.