Getting Started

Idempotency

Safely retry create requests without risking duplicates. Send an Idempotency-Key header and the API guarantees the operation runs at most once.

How it works

On supported POST create endpoints, attach a unique Idempotency-Key. The key is scoped to your business.

The first request with a given key is processed normally and its response is stored.
Retries with the same key and the same body replay the original response, including the original status code. The operation is not run again.
Stored responses are kept for 24 hours. After that, the key is forgotten and may be reused.

Same key, different body

Reusing an idempotency key with a different request body returns 409 Conflict (IDEMPOTENCY_KEY_REUSED). Generate a fresh key per distinct operation.

Supported endpoints

Idempotency keys are honored on create endpoints, including:

POST /businesses/{businessId}/bookings
POST /businesses/{businessId}/gift-cards
POST /businesses/{businessId}/products

Choosing a key

Use a value that is unique to the operation you intend to perform, such as a UUID v4 generated once and reused only for retries of that exact request.

Create a booking idempotently

curl -X POST "https://api.salonify.eu/api/v1/businesses/{businessId}/bookings" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1f0c5e8a-3b2d-4f6a-9c11-7e2b9a4d5f88" \
  -d '{ "serviceIds": ["svc_abc"], "date": "2026-07-01", "startTime": "10:00" }'

Best practice

Generate the key before you send the request and persist it alongside your own record. If your process crashes mid-request, retry with the same key on restart and you will never create a duplicate.

Conflict response

409 Conflict — key reused with a different body

{
  "statusCode": 409,
  "error": "Conflict",
  "code": "IDEMPOTENCY_KEY_REUSED",
  "message": "Idempotency-Key was already used with a different request body"
}

Pair idempotency with retry-on-429 from Rate Limits for resilient writes.