Version history

The Forage API is versioned. A new version is released when there is a backwards-incompatible change to the API.

The API version for all of your requests is set in your account API settings in the Forage dashboard. To prevent breaking changes, the default is the oldest supported API version.

Forage strongly recommends updating the version in your API settings to the most recent release.

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.

2023-05-15

• Introduced psp_customer_id to replace the original customer_id request parameter. Use psp_customer_id to share a credit/debit TPP customer ID with Forage.
• Added a customer_id request parameter, required to perform balance checks. Use customer_id to share a merchant’s ID for a customer with Forage.
  • POST requests to the following endpoints accept a customer_id:
    • Create a Fully Hosted Checkout session: /sessions/
    • Create a Custom Checkout session: /capture_sessions/
    • Create an order: /orders
    • Create a payment method: /payment_methods/
    • Create a payment for a given order: /orders/{order_ref}/payments/
    • Create a payment: /payments/
  • GET requests to the above endpoints return the customer_id, if available.
  • This change impacts balance checks. If you want Forage to perform a balance check, you must pass a customer_id.
• Added an external_order_id request parameter. Use external_order_id to match a merchant’s order ID with a Forage order ID.
  • POST requests to the following endpoints accept an external_order_id:
    • Create a Fully Hosted Checkout session: /sessions/
    • Create a Custom Checkout session: /capture_sessions/
    • Create an order: /orders
    • Create a payment: /payments/
    • Create a payment for a given order: /orders/{order_ref}/payments/
    • Create a refund for a given order: /orders/{order_ref}/refunds/
    • Create a refund for a given payment: /payments/{payment_ref}/refunds/
  • GET requests to the above endpoints and to /reporting endpoints return the external_order_id, if available.

Original unversioned release

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

How to override API version account settings

To override the API version in your account settings for specific requests, set the version in the API-Version request header, as in the following example:

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/sessions/ \
     --header 'API-Version: 2021-12-19' \
     --header 'Merchant-Account: 1234567' \
     --header 'Authorization: Bearer sandbox_lsIZjMZ2eaS6H5SpBcsRI8mViRwKfA' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "snap_total": 100,
  "ebt_cash_total": 20,
  "remaining_total": 0,
  "product_list": [],
  "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": "185y Market St",
    "line2": "",
    "state": "CA",
    "zipcode": "94103"
  },
  "is_delivery": false,
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ]
}
'