Idempotency - Liquidramp

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:

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

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