Common Issues

Start with the correlation ID and the first failed trace step. Later errors are often consequences of an earlier buyer, security or context failure.

Buyer is not allowed

Check the inbound protocol and buyer identity character for character. Then confirm that an active profile exists in the requested store or as an All Store Views fallback. A store-specific match takes precedence over a global profile.

For OCI, compare USER/username and password separately from optional HTTP transport credentials. For cXML, compare sender domain, sender identity and shared secret.

Security validation fails

The top-level response is PUNCHOUT_SECURITY_VALIDATION_FAILED; the errors array gives the cause.

• For PUNCHOUT_IP_NOT_ALLOWED, confirm the real client IP seen by Magento and the configured IPv4/IPv6 range.
• For signature errors, confirm strict mode, secret and the exact body or normalized parameters used to calculate HMAC-SHA256.
• Do not enable strict mode simply because HTTPS is active; the caller must send the custom signature.

Return URL is rejected

Production URLs must use HTTPS, resolve successfully and resolve only to public IP addresses. Sandbox mode can permit localhost/private addresses, but it still requires HTTPS. Check both A and AAAA resolution when a hostname behaves differently between environments.

Storefront opens as the wrong customer

Check Customer Resolution Mode and its corresponding Magento Customer or identity source. Verify that the resolved customer belongs to the Website of the selected Store View unless global customer sharing is enabled. For a newly provisioned account, check whether Magento requires account confirmation.

Also check whether the request selected the intended store. Protocol-specific request customer overrides should normally remain disabled.

Cart price differs from the request

This is expected when Allow inbound cart item prices is No. Magento uses its catalog and customer pricing. If buyer-supplied prices are part of the approved integration contract, enable the setting only for the required scope and retest tax and currency totals.

Mapping fails or fields are empty

Confirm that the buyer has an active outbound, non-template profile with the same protocol and compatible store scope. In the trace, look for PUNCHOUT_MAPPING_REQUIRED_* errors and map that target to a source value maintained for every relevant product/customer.

An optional-enrichment template such as cxml_outbound_level2 is not a complete replacement for the core required rules.

Return to System redirects back to the cart

The browser may have no active token, the context may be expired, the cart may be empty, the hook URL may now fail validation or mapping validation may have failed. Inspect the browser session and the corresponding trace rather than repeatedly clicking the action.

Request replay returns HTTP 409

• PUNCHOUT_REQUEST_REPLAY_IN_PROGRESS: wait for the original call to finish before retrying the identical request.
• PUNCHOUT_REQUEST_REPLAY_CONFLICT: the same X-Punchout-Request-Key was reused with changed input. Generate a new key for the new semantic action.

Request-body key aliases and X-Idempotency-Key are not accepted.

Inbound OrderRequest does not create an order

Open the inbound-order detail before retrying. Check its effective processing mode, status, failure code and normalized payload.

• Acknowledge Only never builds a quote.
• Validate Only can finish successfully without a Magento order ID.
• Create Magento Order requires a resolvable customer and products, valid addresses, and available shipping and payment methods.
• A buyer-profile override can replace the Store-view processing or pricing mode.
• Snapshot-based pricing needs the original BuyerCookie and an unexpired returned-cart snapshot.

If the status is Manual Review, inspect the reason and process or reject the record from Punchout > Inbound Orders. Do not repeatedly submit the same PO with changed content under the same identity.

Document remains pending or failed

Verify that Magento cron runs the default group. The queue processor is scheduled every five minutes:

php bin/magento cron:run --group=default

Open the queue row and check its next-attempt time, Store View, destination, status and last error. Delivery uses durable Buyer Profile/order routing and does not require an unexpired browser context. Confirm the dedicated ASN or Invoice URL and supplier credentials before using Reset or Force Run.

If the row is Delivery Unknown, Magento cannot know whether the receiver accepted the request before the connection failed. Check the procurement platform before using the separately authorized Retry Unknown Delivery action; an unverified retry can create a duplicate business document.

Trace appears empty

Trace logging is store-scoped. Confirm it is enabled in the buyer's resolved store, not only at Default Config. Old records are removed by the daily retention cleanup.

A working trace for one OCI session looks like this — login and cart-transfer steps share one correlation ID:

Use the Error Catalog for the exact response code and Trace and Simulator for a repeatable diagnosis flow.