This article is for DEVELOPERS
With Origin Catalogue API, you’ll be able to give your customers more diversity, offering them access to an expansive and growing digital catalogue of content.
When setting up your feed, we recommend that you accept all products instantly and send them to a queue to process. This will ensure the fastest possible product feed ingestion.
Please note that processing titles individually will slow down the process considerably.
Using the Snapplify Ecommerce plugin for WordPress may alleviate the need to write code for receiving the product feed from Snapplify. Find out more about integrating the Snapplify Ecommerce plugin on WordPress.
Let’s get started
The Product Webhook provides an interface for programmatically receiving product data from Snapplify. You will need to implement this webhook in order to ingest Snapplify’s product feed for sale through your store’s front end.
The webhook is a POST request which is sent from the Snapplify catalogue server whenever products are added, updated or archived. The request consists of an HTTP BODY containing a JSON string with the product information. See the next section (Product data’) for the structure.
Additionally, an OAuth2 style Authorization header will be applied to the request, to prevent this public endpoint from being called by an unintended source. You should check this header. The auth token is a standard token supplied by the customer.
Example request made from catalogue service to a client using curl:
curl --request POST \
--url https://example.com/action/push-asset \
--header 'Host: example.com' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX' \
--data '{ … product … }'
The API request is sent under the following circumstances:
Action | Description |
product updated | When properties or images are updated. Availability and price changes included. |
product added | When a new product has been added. |
product archive | When the product has been archived. |
Product data
Below is a table of notes about the structure. Further down is a full example of the structure of the data that is sent in the API request.
Note the allow.
Property | Allow Empty | Description |
takedown | No | Available for sale, true or false. |
copyright | Yes | The product’s copyright message. |
relatedIdentfier | Yes | Print ISBN. |
subject | Yes | The product’s subject. |
edition | Yes | The product’s edition. |
description | Yes | The product’s description. |
includedForSaleInCountries | Yes | This can either be null or a comma-separated string of ISO 3166-1 alpha-2 country codes. |
language | Yes | The language of the product. ISO 3 letter code. |
availability | No | The product sale availability. AVAILABLE: Item is available for sale. UNAVAILABLE: Item is unavailable for sale. |
type | No | The type indicates the type of asset, LIBRARY, PRODUCT and RESOURCE. |
title | Yes | The product’s title. |
archived | No | If true, this product should not be available for sale. |
gradeLevel | Yes | The education level. This can be a string or a number. |
prescribed | Yes | If this product has been selected for prescribed content. |
subTitle | Yes | The product’s alternative or subtitle. |
numberOfPages | Yes | The number of pages in the product. |
| publishedDate | Yes | The date the product is/was published. |
| embargoDate | Yes | The date from which the product can be accessed by users. |
price | No | float or decimal (32,2). Can be 0.00 to indicate the item is free content. Always VAT excl. |
imageUrl | No | The image URL is for a full-sized image. This should be downloaded, and not used to serve images from your front-end. Consider comparing the imageMd5Hash since this may not always change. |
supplier | No | The product’s supplier. |
currency | No | The ISO 3 letter currency code. |
categories | Yes | The product’s category. |
assetUrl | No | The product’s asset file URL. |
assetMd5Hash | No | The MD5 hash of the encrypted product source file. |
identifier | No | The product identifier (ISBN). |
imageUrlOriginal | No | The product’s image file URL. |
seriesName | Yes | The product’s series name. |
excludedForSaleInCountries | Yes | This can either be null or a comma-separated string of ISO 3166-1 alpha-2 country codes. |
assetUrlOriginal | No | The product’s original asset file URL. |
subjects | Yes | The product’s subject code and label. |
JSON product example
The following depicts the structure of a single product:
{
"identifier":"9780323138727",
"id":16519827,
"takeDown":false,
"copyright":"Elsevier Science",
"relatedIdentifier":"9780122771613",
"subject":null,
"edition":null,
"Description":"sample description.",
"includedForSaleInCountries":"",
"language":"English",
"availability":"AVAILABLE",
"type":"asset",
"title":"Statistical Reasoning in Law and Public Policy",
"archived":false,
"gradeLevel":null,
"prescribed":false,
"subTitle":"Tort Law, Evidence and Health",
"numberOfPages":925,
"price":1462.5196294784546,
"imageUrl":"https://img2.snapplify.com/... /9780323138727.jpg",
"supplier":{
"label":"Elsevier",
"code":"supplierexample"
},
"currency":"ZAR",
"categories":[
{
"id":35,
"label":"Society & Social Sciences",
"parent":null
}
],
"assetUrlOriginal":"https://assets2.snapplify.com/ ... /9780323138727.pdf",
"imageUrlOriginal":"https://img2.snapplify.com/... /9780323138727.jpg",
"assetUrl":"https://assets2.snapplify.com/... /9780323138727.pdf",
"assetMd5Hash":"d298883594eb818bd17912ab0ee1e195",
"imageMd5Hash":null,
"seriesName":"Statistical Modeling and Decision Science",
"excludedForSaleInCountries":"",
"subjects":[
{
"code":null,
"name":null
}
],
"format":"PDF",
"bisacCode":"PSY039000",
"embargoDate":null,
"bicCode":"JMC JNC",
"seriesNumber":"Volume 2",
"drmEnabled":true,
"fileSize":57589054,
"fileMd5Hash":"d298883594eb818bd17912ab0ee1e195",
"publisher":"Academic Press",
"drmRestrictions":[
{
"limited":true,
"type":"DEVICES",
"value":"5"
},
{
"limited":true,
"type":"LICENSE_DAYS",
"value":"0"
}
],
"publishedDate":"28-11-1988",
"contributors":[
{
"firstName":"Gastwirth, Joseph L.",
"lastName":""
}
]
}
Errors
A webhook publish will be in error if you respond with anything other than a 200 HTTP Response.
The response body should be EMPTY.
You must respond within 15 seconds or the publish will be considered an error.
If you fail to respond, the message will be sent again after 90 seconds, 120 seconds,for a maximum of 15 minutes. The delay between messages is based on response times, some randomness and an exponential increase in the delay.
If a webhook client accumulates more than 20 failed attempts consecutively, the client will be marked as unstable, no further requests will be sent, and our system will flag this for our support team to make contact with you.
Learn how to use Origin Voucher API.
Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.
