Idempotency

​

How it works

{
  "externalRef": "shop-order-889",
  "items": [{ "productId": "prod_x", "skuId": "sku_y", "amount": 25, "quantity": 1 }]
}

• First call creates the order and returns 201.
• Any repeat with the same externalRef on the same surface returns 200 with the existing order — no duplicate charge, no duplicate fulfillment.
• Cross-surface reuse returns 409 CONFLICT: externalRef is unique per account across both surfaces, so a ref already used on /b2b cannot be reused on /retailer/v1 (and vice versa). Treat this as an integration bug, not a replay.

​

The retry recipe

1. Generate the externalRef from your own order id (stable, not random per attempt).
2. POST the create call.
3. On timeout, connection error, or 5xx: retry the same request unchanged.
4. Stop on any 2xx (201 = created now, 200 = already existed) or a non-retryable 4xx.

​

Reconciliation

curl "https://api.wizzgift.com/b2b/orders?externalRef=shop-order-889" \
  -H "X-API-Key: wg_live_..."

​

Related idempotency behavior

• Payment invoices — re-creating a payment with the same method refreshes the same provider invoice instead of creating a second one.
• Webhook deliveries — each delivery has a stable id (whd_...) that retries reuse; deduplicate on it. See verifying signatures.