API version upgrades

How to upgrade the Rainforest API version in your integration

Rainforest's API versions are named by the release date. The current version is 2023-12-01. If you're integrated against an older version of the Rainforest API, you should upgrade to the latest version to get access to new features Rainforest has released.

API Versions

2024-10-16 (beta, sandbox only)

2023-12-01

2023-01-01 (deprecating on May 1, 2025)


Minimum API version


Your platform has a minimum API version configured. Every API call requested to Rainforest will utilize this API version implicitly and defines the functionality your platform has access to. Webhook payloads are based on the platform's minimum API version.

This ensures as new API versions are released, your integration is pinned to the API version you integrated against. Your integration will not be impacted by a new API version until you upgrade.


How to set the API version


Before updating your minimum API version, you should update you code to integrate to the latest API version to ensure any changes in the new API version will not break your integration. See each API version guide for all breaking changes you'll need to make to support that version.

Each API request and Rainforest Component will need to know which version to utilize during the upgrade process. You can only specify API versions that are greater than or equal to your platform's minimum API version.

API version header

The Rainforest-Api-Version header can be set on each API request:

curl --location 'https://api.rainforestpay.com/v1/...' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'Rainforest-Api-Version: 2024-09-01' \
--data '{
    ...
}'

Component version

The api-version prop can be set on each Rainforest Component:

<rainforest-payment-report
    session-key="{{session_key}}"
    api-version="2024-09-01"
></rainforest-payment>

Upgrade your minimum API version


Once your integration is compatible with Rainforest's latest API version, you should upgrade your platform's minimum API version.

Upgrading the API version can impact the following:

  • API requests without specifying a Rainforest-Api-Version header
    • New API endpoints available in this version
    • The API contract for request parameters and response payloads
  • The structure of entities sent to your webhook endpoints
  • API requests specifying an API version less than the platform's minimum will fail with a 400 bad request

Submit a request to [email protected] to get your platform's minimum API version upgraded.