Many actions related to codes can be performed without interacting directly with user accounts. In this section we will perform all of those possible steps using the VitalSource code API(s).
An alternative pathway that is available to all VitalSource customers is to login to our UI based web product VitalSource Manage and complete these same steps.
In this article we will:
1. Create a Code
Using the v3/codes - Create endpoint, you will generate a unique code that can either be given to users or you can redeem it on their behalf as part of a workflow. It should be stressed that creating codes is possibly a billable event, depending on your agreement with VitalSource. (VitalSource bills at either create or redeem. speak to your AE from more info)
Codes combine multiple properties in the body of the request and our servers place these elements in the license file of the content upon redemption of the code.
The required fields in the body of the request are:
- These can be obtained via the GET v4/Products - Read All endpoint
- If you chose absdate, then you will need day/month/year of expiration
- If your chose numdays, then you will need the number of days until expiration
To succeed with this endpoint you will need:
- A valid API key
- Use the "tag" parameter to pass a string with information useful in reporting
Below is a curl statement to work with this endpoint
curl -X GET \https://api.vitalsource.com/v3/licenses.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="BOOKSHELF-TUTORIAL" license-type="default" tag="Test" num-codes="1"/>
Successful response will include:
- The requested codes
<?xml version="1.0" encoding="UTF-8"?>
- Save all codes prior to dissemination
- Be sure to retain any associations you make, to users in your system. Until a code is redeemed VitalSource has no visibility into code association other than to the API key that created it.
- If you are going to be emailing the code to customers be sure to include the code and instructions on how to redeem it. Here is a link to an article on that topic. You should include the link in your email https://support.vitalsource.com/hc/en-us/articles/360020775933-Redeem-a-code
Users with full accounts will be accustomed to redeeming codes themselves within the application or online product. Codes can also be disseminated to users as you see fit in an institutional setting, but wherever possible we encourage you to redeem the code on behalf of users to streamline the experience and minimize errors. For more information we explain redeem and SSO here
2. Get a Code
Using the v4/codes GET endpoint you can request information on a code.
An example request:
curl --location --request GET 'https://api.vitalsource.com/v4/codes/ALLCAPSANDNUMBERS' \
This API will give a complete breakdown of the history of this code.
<?xml version="1.0" encoding="UTF-8"?>
<creation-details>(Code created by VitalSource on 2020-01-0 00:00:00 UTC)</creation-details>
<redemption-details>2020-01-0 00:00:00 UTC</redemption-details>
3. Delete a Code
Using the DELETE v4/codes API you can can cancel content based upon your agreement with VitalSource.
To delete a code simply append it to the header.
curl --location --request DELETE 'https://api.vitalsource.com/v4/codes/ALLCAPSANDNUMBERS' \
--header 'Content-Type: text/xml' \
--header 'X-VitalSource-API-Key: YOUR_VST_API_KEY' \
This API has no response body. The HTTP codes denote success or failure.
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