HomeGuidesReference
Log In
Reference

Idempotency

An idempotency key is a unique string identifier, provided by your app, that Forage can use to recognize retries of the same request.

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.

📘

Update Idempotency Key With Body Changes

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 Key Expiration

Idempotency keys expire after 24 hours. Avoid retrying requests beyond that window.

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.