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. 



Webhook publish

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
YesThe date the product is/was published.
embargoDate
YesThe 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.