POST v4/fulfillments - Create

A safe shortcut

The v4/fulfillment API combines three existing APIs into one request so you can accomplish the workflow below in just one step:

1. Check a user license at GET v3/licenses - Read
2. Make a code at POST v3/codes- Create
3. Redeem the code into the user account at POST v3/redemptions - Redeem

v4/fulfillments is an upgrade both for ease of use and in terms of safety. Your integration will have: 

• Fewer steps, which means you will need to understand, build and maintain fewer endpoints
• The license verification part of the code process is built into v4/fulfillments. This ensures that users have only the content they should and that your code will be redeemed for the exact duration you intend.

Ensure

Though this param exists as part of v3/codes it has been refined for the v4/fulfillments API. When passing ensure_{param} you are asking VitalSource to ensure that the user has at least the duration specified in the term param, as required by this API. 

Integrators who have consistent patterns can use ensure to protect from producing codes that exceed their own boundaries.

The logic for deciding what to include for the different ensure values is based on a logic cascade:

• if ensure_years = -1 (this is an override), redeem the code for the user despite any existing license length remaining
• if ensure_days > than user's remaining downloadable license length, then redeem
• if ensure_online_days > than user's remaining online license length, then redeem
• if ensure_years > 0 and if ensure_years > than user's remaining downloadable license length, then redeem
• if ensure_years = 3 > than user's remaining online license length, then redeem
  • Note: if ensure_years is passed as blank or not passed then it defaults to 3

If possible, we recommend testing and then adopting a fulfillment structure with term + ensure. 

POST https://api.vitalsource.com/v4/fulfillments

Data Definitions

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
X-VitalSource-Access-Token: lowercaseandnumbers
Content-Type: application/json

Default example

Request body - default example

{
   "fulfillment": {
      "sku": "L-999-70030",
      "term": "180",
      "online_term" : "180", 
      "ensure_days": "365",
      "tag": "CS_Support##"
   }
}

Response body - default example

{
   "code": "LETTERSANDNUMBERS",
   "sku": "L-999-70030",
   "download_license": {
     "details": "Expires 180 days after registration",
     "duration": "180 days"
   },
   "online_license": {
     "details": "Expires 180 days after registration",
     "duration": "180 days"
   },
   "title": "Fall of the House of Usher",
   "vbid": "L-999-70030",
   "author": "Edgar Allan Poe",
   "imprint": "Originals",
   "publisher": "Hayes Barton Press"
}

Response descriptions

Ensure example - step 1

Request body - ensure example step 1

{
   "fulfillment": {
      "sku": "L-999-70029",
      "term": "2021-06-01 23:59:59",
      "online_term" : "2021-06-01 23:59:59", 
      "ensure_days": "180",
      "tag": "example_001"
   }
}

Response body - ensure example step 1

{
   "code": "LETTERSANDNUMBERS",
   "sku": "L-999-70030",
   "download_license": {
     "details": "Expires at 2021-06-01 23:59:59 UTC",
     "duration": "Until 2021-06-01 23:59:59 UTC"
   },
   "online_license": {
     "details": "Expires at 2021-06-01 23:59:59 UTC",
     "duration": "Until 2021-06-01 23:59:59 UTC"
   },
   "title": "The Elves and the Shoemaker",
   "vbid": "L-999-70029",
   "author": "Brothers Grimm",
   "imprint": "Originals",
   "publisher": "Hayes Barton Press"
}

Ensure example - step 2

Request body - ensure example step 2 (resend same request, same user)

{
   "fulfillment": {
      "sku": "L-999-70029",
      "term": "2021-06-01 23:59:59",
      "online_term" : "2021-06-01 23:59:59", 
      "ensure_days": "180",
      "tag": "example_001"
   }
}

Response body - ensure example step 2

HTTP 422 
{
   "errors": [
   "user guid LETTERSANDNUMBERS already has at least 180 days of access to product L-999-70029 "
   ]
}

Error Codes