A network can lose an answer after a write landed. Send an Idempotency-Key header with the write, and repeating it with the same key answers what the first call did instead of writing again.
Keys
- A key is 1 to 255 visible ASCII characters, no spaces. Make it unique per change you mean (a UUID, or a name tied to it like
publish-watercolor-basics), and reuse it only to repeat that same change. - A key is kept for 24 hours, and belongs to the token and the store: another token, or another store, starts afresh.
- The first call answers
Idempotent-Replayed: false. A repeat within 24 hours answers what the first call answered, with its status, andIdempotent-Replayed: true. A repeat that comes while the first is still running waits for it, then answers the same. - The same key with other arguments, or on another operation, answers
409conflicton the fieldidempotency_key, and changes nothing. - A write that fails records nothing, so a repeat after a refusal runs again. A bulk call is the exception: it lands with its refused items, so a repeat answers the same refusals.
When the first answer couldn’t be kept (it was over 512 KiB, a customer of the store was erased since, or the token lost a scope the answer was read under), a repeat answers 409 with context.current: "applied": the write landed once, so read the state back.
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish' \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H 'Idempotency-Key: publish-watercolor-basics'const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish', {
key: 'publish-watercolor-basics',
});Answers 200, abridged:
{
"id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
"status": "published",
"published_at": "2026-11-03T10:00:00.000Z"
}Which writes take one
A write takes a key when its reference page lists the Idempotency-Key header. Most writes do. Those that don’t refuse the header as 422 invalid at the path ["headers", "idempotency-key"], as reads and the /v1/merchants operations do:
- Writes whose answer can’t be replayed:
POST /webhooksandPOST /webhooks/{webhook}/secret/rollanswer a signing secret, which is never kept. If such an answer is lost, roll the secret again. - Writes that change the store or the business, upload or move files, or change discounts and affiliates, such as
PATCH /v1/stores/{store},POST /uploads,PUT /{kind}/{id}/bodyandPOST /discounts. Most of them set a value, so repeating them leaves the same result; for a create, list what exists before you repeat it. - Writes with a key of their own in the body:
POST /orderstakessource_key, andPOST /products/{product}/portfolio/eventstakesidempotency_key. Each records once per key.
Retrying safely
Retry a write after a timeout, a lost connection, a 500 internal or a 503, with the same key and the same arguments. Without a key, read the state back first: the write may have landed.