2) Basic Bookshelf Workflow - Codes

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. POST - create a code
2. GET - read a code
3. DELETE - cancel a code

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:

• sku
  • These can be obtained via the GET v4/Products - Read All endpoint
• license-type
  • 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
• num-codes

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"?>
<codes>
  <code>ALLCAPSANDNUMBERS</code>
</codes>

Important Notes:

1. Save all codes prior to dissemination
2. 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.
3. 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"?>
<code>
    <product-sku>BOOKSHELF-TUTORIAL</product-sku>
    <product-eisbn>BOOKSHELF-TUTORIAL</product-eisbn>
    <creation-details>(Code created by VitalSource  on 2020-01-0 00:00:00 UTC)</creation-details>
    <creation-user>redacted</creation-user>
    <creation-login>redacted</creation-login>
    <intended-use>code-api</intended-use>
    <redemption-details>2020-01-0 00:00:00 UTC</redemption-details>
    <user-name>Jane Citizen</user-name>
    <user-email>redacted</user-email>
    <download-license-details>Product Default</download-license-details>
    <online-license-details>Product Default</online-license-details>
    <refundable></refundable>
    <refundable_reason_code></refundable_reason_code>
    <refundable_reason_text></refundable_reason_text>
</code>

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' \
--data-raw ''

This API has no response body. The HTTP codes denote success or failure.

Success

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