Idempotency

A network error can happen after the Platform assigned trees to a recipient but before your software received the answer. Retrying would assign trees a second time. 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://woodyou.care/api/v2/recipients \
  -H "Authorization: Bearer wyc_live_..." \
  -H "Idempotency-Key: 7f3c9e1a-2b4d-4c8e-9f0a-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "trees": 1, "external_reference": "ORDER-5012" }'

• 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 /v2/recipients and POST /v2/gift-codes require an idempotency key, because both take trees from your unassigned trees. Other POST endpoints accept one.

For a permanent link between your system and the Platform, also send external_reference when creating a recipient. It is unique per company, so the same customer from your system can never end up on the Platform twice.