Skip to main content
Two different problems, two different mechanisms. Idempotency-Key makes a retry safe. If-Match makes a concurrent update safe.

​
Idempotency-Key

Required on shipment creation and cancellation.
Contract note. The key is 16–128 characters. Some older material describes a 1–128 range; the OpenAPI contract published here is authoritative, and a key shorter than 16 characters is rejected.

​
Scope

A key is scoped by the operation, the merchant company, and the OAuth client. The same key used for a different operation is a different key — you do not need to keep keys globally unique across your whole system, only unique per intent.

​
Replay semantics

Reusing a key with a changed payload is a conflict, not an update. If you genuinely want to create a different shipment, use a different key.

​
Choosing a key

Derive it from the business intent that must happen at most once — your order identifier plus the operation, for example. Do not generate a fresh random key on each retry: that is precisely the case idempotency exists to prevent.

​
ETags and If-Match

Mutable resources carry a strong numeric entity tag, matching ^"[0-9]+"$ — quotes included. It is the resource’s version in ETag form. Conditional requests are required for:
  • revoking an API credential and rotating its secret
  • updating, deleting, or rotating the secret of a webhook endpoint
  • revoking a tracking link

​
The two failure modes

Never work around a 412 by fetching the current ETag and immediately resubmitting the same change. That defeats the check. Re-read, decide whether your change still makes sense against the new state, and only then retry.

​
Reading the current tag

The ETag comes back on the representation you read, and on the response to a successful state-changing request — so a sequence of updates can use each response’s tag for the next call without an extra GET.