Troubleshooting

The buyer silently ignores a document you sent

You send a cart, an order response or an invoice, the transmission succeeds, and the buyer has no record of it. No error, no rejection, nothing to investigate.

Short answer

The payloadID must be unique for every document you ever send. Buyers deduplicate on it and discard a repeat without reporting anything — deliberately, because that is what makes retries safe. Silence is the signature of this problem, so when a document vanishes without complaint, check the identifier before anything else.

Causes, most likely first

Ordered by how often each one turns out to be the culprit, not by how interesting it is. Work down the list.

  1. The payloadID is derived from business data

    How to confirm: Your identifier contains the order number, the cart id or the invoice number. Resending a corrected document then reuses the identifier of the original and is dropped as a duplicate.

    Fix: Generate it from a timestamp, a random component and your domain — the conventional form is 1733836800.9271@supplier.com. Nothing downstream parses it; it only has to be unique.

  2. A retry reused the identifier after the content changed

    How to confirm: The first attempt failed, something was corrected, and the retry carried the original identifier.

    Fix: Reusing the identifier is correct for an idempotent retry of the identical document, and wrong the moment the content differs. Generate a new one whenever anything in the document changes.

  3. Test and production share an identifier generator

    How to confirm: A sequence or counter that resets, or the same seeded generator in both environments, produces collisions that only appear once both are live.

    Fix: Include the environment in the identifier, and never use a resettable counter as the source of uniqueness.

  4. The identifier is being truncated

    How to confirm: The buyer stores it in a shorter field than you generate. Two identifiers that differ only in their tail then collide on their side while looking distinct on yours.

    Fix: Keep it comfortably under 255 characters and put the random component early rather than at the end.

  5. The same identifier is used across document types

    How to confirm: An invoice reusing the identifier of the order it bills.

    Fix: Generate per document, not per transaction. They are separate documents in the buyer’s log even when they describe the same order.

If it is not on your side

Ask the buyer to search their transaction log for the specific payloadID. "Received and deduplicated" and "never arrived" look identical from your side and lead to completely different investigations, and that search is the only thing that separates them.

Check the document itself

Paste your cXML or OCI payload into our free tester. It runs entirely in your browser and reports the structural problems buyers reject on.

Open the tester

Related questions

What should a payloadID look like?

The convention is datetime.process.random@hostname, and no part of it is interpreted by anyone. Readability helps you correlate your own logs, which is the only reason to prefer a structured form over a bare UUID.

Will the buyer tell us when they drop a duplicate?

Usually not. Deduplication is meant to be silent so that a retried document does not generate a spurious error, and the cost of that design is exactly this failure mode.

Other failures

Rather not be the one debugging this?

We build and run the endpoint, and deal with the buyer’s technical team directly. Pricing is published in full.

See pricing Send us the error