Versioning
Learn about API versioning and updating, as well as non-breaking and breaking changes.
Last updated
Digital River API reference
Learn about API versioning and updating, as well as non-breaking and breaking changes.
Last updated
Your account's API version determines the allowable requests and the response structure returned by those requests. The version also defines the structure of generated events. When you sign up for the Digital River API, your account is automatically set to the latest version.
We try to maintain backward compatibility. However, we version the Digital River API when a change creates compatibility issues. Each version contains breaking changes that may require you to update your workflow. All versions are dated and we allow you to remain on your current version until you're ready to . Once you've upgraded, you still have the ability to roll back your API version. We also provide you with some other options for configuring and testing versions.
We will release non-breaking changes without introducing new versions. Your code will be able to handle these changes no matter what version it's on. The following changes are non-breaking, and the descriptions for these non-breaking changes appear in the latest version of the documentation:
Adding a new API resource
Adding a new method to an API resource
Adding new optional request parameters to existing API methods
Adding new properties to an existing API resource
Changing the order of properties in existing API responses
Changing existing error response codes or messages
Adding a field to a request or response
Adding a value to an enum
Adding new event types
Adding or removing prefixes (such as sku_ for SKU IDs)
Changing the length or format of strings, such as object IDs, error messages, and other human-readable strings
The following changes are breaking:
Adding new or modifying existing validation to an existing API resource
Requiring a parameter that was not required before
Modifying the expected payload of webhooks and async callbacks
Changing the data type of an existing field
Changing the supported filtering for existing API resources
Renaming a field or API resource
Adding a new feature that will change the meaning of a field
Removing an existing field or API resource
Changing the URL structure of an existing API resource
You should always ensure your API keys are configured for your code's expected version. In other words, when your code is deployed from test to production, the version on the keys should match the code version.
When performing configurations, we allow you to test a new version, create a restricted key and assign it to a version, create a webhook and assign it to a version, and test a version with a single API request.
To set an API version with a specific request, send the version number in the header: digitalriver-version=2020-09-30
Periodically we release new features that require you to apply changes to your application before you can safely without disruption. These features are "breaking changes."
We create a new version of the Digital River API and the API reference portal whenever we release these breaking changes. In the , we add notes that describe the breaking changes, such as in the sample below.
To see what API version you're currently running and , navigate to the API keys section in Digital River Dashboard. If running an older API version, you can update to the latest version to take advantage of new features and improvements.
Test the new API before updating to the new version. Digital River provides a where you test Digital River features without affecting live data.
You can safely from your Dashboard.
We recommend that you and test a new API version in your before you update the API version in the . Your production environment can remain on the production version until you are ready to upgrade to the latest version. This allows you to continue using your API keys associated with your production environment while testing a new version in your test environment. When you finish testing, you can your production environment.
We recommend when limiting an application, batch job, or partner to a specific API version. You can also use it to allow your teams to choose when they want to upgrade their API version. You can , , , and .
You can and assign it to a specific version. This allows you to send a specific notification to a team or partner.
You can test a single API request without upgrading your API key. Select a library version to change the API version used and with the same API version as the DigitalRiver.API_VERSION property in the library. Use the to find the needed API version and view all breaking changes.
