Idempotency & retries

Network timeouts happen. Because orders spend real money, build your integration so a retry can never send the same gift twice.

external_reference_id — your idempotency key

When creating an order, pass a unique external_reference_id (your own order ID, a UUID without dashes, etc. — alphanumeric, 1–100 characters):

{
  "item": { "id": 5000 },
  "delivery": { ... },
  "external_reference_id": "campaign2026reward0042"
}

The guarantee: within your account, only one order can ever exist per external_reference_id. If you send a create request with a value that already exists, no new order is created — the API returns the existing order with a normal 200 response.

This makes order creation safe to retry:

1. Request times out → you don't know if the order was created.
2. Retry with the same external_reference_id.
3. If the first request succeeded, you get that order back. If it didn't, a new order is created. Either way: exactly one order.

Without external_reference_id, every create request makes a new order — there is no deduplication.

📘

You can also look orders up by this value later — useful for reconciliation:

GET /v1/orders?external_reference_id=myfirstorder001&page=0&element_size=10

Note that page and element_size are required parameters on this endpoint — omitting them returns a 400.

When to retry

Resending a delivered gift

Retrying and resending are different: if a recipient lost the email or mistyped nothing on your side, use POST /v1/orders/{order_item_id}/resend to re-deliver an existing order item. Resend is available for EMAIL and TEXT order items only; other methods return resend_not_allowed.