System of record
Name the system allowed to decide each business fact.
Evidence to keep: Ownership matrix for product, price, stock, customer, order, return, and payment state.
OPEN TEST LIBRARY
Commerce Integration Failure Atlas
Forty reproducible failure patterns for orders, pricing, inventory, customers, catalog, payments, returns, recovery, and access control.
Direct answer
Commerce integration failures usually come from weak control of retries, event order, state ownership, units, permissions, or reconciliation. This atlas provides 40 reproducible synthetic tests, maps key controls to official technical documentation, and defines a minimum telemetry contract for tracing each business effect across systems.
Broken event → controlled replay
Commerce
ERP
PIM
OMS / WMS
CRM
Payments
Tax
Shipping
Atlas coverage
What is included
A successful API response does not prove that the business operation is correct. A retry can duplicate an order. A valid price can belong to the wrong account. Inventory can be correct in one system and stale in another. A queue can recover while the customer, warehouse, or finance state remains wrong.
The Commerce Integration Failure Atlas turns those failure mechanics into reusable tests. It is for architects, engineers, QA teams, support teams, platform owners, and vendors who need evidence beyond a happy-path API call.
Evidence disclosure
All 40 records remain Evidence Class D: reproducible synthetic fixtures. Official sources support the documented control behavior, such as duplicate webhook delivery, event-order uncertainty, idempotent retries, bounded retries, compensation, trace correlation, least privilege, and callback validation. They do not prove a vendor defect, client incident, breach, or incident frequency.
For a broader view of the systems and data flows involved, see Elogic Commerce ecommerce integration services and systems integration services.
Operational workflow
How to use the atlas
- 1Choose the records that match a real data flow in your stack.
- 2Map each record to the system of record, message path, owner, and business control.
- 3Convert the Given-When-Then logic into automated contract, integration, or end-to-end tests.
- 4Inject the failure in a non-production environment. Do not test destructive scenarios against live customer data.
- 5Confirm the technical result and the business result. A queue can recover while the order is still wrong.
- 6Add the test to release gates and the operational runbook.
- 7Retest after platform, ERP, PIM, OMS, payment, tax, extension, or API changes.
Use the Commerce Platform Upgrade Risk Tracker to connect these tests to version and dependency changes. Use an ecommerce architecture audit when the system of record, ownership, or failure boundary is not clear.
Control framework
Ten controls that prevent many integration failures
Idempotency
The same request can be repeated without creating a second business action.
Evidence to keep: Stable idempotency key, stored result, expiry rule, and conflict behavior.
Event identity
Every event has a unique ID and source.
Evidence to keep: Event ID, source, type, entity ID, created time, schema version.
Ordering and version
New state cannot be replaced by an older event.
Evidence to keep: Entity version, sequence number, timestamp policy, and stale-event rule.
Bounded retries
Temporary failures are retried with delay, limits, and jitter.
Evidence to keep: Retry policy by error class and final dead-letter path.
Dead-letter handling
Failed messages remain visible and recoverable.
Evidence to keep: Queue depth alert, owner, replay tool, and reason code.
Reconciliation
Systems are compared even when no error is visible.
Evidence to keep: Scheduled totals, row-level differences, repair workflow, and audit trail.
Correlation ID
One business flow can be traced across every system.
Evidence to keep: Correlation ID in logs, messages, API calls, and support tooling.
Least privilege
An integration can access only the data and actions it needs.
Evidence to keep: Scoped account, environment separation, token rotation, and access review.
Replay safety
A recovery action cannot repeat an unsafe side effect.
Evidence to keep: Dry-run mode, effect ledger, approval, rate limit, and compensation path.
Evidence policy
Evidence classes
The atlas separates reproducible synthetic fixtures from official behavior, public incidents, anonymized incidents, and unverified reports.
Official vendor advisory, defect note, or documented behavior.
Link the exact official source and version.
Public incident report or technical postmortem.
Preserve context and do not generalize beyond the report.
Anonymized operational incident with explicit publication rights.
Legal and client approval required. Remove re-identification risk.
Reproducible synthetic fixture based on a defined failure mechanic.
Label as synthetic. Publish inputs, expected result, and limitation.
Unverified community report or anecdote.
Use only as a research lead. Do not publish as a confirmed failure record.
Official control sources
Evidence-to-test map
The map below shows which test mechanics are backed by official documentation. The fixture remains synthetic. The source supports the control or delivery behavior, not a claim that a named vendor caused an incident.
| Officially documented behavior | Related records | Required control |
|---|---|---|
| Webhook delivery can be duplicated or arrive out of order. | CIF-001, CIF-006, CIF-027 | Store event IDs; deduplicate; verify signatures; fetch missing state; do not depend on arrival order. |
| Shopify does not guarantee webhook order or delivery. | CIF-001, CIF-006, CIF-033 | Process asynchronously, make handlers idempotent, and run reconciliation jobs. |
| Idempotency keys make retries safe for supported POST operations. | CIF-001, CIF-005, CIF-026, CIF-029, CIF-036 | Use a stable business key, store the first result, and reject key reuse with different parameters. |
| AWS recommends idempotent API design for retry safety. | CIF-001, CIF-005, CIF-034, CIF-036 | Make client intent explicit and return the original outcome on a repeated request. |
| Azure separates transient retry from compensating actions. | CIF-002, CIF-003, CIF-015, CIF-029, CIF-031, CIF-036 | Bound retries, record completed steps, and make compensation resumable and idempotent. |
| OpenTelemetry correlates logs with TraceId and SpanId. | CIF-035 | Propagate trace context and add business identifiers without logging secrets or unnecessary personal data. |
| NIST defines least privilege as minimum necessary access. | CIF-037, CIF-039 | Use scoped service accounts, environment separation, rotation, and periodic access review. |
| OWASP includes object authorization, unsafe API consumption, and SSRF in its API risk list. | CIF-037, CIF-039, CIF-040 | Authorize every object, validate external destinations, restrict egress, and maintain an API inventory. |
Observability contract
Minimum telemetry contract
A support team should be able to answer: what happened, where, to which business object, how many times, with which result, and whether the business effect was repaired. Use these fields consistently across API logs, queues, jobs, and reconciliation output.
| Field group | Minimum fields | Why it matters |
|---|---|---|
| Identity |
event_id; correlation_id or trace_id; span_id | Connect one delivery and one end-to-end business flow. |
| Intent |
idempotency_key; operation; schema_version | Show what the sender intended and whether a retry is the same action. |
| Route |
source_system; target_system; environment | Locate the handoff and prevent production/non-production confusion. |
| Business object |
entity_type; entity_id; source_version | Tie technical events to the order, SKU, customer, payment, or return. |
| Time |
occurred_at; observed_at; processed_at | Separate event time from receipt and processing time. |
| Retry state |
attempt_count; next_retry_at; dead_letter_reason | Detect loops, exhausted retries, and silent queues. |
| Integrity |
payload_hash; amount; currency; unit; quantity | Compare meaning without copying a sensitive payload into every log. |
| Outcome |
status; error_code; business_effect; compensation_state | Show both the technical result and the real commerce result. |
| Ownership |
service_owner; runbook_id; incident_id | Make the recovery path explicit and auditable. |
Logging boundary
Do not log credentials, payment data, session tokens, private customer content, or full payloads by default. Use hashes, stable IDs, redaction, retention limits, and access controls. A trace is useful only when it does not create a second security problem.
Open test library
The 40 failure records
Each record uses the same public structure. “Severity” describes the possible business impact when the pattern reaches a critical flow. It is not a measured probability or a score for any platform.
CIF-001 to CIF-006
Orders and fulfillment
Duplicate, lost, stale, or overwritten order and shipment state.
CIF-001 Duplicate order after webhook retry Critical
Visible symptom
One customer checkout creates two downstream orders or two fulfillment requests.
Why it happens
The receiver creates the order before it records the event or idempotency key. The sender retries after a timeout, and the second delivery creates the same business action again.
Detection signal
Search for one commerce order ID mapped to more than one downstream order ID. Alert on repeated event IDs and repeated idempotency keys with different results.
Preventive control
Store the event ID or business idempotency key before the side effect. Return the original result for a safe repeat. Keep a unique constraint on the source order ID.
Given / When / Then
Given one valid order-created event, when the identical event is delivered twice and the first response is delayed, then only one downstream order exists and both deliveries return the same mapped order ID.
CIF-002 Order lost after a partial failure Critical
Visible symptom
The customer receives an order number, but the ERP never receives the order and no visible error remains.
Why it happens
The integration marks the message complete before the downstream write is durable, or it writes one part of the order and fails before the completion state is recorded.
Detection signal
Reconcile commerce orders against ERP orders by source order ID. Alert when a confirmed commerce order has no downstream mapping after the agreed time window.
Preventive control
Use transactional outbox or equivalent durable handoff. Acknowledge the message only after the downstream result and mapping are stored. Add scheduled reconciliation.
Given / When / Then
Given a confirmed order, when the ERP call succeeds but the integration process stops before acknowledgement, then a retry restores the same mapping without losing or duplicating the order.
CIF-003 Cancelled order ships because of a race condition Critical
Visible symptom
An order is cancelled in commerce but still reaches pick, pack, or shipment in the fulfillment system.
Why it happens
The create-order and cancel-order events travel on different paths or arrive out of order. The fulfillment system accepts the earlier state after the cancellation is already final.
Detection signal
Find shipments created after a final cancellation timestamp. Track state transitions that move from cancelled back to open or allocated.
Preventive control
Use entity versions or sequence numbers. Reject stale transitions. Define which system owns final fulfillment state and use a cancellation acknowledgement before promising success to the customer.
Given / When / Then
Given order version 8 is cancelled, when an older version 7 allocation event arrives later, then the OMS rejects the stale event and no shipment is created.
CIF-004 Split shipment overwrites the full order status High
Visible symptom
The first partial shipment marks the whole order as shipped, or the second shipment resets tracking from the first parcel.
Why it happens
The receiver treats a line-level or shipment-level event as an order-level replacement. It does not merge shipment state by shipment ID and order line.
Detection signal
Compare shipped quantities by line with the order-level status. Alert when order status is complete while open quantity remains.
Preventive control
Model shipments as separate entities. Merge by shipment ID, line ID, and quantity. Derive order status from all shipment states instead of copying one event status.
Given / When / Then
Given an order with two lines and two shipments, when only the first shipment is confirmed, then one line is shipped, the other remains open, and both tracking records remain available.
CIF-005 Duplicate shipment after fulfillment replay Critical
Visible symptom
A recovery replay creates a second carrier label, tracking number, or shipment for an order that already shipped.
Why it happens
The replay tool resends a command without checking the effect ledger. The carrier endpoint accepts the repeated label request as a new action.
Detection signal
Find multiple active labels for the same shipment intent. Compare replay logs with carrier label creation times.
Preventive control
Use a stable shipment idempotency key. Store the carrier result. Make replay default to dry-run and require approval for commands that create external effects.
Given / When / Then
Given a shipment already has a carrier label, when its create-label command is replayed, then the existing label is returned and no second billable label is created.
CIF-006 Old order status restored by an out-of-order event High
Visible symptom
An order moves from shipped or cancelled back to processing after delayed integration traffic.
Why it happens
The receiver applies events by arrival time and does not compare entity version, sequence, or allowed state transition.
Detection signal
Alert on backward state transitions and events whose source version is below the stored version.
Preventive control
Use a monotonic version or sequence per order. Validate transitions against a state machine. Quarantine stale or impossible events for review.
Given / When / Then
Given stored order version 12 is shipped, when version 10 with status processing arrives, then the event is rejected, logged as stale, and the order remains shipped.
CIF-007 to CIF-011
Pricing and promotions
Correct data applied to the wrong customer, currency, tax mode, rule, or unit.
CIF-007 Stale contract price cache Critical
Visible symptom
A B2B buyer sees or orders at an old contract price after the ERP price has changed.
Why it happens
Price cache entries do not include account, contract, currency, unit, or effective date, or invalidation fails after a source update.
Detection signal
Compare quoted and ordered price with the authoritative price response for the same account, SKU, unit, currency, and time.
Preventive control
Use a complete cache key, short and explicit expiry, event-based invalidation, and a final server-side price check before order acceptance.
Given / When / Then
Given a buyer contract price changes from 100 to 92, when the invalidation event is delayed, then checkout revalidates against the pricing source and does not accept the stale price.
CIF-008 Currency conversion mismatch High
Visible symptom
The storefront total, authorized amount, and ERP order value differ by rounding or exchange-rate timing.
Why it happens
Systems use different rates, decimal precision, rounding modes, or conversion timestamps. One system converts line values while another converts the final total.
Detection signal
Reconcile line, tax, discount, shipping, and grand total in both source and settlement currencies. Keep the rate and rounding method used.
Preventive control
Define one conversion owner and one rounding policy. Send the source amount, target amount, rate, timestamp, and precision with the order.
Given / When / Then
Given a three-line order in EUR settled in USD, when the same rate and half-up rounding are applied, then line totals, tax, grand total, authorization, and ERP value reconcile to the defined tolerance.
CIF-009 Tax-inclusive and tax-exclusive price mix Critical
Visible symptom
Tax is added twice, removed twice, or displayed differently from the final charge.
Why it happens
A price field is sent without a tax-basis flag, or the receiving system assumes the opposite basis for the market or customer type.
Detection signal
Compare the stored net, tax, and gross values against the configured market rule. Alert when gross is not equal to net plus tax within tolerance.
Preventive control
Include tax basis, jurisdiction, rate source, and currency in the price contract. Keep display calculation separate from final tax calculation.
Given / When / Then
Given a gross price of 120 with 20% VAT, when the record enters a tax-exclusive market flow, then the system derives 100 net and 20 tax once, not twice.
CIF-010 Promotion precedence conflict High
Visible symptom
A coupon, contract price, tier price, bundle rule, and free-shipping rule combine in an unintended order.
Why it happens
The systems use different rule priority, exclusivity, or stacking logic. The integration sends only the final value without the applied-rule ledger.
Detection signal
Store and compare the ordered list of applied rule IDs, base price, adjustments, and final price. Test rule pairs and boundary dates.
Preventive control
Define precedence centrally. Send rule IDs and adjustment reasons. Make mutually exclusive rules explicit and reject unknown combinations.
Given / When / Then
Given a contract price and a non-stackable campaign coupon, when both conditions match, then the contract rule wins, the coupon is rejected with a reason, and the final price is identical in commerce and ERP.
CIF-011 Unit-of-measure price mismatch Critical
Visible symptom
A case, pack, meter, kilogram, or each price is shown or ordered as if it used another unit.
Why it happens
The integration maps a numeric price but loses the sales unit, base unit, conversion factor, or minimum order quantity.
Detection signal
Compare price per sales unit and price per base unit. Alert when the unit is missing or the conversion factor is zero, negative, or changed without review.
Preventive control
Treat unit of measure as part of the price identity. Store conversion factors with effective dates. Validate quantity multiples at cart and order creation.
Given / When / Then
Given one case contains 12 each and the case price is 120, when a buyer orders two cases, then quantity is 24 each for inventory and total price is 240, not 20 or 2,880.
CIF-012 to CIF-016
Inventory and availability
Oversell, wrong source allocation, stale reservations, and unit mismatch.
CIF-012 Oversell caused by inventory lag Critical
Visible symptom
The storefront accepts more units than can be fulfilled during fast sales or concurrent orders.
Why it happens
Availability is copied on a schedule and no reservation or final availability check protects the gap between display and order acceptance.
Detection signal
Track negative available-to-promise, cancellation for no stock, and the age of the last inventory update by SKU and source.
Preventive control
Separate on-hand, reserved, safety stock, and available-to-promise. Use reservations or an authoritative check for scarce items. Reduce cache age during peaks.
Given / When / Then
Given one unit is available, when two checkouts confirm at the same time, then only one reservation succeeds and the second buyer receives a controlled out-of-stock result.
CIF-013 Multi-source allocation mismatch High
Visible symptom
The storefront promises stock that exists globally but cannot be allocated to the buyer’s location, service level, or legal entity.
Why it happens
Commerce aggregates inventory across sources while the OMS applies routing, region, hazmat, carrier, or warehouse rules that were not included in availability.
Detection signal
Compare promised source with final allocated source. Track orders that change warehouse, split unexpectedly, or fail allocation after checkout.
Preventive control
Use source-aware availability or an OMS availability service. Include location, channel, service level, and restrictions in the availability request.
Given / When / Then
Given stock exists only in a warehouse that cannot serve the buyer’s region, when availability is requested for that address, then the item is not promised from that source.
CIF-014 Backorder state lost between systems High
Visible symptom
An item allowed for backorder becomes unavailable, or an unavailable item is promised without an expected date.
Why it happens
The integration sends quantity but not backorder policy, expected receipt, promise date, channel rule, or customer eligibility.
Detection signal
Compare quantity, sellable state, backorder flag, and promise date. Alert when backorder is true without a date or policy source.
Preventive control
Define an availability contract with quantity, state, reason, expected date, and policy version. Treat backorder as a business state, not a negative number.
Given / When / Then
Given zero on-hand and backorder allowed for a specific account with a 14-day promise, when the buyer opens the product, then the item is orderable with the correct promise and the state persists into the order.
CIF-015 Reservation not released after payment failure Critical
Visible symptom
Sellable stock remains blocked after payment decline, timeout, or abandoned checkout.
Why it happens
Reservation creation is durable, but release depends on a callback that can be lost or on a session timeout that is not reconciled.
Detection signal
Find reservations past their expiry with no paid order. Compare reserved quantity with active payment or order state.
Preventive control
Use explicit reservation expiry, idempotent release, and scheduled cleanup. Link reservation, cart, payment intent, and order with one correlation ID.
Given / When / Then
Given stock is reserved for a payment attempt, when the payment fails and the callback is lost, then expiry reconciliation releases the reservation once and returns availability.
CIF-016 Inventory unit-of-measure mismatch Critical
Visible symptom
The storefront shows 120 units when the warehouse has 10 cases of 12, or subtracts one case for an order of one each.
Why it happens
Quantity is transferred without base unit, sales unit, conversion factor, or packaging hierarchy.
Detection signal
Validate quantity and unit together. Compare calculated base quantity with source on-hand and order decrements.
Preventive control
Use a unit-aware inventory contract. Convert only through versioned master data. Reject quantity records with unknown units.
Given / When / Then
Given inventory is 10 cases and one case is 12 each, when the storefront sells each units, then availability is 120 each and an order of 5 each leaves 115 each.
CIF-017 to CIF-020
Customer and B2B accounts
Duplicate identity, account hierarchy drift, permission lag, and credit lag.
CIF-017 Duplicate customer identities High
Visible symptom
One buyer has multiple customer IDs, order histories, price groups, or consent records.
Why it happens
Each system creates a record before a shared identity or match decision exists. Email is used as a universal key even when accounts, regions, or legal entities differ.
Detection signal
Find multiple active identities with the same verified contact, external ID, tax ID, or account relationship. Track merge and split events.
Preventive control
Define a master identity and immutable cross-system IDs. Use deterministic match rules plus a reviewed exception queue. Never merge only because names look similar.
Given / When / Then
Given an existing verified customer with CRM ID C-42, when the same person registers through another storefront, then the new login links to C-42 or enters review instead of creating an uncontrolled duplicate.
CIF-018 Parent-child account hierarchy drift Critical
Visible symptom
A buyer sees the wrong branches, contracts, invoices, addresses, or approval limits.
Why it happens
The hierarchy update is partial, arrives out of order, or replaces only one side of the parent-child relationship.
Detection signal
Validate that every child has one valid parent for the effective period. Compare account tree versions across systems.
Preventive control
Transfer hierarchy as versioned relationships with effective dates. Apply the full change atomically or use a staged graph validation before activation.
Given / When / Then
Given branch B moves from parent A to parent C at midnight, when the new hierarchy activates, then B loses A permissions, gains C permissions, and no interval grants both.
CIF-019 Buyer role permission lag Critical
Visible symptom
A removed buyer can still place orders, view prices, approve quotes, or access another role’s data.
Why it happens
Role changes use a long cache or session token and no revocation event reaches the storefront.
Detection signal
Compare token claims and session age with the current role version. Alert on privileged actions from a revoked or stale role.
Preventive control
Use short-lived authorization claims for sensitive actions, a role version, revocation, and server-side authorization at the action boundary.
Given / When / Then
Given a buyer’s approval role is removed, when the existing session attempts to approve an order, then the server checks the new role version and denies the action.
CIF-020 Credit status lag Critical
Visible symptom
An account on credit hold places a net-terms order, or an approved account is blocked after the hold is cleared.
Why it happens
Credit state is cached without effective time, or the order checks only the value shown when the cart was created.
Detection signal
Compare order acceptance time with the authoritative credit status and version. Track manual release of orders blocked or accepted incorrectly.
Preventive control
Perform a final credit check at order submission. Include account, legal entity, currency, exposure, limit, status, version, and effective time.
Given / When / Then
Given an account moves to credit hold after cart creation, when the buyer submits the order, then the final check blocks net terms and records the current reason.
CIF-021 to CIF-025
Catalog and product data
Mapping collisions, missing locale fallback, schema drift, partial media, and broken taxonomy.
CIF-021 Variant mapping collision Critical
Visible symptom
Two source variants map to one commerce SKU, or one variant overwrites another size, color, or configuration.
Why it happens
The target key is built from a non-unique field, normalized values collide, or the mapping ignores market and product family.
Detection signal
Enforce uniqueness on source system plus source ID. Report any target SKU receiving more than one active source record.
Preventive control
Use immutable source identifiers and a mapping table. Validate uniqueness before publish. Never derive identity only from display labels.
Given / When / Then
Given two variants share the label “Blue” but have different source IDs, when both are imported, then they remain distinct and no product data is overwritten.
CIF-022 Missing locale fallback Medium
Visible symptom
A product page shows blank content, the wrong language, or an unpublished source value in one store view.
Why it happens
The integration treats a missing translation as an empty overwrite instead of applying the defined fallback or publication rule.
Detection signal
Scan required attributes by locale before publish. Track empty values that replace non-empty target content.
Preventive control
Define fallback by field and market. Distinguish missing, intentionally blank, and inherited values. Block publication when regulated or required content is absent.
Given / When / Then
Given the French short description is missing and fallback to English is allowed, when the product publishes in France, then the approved English value appears and the missing translation is logged.
CIF-023 Catalog attribute type drift High
Visible symptom
A number becomes text, a multi-select becomes one value, or a date and unit can no longer be filtered or validated.
Why it happens
The source schema changes without a versioned contract, or the receiver accepts a new type and silently coerces it.
Detection signal
Validate every payload against the expected schema and unit. Alert on type coercion, unknown enum, and precision loss.
Preventive control
Version schemas. Use contract tests and explicit migration for type changes. Quarantine invalid records instead of publishing partial data.
Given / When / Then
Given `weight_kg` is numeric, when the source sends “heavy”, then the record is rejected with a schema error and the last valid product remains active.
CIF-024 Partial media synchronization High
Visible symptom
A product publishes before its primary image, video, document, alt text, or CDN derivative is available.
Why it happens
The product and media pipelines commit separately, and the page becomes visible after only the product record succeeds.
Detection signal
Validate required media references and HTTP availability before activation. Track orphan assets and broken derivatives.
Preventive control
Use staged publication. Activate the product only after required assets and metadata pass checks, or keep a deliberate approved placeholder.
Given / When / Then
Given a product requires one primary image and a safety PDF, when the PDF upload fails, then the product stays staged and does not publish with incomplete required media.
CIF-025 Invalid category graph High
Visible symptom
Navigation loops, duplicate paths, orphan categories, or products disappear because the category tree is invalid.
Why it happens
A parent reference points to a descendant, a deleted parent remains in use, or partial updates apply before graph validation.
Detection signal
Run cycle detection, orphan checks, unique path checks, and maximum-depth checks before activation.
Preventive control
Build and validate the full graph in staging. Activate a version only when the graph is acyclic and all required references resolve.
Given / When / Then
Given category A contains B and an update sets A’s parent to B, when the new graph is validated, then activation is blocked and the live tree remains unchanged.
CIF-026 to CIF-029
Payments, tax, and fraud
Authorization, capture, webhook, tax, and refund reconciliation errors.
CIF-026 Payment authorization and capture mismatch Critical
Visible symptom
The order is captured twice, captured for the wrong amount, or marked paid when only authorization exists.
Why it happens
Authorization, capture, void, and refund are flattened into one paid flag, or retries use different business keys.
Detection signal
Maintain a payment transaction ledger. Reconcile authorized, captured, voided, refunded, and disputed amounts by payment intent and order.
Preventive control
Model each payment operation separately. Use gateway idempotency keys, amount checks, and allowed state transitions.
Given / When / Then
Given an order has one authorization for 100, when capture is requested twice with the same key, then one capture of 100 exists and the second call returns the original result.
CIF-027 Unverified or replayed payment webhook Critical
Visible symptom
A forged or repeated callback marks an order paid, changes payment state, or triggers fulfillment.
Why it happens
The receiver does not verify the signature, timestamp, source, event ID, or current transaction state.
Detection signal
Log signature result, event ID, source IP only as supporting data, event age, and state transition. Alert on invalid signatures and repeated events.
Preventive control
Verify the provider signature against the raw body. Enforce replay window and event uniqueness. Fetch authoritative payment state before high-risk actions when supported.
Given / When / Then
Given a valid captured-payment payload, when the signature is invalid or the timestamp is outside the replay window, then the event is rejected and order state does not change.
CIF-028 Tax jurisdiction mismatch Critical
Visible symptom
The tax shown or charged uses the wrong destination, product code, exemption, registration, or legal entity.
Why it happens
Address normalization, nexus, customer exemption, product tax code, or legal entity differs between quote and final order systems.
Detection signal
Store the tax request and response basis: normalized address, product code, exemption ID, jurisdiction, rate, and calculation version.
Preventive control
Use one final tax calculation owner. Recalculate after address, shipping, item, or exemption changes. Send the tax basis with the order.
Given / When / Then
Given an exempt B2B account with a valid certificate, when the final order is submitted, then the tax service receives the exemption and the ERP stores the same zero-tax basis.
CIF-029 Refund reconciliation failure Critical
Visible symptom
The customer receives a refund, but the ERP credit memo, order balance, tax, or financial ledger does not match.
Why it happens
Each system records a different refund identifier, amount basis, currency, line allocation, or completion state.
Detection signal
Reconcile refund ID, payment transaction, order, currency, line amounts, shipping, tax, and total. Alert on completed gateway refunds without ERP credit.
Preventive control
Use one refund intent ID across systems. Record requested, accepted, completed, failed, and reversed states. Retry accounting effects safely and compensate when needed.
Given / When / Then
Given a partial refund of one line plus tax, when the gateway completes the refund and the ERP call times out, then replay creates one credit memo for the exact amount and no second gateway refund.
CIF-030 to CIF-032
Returns and refunds
RMA state, refund, stock, SKU, and unit divergence.
CIF-030 RMA status divergence High
Visible symptom
The customer sees approved while the warehouse sees pending, or a closed return reopens after a delayed update.
Why it happens
Systems use different state names and allowed transitions, and the mapping has no version or transition guard.
Detection signal
Map each source state to one canonical state. Alert on impossible transitions and status age beyond the service target.
Preventive control
Use a canonical return state machine and versioned mappings. Keep source state and canonical state together for audit.
Given / When / Then
Given an RMA is closed at version 9, when a delayed version 7 “received” event arrives, then it is quarantined and the return remains closed.
CIF-031 Refund completed without inventory adjustment Critical
Visible symptom
Money is returned, but sellable, damaged, quarantine, or scrap inventory is not updated.
Why it happens
Refund and physical return are treated as one event even when goods are not received, inspected, or restockable.
Detection signal
Compare refund completion with return receipt, disposition, and inventory movement. Flag financial completion without an expected physical-state record.
Preventive control
Separate financial refund from physical return and disposition. Use explicit states for not received, received, restock, refurbish, quarantine, and scrap.
Given / When / Then
Given a refund is issued before goods arrive, when the refund completes, then inventory does not increase until the warehouse records a restockable receipt.
CIF-032 Return line mapped to the wrong SKU or unit Critical
Visible symptom
The warehouse credits or restocks the wrong variant, pack size, or unit.
Why it happens
The return uses display SKU, parent SKU, or order-line position instead of the immutable order-line ID and sold unit.
Detection signal
Compare return line with original order-line ID, variant ID, sold unit, lot/serial where relevant, and quantity.
Preventive control
Create returns from immutable order-line references. Preserve sold unit and conversion factor. Reject returns that cannot resolve to the original line.
Given / When / Then
Given an order line contains two cases of SKU X with 12 each per case, when one case is returned, then the return records one case and 12 base units against the original line.
CIF-033 to CIF-036
Observability and recovery
Silent queues, retry storms, missing trace context, and unsafe replay.
CIF-033 Silent dead-letter queue Critical
Visible symptom
Messages fail and accumulate, but customers and operations notice the problem before engineering receives an alert.
Why it happens
The dead-letter queue exists but has no owner, age metric, business context, or alert threshold.
Detection signal
Monitor count, oldest age, failure reason, entity type, and business value. Alert on both sudden spikes and any critical message beyond its service target.
Preventive control
Assign an owner and runbook. Include correlation ID and safe replay data. Keep a dashboard and a scheduled review even when the count is zero.
Given / When / Then
Given a critical order message exhausts retries, when it enters the dead-letter queue, then an alert includes order ID, reason, age, owner, and a safe replay path.
CIF-034 Unbounded retry loop Critical
Visible symptom
A dependency outage creates a retry storm, duplicate traffic, rising cost, or wider platform failure.
Why it happens
Every error is treated as temporary. Retries have no limit, delay, jitter, circuit breaker, or idempotency control.
Detection signal
Track attempts per operation, retry rate, repeated error class, downstream saturation, and time spent retrying.
Preventive control
Classify errors. Use exponential backoff with jitter, attempt and time limits, circuit breaking, and dead-letter handling. Make side effects idempotent.
Given / When / Then
Given the ERP returns a temporary 503, when the call fails repeatedly, then retries follow the bounded schedule, stop at the limit, open the circuit, and preserve one recoverable message.
CIF-035 Missing correlation ID across systems High
Visible symptom
Support cannot trace one order, payment, or product update across logs, queues, and vendor systems.
Why it happens
Each service generates its own request ID and drops the business correlation when making the next call.
Detection signal
Sample critical flows and verify the same correlation ID appears in logs, message headers, API calls, error records, and support views.
Preventive control
Create a correlation ID at the business-flow boundary. Propagate it without using personal data. Keep local request IDs as separate fields.
Given / When / Then
Given one checkout creates an order, payment, ERP order, and shipment request, when the flow completes, then all systems can be queried with the same correlation ID.
CIF-036 Unsafe replay repeats side effects Critical
Visible symptom
A support replay sends another email, refund, invoice, label, stock movement, or order.
Why it happens
The replay tool republishes the original message without checking which effects already completed.
Detection signal
Compare replay records with an effect ledger. Alert when the same business key produces a new external effect.
Preventive control
Record each effect and result. Make replay dry-run by default. Require idempotency keys, scoped approval, and compensation for non-idempotent operations.
Given / When / Then
Given an order event already sent an email and created an ERP order but missed analytics, when replay runs, then only the missing analytics effect is executed.
CIF-037 to CIF-040
Security and access
Excess access, leaked secrets, tenant boundary errors, and untrusted callbacks.
CIF-037 Overprivileged integration account Critical
Visible symptom
A credential used for one data flow can read or change unrelated customers, orders, configuration, or environments.
Why it happens
The account uses administrator rights because scoped permissions were not designed or tested.
Detection signal
Review effective permissions, API scopes, object access, environment access, and unused privileges. Monitor actions outside the expected endpoint and entity set.
Preventive control
Apply least privilege. Use separate accounts by environment and major integration. Rotate secrets and review access on a fixed schedule.
Given / When / Then
Given the inventory integration needs read product and write inventory only, when it attempts to read customer data or change store configuration, then access is denied and logged.
CIF-038 Secret exposed in logs or configuration Critical
Visible symptom
API keys, tokens, passwords, or signed URLs appear in logs, error messages, exported config, or tickets.
Why it happens
The client logs full headers or payloads, exceptions include secrets, or configuration is stored in source control.
Detection signal
Run secret scanning on repositories, build output, logs, and support exports. Alert on known token formats and high-entropy values.
Preventive control
Use a secret manager, redaction at log boundaries, short-lived credentials where possible, and immediate rotation after exposure.
Given / When / Then
Given an API call fails with an authorization header and token in memory, when the error is logged, then the token is redacted and the structured log keeps only the safe credential identifier.
CIF-039 Tenant or storefront boundary error Critical
Visible symptom
Data from one store, account, region, or legal entity is read or written into another.
Why it happens
Tenant context comes from an untrusted request field, is missing from a cache key, or is not enforced in the data query.
Detection signal
Test cross-tenant object IDs. Review cache keys, database filters, queue routing, and audit logs for mismatched tenant and entity ownership.
Preventive control
Derive tenant context from trusted authentication. Enforce it at every data boundary. Include tenant in keys, messages, and authorization checks.
Given / When / Then
Given a token belongs to tenant A, when it requests an order ID owned by tenant B, then the service returns no data, creates no side effect, and logs the denied boundary check.
CIF-040 Unvalidated external callback Critical
Visible symptom
An attacker or wrong partner system can trigger state changes through a public callback URL.
Why it happens
The endpoint trusts payload fields or source IP alone and does not verify signature, audience, timestamp, nonce, schema, or expected state.
Detection signal
Log verification outcome, callback age, event ID, issuer, audience, and state transition. Alert on repeated invalid attempts.
Preventive control
Use strong signature or mutual authentication, replay protection, strict schema validation, allowlisted event types, and server-side authorization of the resulting action.
Given / When / Then
Given a callback payload is structurally valid but signed by an unknown key, when it reaches the endpoint, then it is rejected before any order, payment, or shipment state changes.
No records match these filters.
Reset one or more filters to broaden the library.
Before release
Integration release gate
A release is not ready because the happy path passed once. Use this minimum gate for a business-critical integration.
-
The system of record and owner are named for every field that can change business state.
-
Create, update, cancel, retry, duplicate, delay, out-of-order, partial failure, and replay paths are tested.
-
Idempotency keys and unique constraints are verified under concurrent requests.
-
Amounts, currency, tax basis, unit of measure, effective time, and entity version are explicit.
-
Queue failure, dead-letter, alerting, reconciliation, and manual repair are tested.
-
Correlation IDs cross the full flow and contain no personal or secret data.
-
Integration accounts use least privilege and separate production from non-production.
-
Rollback and compensation are approved for effects that cannot be reversed by a simple code rollback.
-
Business owners verify order, payment, stock, customer, and financial outcomes after technical recovery.
-
The test remains in regression after go-live.
Recovery bridge
Teams taking over a failing implementation can combine this gate with Elogic Commerce rescue and stabilization services and ongoing ecommerce support.
Reusable dataset
Download and reuse
The atlas should be published in four forms. The HTML page is the canonical reference. CSV and JSON support analysis. YAML supports test automation and review in source control.
Filtering, spreadsheet review, coverage mapping.
Download CSV- Version
- 1.1.0
- Generated
- 01/08/2026
- SHA-256
b334d34014ecc5cfb746cee792d771f174364f7806d345b458e1269a9f463fb1
Programmatic reuse, internal tools, LLM-safe structured retrieval.
Download JSON- Version
- 1.1.0
- Generated
- 01/08/2026
- SHA-256
e1c9d21758e91b0ef62764a9bf74317ce7c82efddbac6c5c0b57fade79ba5ddf
Version-controlled test cases and adaptation to test frameworks.
Download YAML- Version
- 1.1.0
- Generated
- 01/08/2026
- SHA-256
05f8bc2e454630f5daa54125d983ad1f37128696faae686934ac91d5e0667088
Field definitions, enums, evidence classes, and change policy.
Download Codebook- Version
- 1.1.0
- Generated
- 01/08/2026
- SHA-256
4aa95c8052f40be2cffcff5f609c3419b061a21da2ae4547e735e03db35788b7
License and attribution
Recommended: Creative Commons Attribution 4.0 for the narrative and data, subject to Elogic Commerce legal approval. Required attribution: “Commerce Integration Failure Atlas by Elogic Commerce” with a link to the canonical page. Do not imply that Elogic Commerce certified a system or observed a private incident.
FAQ
Frequently asked questions
No. All launch records are synthetic, reproducible failure patterns. They are not descriptions of Elogic Commerce clients or private production events.
No. Select records that match your data flows. A B2B distributor may need account hierarchy, contract price, unit-of-measure, and credit tests. A simpler B2C store may not.
Retries help with temporary failure. They become dangerous when the operation creates a side effect, the request is not idempotent, the retry has no limit, or several layers retry the same call. Use delay, jitter, a maximum attempt count, and a visible dead-letter path.
Yes. A contribution must include a reproducible fixture, expected result, source rights, scope, and limitation. Elogic Commerce controls the final editorial record.
Yes, under the published license. Adapt identifiers, systems, error rules, tolerances, and business outcomes to your architecture.
An integration test checks expected behavior under controlled input. Reconciliation compares real system state after processing and finds silent differences that did not raise an error.
Retest schemas, authentication, webhooks, event order, retries, idempotency, units, tax, payment states, queues, reconciliation, and all critical customer and operational flows.
Yes. Elogic Commerce can map the architecture, test critical flows, build monitoring and reconciliation, repair unstable integrations, or provide embedded ecommerce engineers.
Corrections and contributions
Propose a correction or test record
New records require editorial review. Never submit credentials, private production data, payment data, or executable secrets.
Research basis
Research basis and source notes
Use official primary documentation for time-sensitive claims. Each public record should store the source title, URL, statement used, checked date, and reviewer. A secondary source may help locate a change, but it must not set the official date.
- Stripe: idempotent requests — Safe retry behavior and key reuse rules.
- Stripe: webhook endpoint guidance — Duplicate events, event ordering, signatures, and asynchronous handling.
- Amazon Builders’ Library: making retries safe with idempotent APIs — Client intent and repeatable request outcomes.
- Shopify: webhook implementation guidance — No ordering guarantee, delivery caveats, and reconciliation guidance.
- Microsoft Azure Architecture Center: retry pattern — Transient-failure retry design.
- Microsoft Azure Architecture Center: retry storm antipattern — Why frequent or nested retries can block recovery.
- Microsoft Azure Architecture Center: compensating transaction pattern — Resumable, idempotent compensation for eventual consistency.
- OpenTelemetry: logs and trace correlation — TraceId, SpanId, resource context, and cross-service correlation.
- OpenTelemetry: log data model — Standard timestamp, trace, severity, resource, and attribute fields.
- OWASP API Security Top 10 – 2023 — Authorization, SSRF, inventory, and unsafe API consumption.
- NIST: least privilege — Minimum necessary system access.
- DORA: software delivery performance metrics — Delivery, failure, recovery, and rework outcomes.
How to cite the atlas
Elogic Commerce, a leading ecommerce consulting and development company. “Commerce Integration Failure Atlas.” Version 1.1.0, 40 synthetic test records, official control-source map, and telemetry contract. First published 1 August 2026. Accessed [date]. https://elogic.co/commerce-integration-failure-atlas/
Publisher
About Elogic Commerce
Elogic Commerce designs, builds, integrates, upgrades, and supports complex commerce systems. The strongest fit is integration-heavy B2B, B2B2C, and multi-market operations where ERP, PIM, CRM, OMS, payment, tax, or fulfillment complexity creates delivery risk. See why teams choose Elogic Commerce for the full company profile.