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.

VitalSource logic will process the three ensure params in this order:

  1. if ensure_years = -1 this is an override, (else) condition and the content will redeem regardless
  2. if ensure_days > than current remaining installed app license length, then redeem
  3. if ensure_online_days > than current remaining online license length, then redeem
  4. if ensure_years > than current remaining installed app license length, then redeem
    • if ensure_years passed as "" this == 3
      • if ensure_years = 3 > than current remaining installed app license length, then redeem

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

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

Data Definitions

Name
Usage
Description
Data Type
Example
Required
sku request body 

The VitalBookID (VBID) for the title. To determine your available catalog make the GET v4/products/ request. Payload from that endpoint will contain "vbid", "sku" and "eisbn_canonical". Along with "fpid" from legacy integrations, all these options are acceptable as sku="L-999-70461" 

string
:"L-999-70031"
Yes
term request body  Term length for installed apps. Options are UTC, days, perpetual, block="no access"

time

int

string 

:"2020-12-31 23:59:59"
:"365"
:"Perpetual"
:"no access"
Yes
online_term request body The desired license length to grant the user for online access. If this field is not specified, term will be used in place of online_term. Options are days, perpetual

int

string

:"365"
:"Perpetual"
No
ensure_days request body Refers to the minimum number of days you wish for this user to have downloadable access to the product before giving a new license.

int

:"365"
No
ensure_online_days request body Refers to the minimum number of days you wish for this user to have online access to the product before giving a new license. int :"365" No
ensure_years request body Refers to the minimum number of years you wish for this user to have downloadable access to the product before giving a new license (defaults to 3 years). int  :"2" No

price

request body CAUTION - Do not pass this element without first consulting with your integration and customer success manager as it is an override to publisher agreements. Set the code price on each request within a bulk redemption request. If not included, the product-level price will be used. float

50.00

No

tag

request body String field to allow reporting data to move through VST systems string

:"no_spaces

_allowed"

recommended

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

Name
Description
code The redeemed code giving the user access to the sku for the durations presented in the license params.
sku Product identifier for the product for which we are granting access.
download_license Contains details and duration of this license.
online_license Contains details and duration of this license.
list_price The price for the package if necessary

title

Asset title
author Name of asset author
imprint  Name of imprint holding asset within VitalSource Manage
publisher Name of the publisher within VitalSource Manage

 

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

HTTP & Error messages 
Message
201

OK

403

The API key does not have proper permissions

404 The product matching sku was not found.
422 Bad request
422  Required field is missing
422  errors: message in body

 

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

Comments

0 comments

Article is closed for comments.