6) Bookshelf workflow - Codes - Delete/Cancel/Refund

For various reasons, it can become necessary to cancel/refund content that was previously created. Let us first recall the steps in the code workflow:

  1. POST v3/codes - Create generates a unique code that contains the rights to a single content item
  2. POST v3/redemptions redeems this content item into a specific user account
  3. GET v4/codes/:code - Read (single, bulk) gets status on code(s)

If your API key has sufficient permissions are such that you were the grantor of the original code, or you are the publisher or institutional account holder behind the code you can remove content from a users bookshelf account at any point. For more information you can speak with Publisher Services.

This is achieved using the DELETE v4/codes/:code - Delete/Cancel/Refund endpoint. As this is a point of frequent question/confusion it is worth noting the behavior this endpoint represents. By calling this endpoint you are attempting to DELETE content regardless of its status.

The following examples will DELETE the content from all user devices, apps, online sites, and also produce a refund in your VitalSource account:

  1. If the code has never used/redeemed
  2. The code has been redeemed but:
    • Less than 14 days have elapsed since redemption
    • User has viewed less than 20% of the title 

If neither of these criteria are true but the code has been redeemed and you call the DELETE v4/codes/:code - Delete/Cancel/Refund endpoint, the only result will be the removal of the content from all user devices, apps, and online sites. This is still a very valid use case, i.e. an employee leaves and was previously given perpetual license or a customer leaves your ecosystem and you wish to revoke rights to content in bulk.

Please note: We deprecated the DELETE/v3/ endpoint and it should not be used. Please use v4/ for all new integrations.

Delete Content

Delete content is among the simplest endpoints to work with and requires only the code you wish to delete and an API key with permissions to receive the refund (should it be issued).

You will need the following elements.

  • VitalSource API key
  • Valid/refundable code

Below is a curl statement that when pasted in a command line will succeed:

curl -X DELETE \ https://api.vitalsource.com/v4/codes/YOUR_CODE_GOES_HERE \

Success will generate

HTTP: 200 OK

Failure is likely to be the result of a code that is invalid, incorrect or has been previously refunded. If you feel that the code should still be refundable please contact support:

In the US/Canada please call: 1-855-200-4146
In the UK please call: +44 800 802 1506
In Australia please call: +61 8 7111 3343

Full documentation is available at DELETE v4/codes/:code - Delete/Cancel/Refund


Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.