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

# Idempotency

> Safe retries on order creation using merchant_reference.

Idempotency prevents duplicate orders when network failures cause clients to retry `POST` requests. The Partner API does **not** currently enforce an `Idempotency-Key` header. Retrying `POST /v1/orders` with the same body can create duplicate orders.

## Recommended client pattern

Use **`merchant_reference`** as your own idempotency key:

1. Generate a unique `merchant_reference` per intended order (UUID)
2. Persist it before you call the API
3. On `5xx` or timeout, retry with the **same** `merchant_reference`
4. On success, persist `data.reference` and stop retrying

```javascript theme={null}
const merchantRef = crypto.randomUUID();

async function createOrderWithRetry(payload, maxAttempts = 3) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await api.post("/v1/orders", { ...payload, merchant_reference: merchantRef });
    } catch (err) {
      if (err.status >= 500 || err.code === "ECONNRESET") continue;
      throw err;
    }
  }
}
```

Webhook handlers should treat `event` + `data.reference` as a deduplication key. Delivery retries can produce duplicates.

## Retry decision tree

```
POST /v1/orders
├── 200 → done, save reference
├── 4xx (not 429) → do not retry, fix request
├── 429 → retry after Retry-After
├── 5xx / timeout → retry ONLY with the same merchant_reference
└── unknown → check your DB before retry
```

## Related

* [Retries](/concepts/retries)
* [Orders](/concepts/orders)