---
title: "Idempotency"
description: "Repeat a write safely with an Idempotency-Key, and what a repeat answers."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

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, and `Idempotent-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 `409` [`conflict`](/merchant-api/errors#conflict) on the field `idempotency_key`, and changes nothing.
- A write that fails records nothing, so a repeat after a refusal runs again. A [bulk](/merchant-api/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.

```bash
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'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish', {
  key: 'publish-watercolor-basics',
});
```

Answers `200`, abridged:

```json
{
  "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](/merchant-api/reference) page lists the `Idempotency-Key` header. Most writes do. Those that don't refuse the header as `422` [`invalid`](/merchant-api/errors#invalid) at the path `["headers", "idempotency-key"]`, as reads and the `/v1/merchants` operations do:

- **Writes whose answer can't be replayed**: <a href="/merchant-api/reference/create-webhook/">`POST /webhooks`</a> and <a href="/merchant-api/reference/roll-webhook-secret/">`POST /webhooks/{webhook}/secret/roll`</a> answer 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 <a href="/merchant-api/reference/update-store/">`PATCH /v1/stores/{store}`</a>, <a href="/merchant-api/reference/create-upload/">`POST /uploads`</a>, <a href="/merchant-api/reference/set-body/">`PUT /{kind}/{id}/body`</a> and <a href="/merchant-api/reference/create-discount/">`POST /discounts`</a>. 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**: <a href="/merchant-api/reference/record-order/">`POST /orders`</a> takes `source_key`, and <a href="/merchant-api/reference/record-portfolio-event/">`POST /products/{product}/portfolio/events`</a> takes `idempotency_key`. Each records once per key.

## Retrying safely

Retry a write after a timeout, a lost connection, a `500` [`internal`](/merchant-api/errors#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.

Source: https://docs.sherpo.io/merchant-api/idempotency/index.mdx
