HomeGuidesReference
Log In
Reference

Versioning

Forage releases a new Payments API version when there is a backwards-incompatible, breaking change. These changes include when:

  • A new field is required in a request payload
  • A field type has changed in a request or response payload
  • A field is removed from a request or response payload
  • The structure of a request or response payload has changed
  • An existing response field can now be returned as null

📘

Payments API Versions And SDK Releases

All SDK releases are backwards-compatible with any API version including and after 2023-05-15.

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}/.

⚠️

Default Version Without Header

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

Pass an API-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}/.