The Rich Returns API uses API keys to authenticate requests. You can view and manage your API keys in the Rich Returns Dashboard. Make sure that your current plan allows for API access.

For this navigate to Account / API keys in your Rich Returns dashboard. After creation write the key down in a secure place. You will not be able to access it later in full.

Your API keys carry many privileges, so make sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

  • Provide a key "Authorization" in the header of your request

    • Set its value to "RichReturnsToken xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"

    • xxxxx-xxxxx-xxxxx-xxxxx-xxxxx represents your token

    • pay attention to the whitespace between RichReturnsToken and your token

  • Set the "Content-Type" in the header to application/json

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Below is a screenshot of how a request with authentication looks in the popular Postman App:

Sample request in Postman
curl \
-H "Authorization: RichReturnsToken <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{...}'
// using popular library axios (
// token is stored in an ENV file in this case, your implementation might be different
const token = process.env.RICH_RETURNS_API_TOKEN;
try {
// axios sets the content-type to json automatically in the header
const returns = await axios.get("",
headers: {
"Authorization": "RichReturnsToken " + token,
// logic to use returns-data in your system
} catch(err) {
// error handling