An HTTP timeout does not tell you whether the server created a shipment record. Retrying with a new identity can create a second record and duplicate monitoring work. Idempotency lets one intended creation be recognized across repeated submissions.
Use a stable key tied to your application’s fulfillment operation. The key is not the tracking number: a carrier can reuse a number and one order can have more than one parcel or replacement cycle.
Choose the key before sending the request
Persist an operation ID and the exact body in your own outbox before the first attempt. A fulfillment event ID plus a parcel-cycle ID is a useful basis. Keep the value free of customer email addresses or other private details, because it may appear in operational diagnostics.
POST /v1/shipments requires Idempotency-Key. The first successful create returns 201. An identical retry returns 200 with replayed=true. Reusing a key with a changed body returns 409; changing the key to bypass that conflict can hide an integration bug.
Handle the response according to what is known
Separate a confirmed API rejection from an ambiguous connection failure. When the connection fails after sending a create request, repeat the same key and body within the documented retention behavior, or reconcile the recorded operation before taking another action.
| Situation | Next step |
|---|---|
| 201 created | Save the returned shipment ID against the fulfillment. |
| 200 replayed | Reuse the returned identity; do not create another local parcel. |
| 409 changed body | Compare the saved request with the retry and correct the mismatch. |
| Transport timeout | Keep the same operation identity; do not invent a new creation key. |
| New replacement parcel | Create a deliberate new cycle and a new key. |
Keep updates separate from creation retries
Once a record exists, use the documented update operation for editable metadata or stopping monitoring. Tracking identity is immutable. A retry of the original create should not be repurposed as an update, and a closed record needs a new cycle to resume.
Imports and tracking jobs also require idempotency keys, but their results and retention rules differ. In particular, a removed tracking-job idempotency record may allow the key to create new work later. Do not assume a key is a permanent global lock.
Test concurrency as well as a sequential retry
Submit the same creation twice in a local or isolated integration fixture and assert that both responses refer to one record. Repeat concurrently, then change one field while holding the key constant and assert a conflict. Simulate losing the first response after the server commits.
Your local order mapping also needs a unique constraint or equivalent transactional rule. Remote idempotency prevents duplicate remote creation; it does not automatically protect two workers inserting duplicate local associations.
Common questions
Should I use the tracking number as the idempotency key?
Prefer an operation or fulfillment-cycle identity. A tracking number alone cannot distinguish a later reuse, replacement or separate shipment cycle.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.