Best practices

Understand the best practices when integrating with the Digital River API.

API keys

When integrating the Digital River API, you should be aware that we use public, confidential, and restricted keys.

Public keys

The public API keys identify your account with Digital River and allow you to create sources. You can use them with your DigitalRiver.js JavaScript code.

Confidential keys

The confidential (secret) API keys allow you to send an API request to Digital River without restriction. Keep these secret keys confidential and only store them on your servers. Don't use your confidential key for everything. Instead, consider using restricted keys when you want to limit access to your environment.

Restricted keys

If you want more security, you can create restricted API keys. A restricted key reduces risk when using or building services. It provides the minimum level of access and permissions a service needs to access specific resources in the Digital River API. Use restricted keys when you want to limit access for services that interact with the Digital River API. You can name a restricted key and assign it to the service you want.

Versioning and keys

Your account's API version determines the structure of events generated by API requests. It also determines the requests allowed by an API and the responses generated.

A version contains breaking changes that require you to change your workflow. The version's are dated and our implementation allows you to remain on your current version until you're ready to update to the latest version.

Ensure that your API keys are configured for the version expected by your code. In other words, when your code is deployed from test to production, the version on the keys should match the code version.

You can choose from the following options when updating and managing your API versions:

Testing a new version

We recommend that you update and test a new API version in your test environment before you update the API version in the production environment. 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 update your production environment.

Creating a restricted key and assigning it to a version

We recommend that you create a restricted API key when you want to limit 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 create, edit, delete, and rotate restricted keys.

Creating a webhook and assigning it to a version

You can create a webhook and assign it to a specific version. This allows you to send a specific notification to a team or partner.

Testing a version with a single API request

You can test a single API request without upgrading your API key. Select a version of the library to change the API version used and create a webhook endpoint with the same API version as the DigitalRiver.API_VERSION property in the library. Use the Release notes to find the API version you need and view all breaking changes.

To set an API version with a specific request, send the version number in the header: digitalriver-version=2020-09-30


Digital River often makes non-breaking changes to our API request and response content. As a result, we recommend your integration conform to the tolerant reader principle. Specifically, this means that you should:

  • Be aware that new elements can be added to responses at any time.

  • Build your code to extract only the attributes needed when reading responses and ignore everything else.

  • Avoid coding with a specific order of fields in mind.

  • Assume that ids are alphanumeric strings, which potentially contain special characters, and they have variable lengths.

  • Expect changes to the length and value of error messages and other strings that don’t represent an enumeration, type, or code.

  • Anticipate the addition of new optional request and query parameters.

Fraud detection

To improve fraud detection, you should provide an IP address when creating a checkout, invoice, or order.

Call debugging

When working with Digital River to debug calls, please provide the x-dr-requestid value returned in HTTP response headers. Alternatively, you can generate your own request identifier. If you do so, we'd prefer you use request-correlation-id as the HTTP header name.

Validation and conflict errors

Attempt to minimize HTTP 400 Bad Request and 409 Conflict error types by adding appropriate validation checks before a request is submitted.

Transaction Speeds

  • For HTTP GET requests, we encourage making concurrent calls.

  • Avoid making changes to the same resource in multiple calls. Instead, bundle changes in a single call.

  • Avoid making concurrent mutation calls to the same resource.

Test Mode

Use the liveMode flag contained in API responses to validate that you are pointing to the correct environment.

"liveMode": false


  • When using webhooks, check the Digital River signature to ensure callback requests have not been tampered with.

  • The webhook end point must be able to handle concurrent webhook callback requests.

  • Webhook events may be delivered multiple times. So be sure you can process the delivery of duplicate events.

  • Your webhook endpoint must respond to callback requests in a timely manner. A response time greater than 3000 milliseconds is considered a timeout. We expect you to immediately acknowledge the callback request by sending an appropriate HTTP 2XX response code. Once this acknowledgment is sent, you can then asynchronously process the webhook event on your end.