HomeGuidesReference
Log In

Versioning

Forage releases a new API version when there is a backwards-incompatible change.

How to specify Forage versions

Forage recommends that you:

  1. Determine the Forage version that includes the most critical features to your integration.
  2. Set that as the default version in the Forage dashboard API settings (sandbox, production)
  3. If you need to use a version of an endpoint that differs from the default, then specify the API-Version Header in the request to override the dashboard settings.

Set the default version in the dashboard

Set the API version for all of your requests in the Forage dashboard API settings (sandbox, production). To prevent breaking changes, the dashboard version defaults to the original unversioned "default" release. If you’re new to Forage, then we strongly recommend updating your dashboard API version setting to the most recent release.

If the dashboard-specified version does not exist for a specific endpoint, then Forage automatically updates requests to that endpoint to the previous version nearest-in-time to the dashboard setting.

For example, if you set the dashboard version to 2024-03-05, then requests to Retrieve an Order default to the original unversioned "default" release. That’s the version nearest in time to 2024-03-05 for GET /orders/{order_ref}/.

🚧

If you do not set a dashboard version, then Forage defaults any requests that omit the API-Version header to the original unversioned "default" release.

Pass anAPI-Version Request Header to override the dashboard setting

To override the dashboard setting for a specific request, include an explicit API-Version header in the request, as in the following example:

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/capture_sessions/ \
     --header 'API-Version: 2024-03-05' \
     --header 'Authorization: Bearer <auth-token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: mid/<Forage Merchant ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "success_redirect_url": "https://www.joinforage.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/status=CANCELED",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1857 Market St.",
    "zipcode": "CA",
    "state": "94117"
  },
  "is_delivery": true,
  "payment_details": {
    "snap_payment": {
      "amount": "1.23",
      "payment_method": "<payment-method-ref>",
      "description": "A SNAP payment",
      "funding_type": "ebt_snap",
      "metadata": {}
    },
    "ebt_cash_payment": {
      "amount": "4.56",
      "payment_method": "<payment-method-ref>",
      "description": "An EBT Cash payment",
      "funding_type": "ebt_cash",
      "metadata": {}
    }
  }
}
'

If you specify a version that does not exist for an endpoint in the header, then Forage automatically updates the request to use the version nearest-in-time to that specified in the header.

For example, if you specify 2024-03-05 in the API-Version Request Header to Retrieve an Order, then Forage sets the version to the original unversioned "default" release. That’s the version nearest in time to 2024-03-05 for GET /orders/{order_ref}/.

API version history

The sections below detail every supported version of the Forage API. Each version is named after its release date, following the YYYY-MM-DD convention.

2024-03-05

  • Updated the Create a Custom Payment Capture Session endpoint to accept a payment_details object instead of separate snap_total or ebt_cash_total request body parameters.
    • With this change, Forage automatically creates associated OrderPayments for the Capture Session.
  • Added a PATCH endpoint to Update an OrderPayment.

2024-02-15

2024-01-08

2023-05-15

Original unversioned release

  • Introduced split tender over SNAP, EBT Cash, and credit/debit cards.