---
updatedAt: 2025-11-17T21:31:11.000Z
agentTools:
  projectIndex: https://docs.joinforage.app/llms.txt
---

# 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:

```bash
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.

* [Create a Fully Hosted Session](https://docs.joinforage.app/reference/create-session)
* [Create a Custom Balance Check Session](https://docs.joinforage.app/reference/create-custom-balance-check-session)
* [Create a Custom Payment Capture Session](https://docs.joinforage.app/reference/create-capture-session)
* [Capture Payments for an existing Order](https://docs.joinforage.app/reference/capture-order)
* [Create an OrderPayment](https://docs.joinforage.app/reference/create-order-payment)
* [Cancel an OrderPayment](https://docs.joinforage.app/reference/cancel-an-order-payment)
* [Create an OrderRefund for an entire Order](https://docs.joinforage.app/reference/refund-entire-order)
* [Create a partial OrderRefund](https://docs.joinforage.app/reference/refund-partial-order)
* [Create a Payment](https://docs.joinforage.app/reference/create-a-payment)
* [Update a Payment](https://docs.joinforage.app/reference/update-a-payment)
* [Capture a Payment during sandbox testing](https://docs.joinforage.app/reference/capture-a-payment-during-sandbox-testing)
* [Cancel a Payment](https://docs.joinforage.app/reference/cancel-a-payment)
* [Create a PaymentRefund](https://docs.joinforage.app/reference/create-payment-refund)

# Sibling pages

* [Introduction](https://docs.joinforage.app/reference/introduction.md)
* [Request Limits](https://docs.joinforage.app/reference/request-limits.md)
* [Errors](https://docs.joinforage.app/reference/errors.md)
* [Versioning](https://docs.joinforage.app/reference/version-history.md)
* [Changelog](https://docs.joinforage.app/reference/changelog.md)