Idempotency Keys in B2B Order APIs 2026: Deep Dive with UUIDv4

Idempotency keys are the technique that makes any POST request in a B2B API retry-safe. Without them every network timeout on the client turns into a "did the order create or not?" question — and in 30% of cases the answer is "both". This article walks through production patterns borrowed from Stripe and applied to the FoxReload Orders API.

1. Why a single retry creates two orders

A simple sequence: your ERP issues POST /v1/orders with payload {sku: "PSN_TR_50", qty: 1}. FoxReload creates the order and starts delivery, but the TCP response is lost (network blip). Your HTTP client retries after 30s — FoxReload sees a new request, creates a second order, debits your balance twice. Result: duplicate.

With an idempotency key this scenario is impossible: the server sees the same key, returns the original response, and the second order is never created.

2. UUIDv4 generation on the client

The key must be globally unique and unpredictable. UUIDv4 is the standard choice:

import { randomUUID } from 'crypto';
import axios from 'axios';

async function createOrder(sku: string, qty: number) {
  const idempotencyKey = randomUUID(); // UUIDv4
  return axios.post('https://api.foxreload.com/v1/orders', {
    sku, qty, currency: 'USD',
  }, {
    headers: {
      'Authorization': `Bearer ${process.env.FOXRELOAD_KEY}`,
      'Idempotency-Key': idempotencyKey,
    },
    timeout: 30000,
  });
}

Persist idempotencyKey in your DB before issuing the request. On retry, read the same key — never generate a new one.

3. Server-side dedup window

FoxReload stores each key in Redis with a 24h TTL. Processing logic:

// server-side pseudocode
async function handleCreateOrder(key: string, payload: OrderPayload) {
  const existing = await redis.get(`idem:${key}`);
  if (existing) {
    const stored = JSON.parse(existing);
    if (hash(payload) !== stored.payloadHash) {
      return { status: 422, error: 'idempotency_conflict' };
    }
    return stored.response; // retry — return original
  }
  const response = await createOrderInternal(payload);
  await redis.set(`idem:${key}`, JSON.stringify({
    payloadHash: hash(payload),
    response,
  }), 'EX', 86400);
  return response;
}

The race between two simultaneous requests using the same key is resolved with Redis SETNX plus a Postgres advisory lock on idempotency_key.

4. Comparing dedup storage backends

FoxReload runs a 6-node Redis cluster sharded by hash(idempotency_key). This delivers <2ms p99 latency on the dedup check.

CTA

Idempotency-Key is supported on every POST/PUT/DELETE endpoint of the FoxReload API. The full reference is available after onboarding — request access.