Idempotency

Networks fail in the middle of a call. Every write can be retried safely, so a guest never gets cashback twice for one check.

Checks and visits: external_id

POST /v1/transactions and POST /v1/visits require external_id: your own id of the check or the visit. We apply each external_id once per venue. If you send it again, you get 200 with the stored result instead of 201, and nothing changes on the card. This holds forever, not just for a day, so it is safe to resend a whole shift after the till was offline.

Everything else: Idempotency-Key

For other writes (enrolling a member, redeeming a reward, creating a dish) send an Idempotency-Key header with a unique value, for example a UUID you generate before the first attempt. We store the response for 24 hours. A retry with the same key and the same body returns that response with the header Idempotent-Replayed: true. The same key with a different body is refused with 409 idempotency_key_reused.

curl

curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6d1c0a-9b0e-4d2b-8e57-enrol-77" \
  -d '{ "phone": "+37366791102", "first_name": "Ion", "consent": true }'

# repeat the same call: same body, same status, plus the header
# Idempotent-Replayed: true

How to retry

Retry on network errors, timeouts, 429, 500, 502 and 503. Do not retry other 4xx; the answer will not change.
Wait before each retry and wait longer each time, for example 1, 2, 4, 8 seconds.
Keep the same external_id or Idempotency-Key across retries of one operation. A new value means a new operation.