Idempotency

Use Idempotency-Key on mutating public API requests so retries are safe.

Idempotency

Mutating public routes expect an Idempotency-Key header. Retries with the same key return the original result instead of creating a second customer, invoice, or checkout session.

Rules

Send a new key for a new logical operation.
Reuse the same key when retrying the same operation after timeouts or network failures.
Keys should be unique per API key / merchant scope (UUIDs or your own deterministic ids work).

curl -sS -X POST "https://api.vortex.nyc/v1/invoices" \
  -H "Authorization: Bearer $VORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv_create_cus_demo_2026_08_03" \
  -d '{ "customerId": "cus_demo", "currency": "usd", "lines": [] }'

What to key

Action	Key it?
Create invoice / checkout / webhook endpoint	Yes
Upsert customer	Yes (stable key per upsert intent)
Collect / refund / credit-note writes	Yes
Pure GETs	No