Idempotency

If a network outage disrupts an API request, then you might not receive a response. The Forage API requires that you pass an Idempotency-Key header in some requests so that you can retry a request that fails due to network issues while ensuring that the request only executes once. This prevents duplicate financial side effects.

Forage uses the Idempotency-Key header to identify retried requests. If the API recognizes a duplicate request with the same request body and Idempotency-Key value after the request has already executed, then it serves a cached response.

📘
If you change the request body, then you must also change the Idempotency-Key value.

Forage recommends using a deterministic Idempotency-Key, such as the UUID of the related object on your backend. For example, if the UUID for an order in your system is 75c34048-f166-4bf7-8447-2bbd39ff9ebe, then you could share that value as the Idempotency-Key when you send a request to create a Fully Hosted Session that initiates customer checkout for the order:

curl -X POST \
-H 'Idempotency-Key:75c34048-f166-4bf7-8447-2bbd39ff9ebe' \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <your_token>' \
https://api.sandbox.joinforage.app/api/sessions/ \
-d '
{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Unit 3",
    "zipcode": "94102",
    "state": "CA"
  },
  "is_delivery": true,
  "snap_total": 25.99,
  "ebt_cash_total": 25.99,
  "success_redirect_url": "<https://your-app.com/receipt>",
  "cancel_redirect_url": "<https://your-app.com/order-canceled>",
  "remaining_total": 0
}
'

🚧
Idempotency keys only last for 10 minutes on the Forage backend.
Don’t retry requests for more than 10 minutes.

Endpoints that accept idempotency keys

POST requests that create Forage Sessions, Orders, Payments, and Refunds accept idempotency keys. Avoid sending idempotency keys in GET and DELETE requests, which are idempotent by definition.