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 'Authorization: Bearer XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX' \
  --header 'content-type: application/json' \
  --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. The table below has been alphabetized for ease of reference. 


Field NameDescriptionCan this be NULL?
availabilityThe availability status of the asset. It can be either "UNAVAILABLE" or "AVAILABLE".No
bicCodeThe BIC code of the asset.Yes
bisacCodeThe BISAC code of the asset.Yes
categoriesThe categories of the asset.Yes
contributorsThe contributors of the asset.Yes
copyrightThe copyright of the asset.Yes
createdDateThe date when the asset was created.No
currencyThe currency of the asset's price.No
descriptionThe description of the asset.Yes
drmEnabledA boolean indicating whether DRM restrictions are enabled for the asset.No
drmRestrictionsThe DRM restrictions of the asset.Yes
editionThe edition of the asset.Yes
embargoDateThe embargo date of the asset.Yes
etagThe ETag of the asset.Yes
excludedForSaleInCountriesThe countries where the asset is excluded for sale.Yes
fileSizeThe size of the asset file.Yes
formatThe format of the asset.No
freeA boolean indicating whether the asset is free.No
gradeLevelThe grade level of the asset.Yes
idThe unique identifier of the store asset.No
identifierThe identifier of the asset.No
imageMd5HashThe MD5 hash of the asset's image.Yes
imageUrlThe URL of the asset's image.Yes
includedForSaleInCountriesThe countries where the asset is included for sale.Yes
languageThe language(s) of the asset.No
numberOfPagesThe number of pages in the asset.Yes
priceThe price of the asset.Yes
publishedDateThe date the asset was published.Yes
publisherThe publisher of the asset.Yes
relatedIdentifierThe related identifier of the asset.Yes
sentDateTimeThe timestamp when the payload was sent.No
seriesNameThe name of the series the asset belongs to.Yes
seriesNumberThe number of the series the asset belongs to.Yes
subjectThe subject of the asset.Yes
subjectsThe subjects of the asset.Yes
subTitleThe subtitle of the asset.Yes
supplierThe supplier of the asset, represented as a map with "label" and "code" keys.No
titleThe title of the asset.No
updatedDateThe date when the asset was last updated.No


JSON product example

The following depicts the structure of a single product:

{
    "id": 123,
    "availability": "AVAILABLE",
    "identifier": "asset123",
    "relatedIdentifier": "relatedAsset123",
    "format": "pdf",
    "title": "Asset Title",
    "subTitle": "Asset Subtitle",
    "drmEnabled": true,
    "numberOfPages": 200,
    "language": "English, Spanish",
    "edition": "1st",
    "description": "This is a description of the asset.",
    "publisher": "Publisher Name",
    "subject": "Subject Name",
    "categories": [
        {
            "id": 1,
            "label": "Category 1",
            "parent": null
        }
    ],
    "imageMd5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "imageUrl": "http://example.com/image.jpg",
    "publishedDate": "01-01-2022",
    "embargoDate": "01-01-2023",
    "price": 9.99,
    "currency": "USD",
    "supplier": {
        "label": "Supplier Name",
        "code": "SUP123"
    },
    "copyright": "Copyright 2022",
    "fileSize": 1024,
    "gradeLevel": "Grade 1",
    "bicCode": "BIC123",
    "bisacCode": "BISAC123",
    "seriesName": "Series Name",
    "seriesNumber": "1",
    "includedForSaleInCountries": "US,UK",
    "excludedForSaleInCountries": "CA,AU",
    "subjects": [
        {
            "code": "Subject Code",
            "name": "Subject Name"
        }
    ],
    "drmRestrictions": [
        {
            "type": "PRINTABLE",
            "value": "10",
            "limited": true
        }
    ],
    "contributors": [
        {
            "firstName": "John",
            "lastName": "Doe"
        }
    ],
    "sentDateTime": 1646146800000,
    "createdDate": "2022-01-01T00:00:00Z",
    "updatedDate": "2022-02-01T00:00:00Z",
    "etag": "3f786850e387550fdab836ed7e6dc881e2dd63ec",
    "free": false
}


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.