Using Origin Catalogue API

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:

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. 

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.