Idempotency

A network error can happen after Tixxy created an order but before your software received the answer. Retrying would create a second order, with a second fee. Idempotency keys prevent that.

Send a unique Idempotency-Key header (for example a UUID) with every POST. Use a new key for every new action and the same key when you retry the same action.

curl https://api.tixxy.nl/v1/orders \
  -H "Authorization: Bearer tixxy_live_..." \
  -H "Idempotency-Key: 7f3c9e1a-2b4d-4c8e-9f0a-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ "ticket_type": "tt_01J...", "quantity": 2, "booker": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" } }'

• The first request runs and its successful response is stored for 24 hours.
• A retry with the same key and body returns the stored response with the header Idempotent-Replayed: true. Nothing is created again.
• The same key with a different body returns 422 idempotency_key_reused.
• The same key while the first request still runs returns 409 request_in_progress.
• Errors are not stored, so you can fix the request and retry with the same key.

POST /v1/orders requires an idempotency key. Other POST endpoints accept one.

For a permanent link between your system and Tixxy, also send external_reference when creating an order. It is unique per organisation, so the same order from your system can never end up in Tixxy twice.