Developer reference for the data feed to Shopify.

Consonance can be a data provider to a Shopify store, by pushing data to its API endpoints which is then accessible via its Liquid markdown templates.

I am not a developer – what does this mean?

We sometimes take on projects to set up our clients’ Shopify stores, but we much prefer you to find a developer who can use this documentation to set up your store with a Consonance feed for you. Find a list of Shopify developers here.

This article provides the details about which Consonance information goes to which Shopify fields.

1. Metafields

Shopify is not a book publishing specific ecommerce solution and so there isn’t a direct mapping of some of the more publishing-specific data from Consonance to Shopify, such as ISBN13, series name and copyright notices. However, Shopify has metafields. We use metafields, scoped on Shopify products, to provide access to publishing-specific data.

The table below gives all the metafields that Consonance generates. Some of the metafield keys are dynamically named: in the table, we’ve shown how they are generated using the Ruby string interpolation syntax #{...}.

If data is missing, the metafield value is not nil, but a meaningful string such as Unknown or No authors.

All the values below are Strings.

Key Example data (value) Consonance location
Size 129 x 198mm Generated from measurements data section on Metadata page
Format Paperback From format data section on Metadata page
ISBN 9781905005123 From top of Metadata page
Publication 1 October 2017 From top of Metadata page
Series The Black Road 2 From the series section of the Metadata page
Pages 416 From the extents section of the Metadata page
Subtitle From there to here From the title section of the Metadata page
Copyright 2016 From the copyright date field on the contract page
Edition Abridged and illustrated edition From the edition statement field on the Metadata page
Illustrations 153 illustrations and 23 woodcuts Generated from the illustrations section of the Metadata page
pretty_contacts Edited by Emma Barnes with a foreword by David Aldridge et al. Concatenates all the contributor names grouped by roles into a humanized sentence, or alternatively uses the online authorship description from the Metadata > Contributors section
tableofcontents 01 Preface02 Introduction03 … Generated from the Metadata page marketing text page
short_blurb A fine book about owls. Generated from the Metadata page marketing text page, main type of 02 Short description
keysellingpoints Everyone loves owls Published in time for OwlFest ‘17 Promotional budget available. Generated from the Metadata page marketing text page, main type of Key Selling Points
long_blurb [Long descriptive text] Generated from the Metadata page marketing text page, main type of Long Description
blurb [Medium length descriptive text] Generated from the Metadata page marketing text page, main type of Description
bio_text Emma Barnes was born in England and now lives in England. Generated from the Metadata page marketing text page, main type of Biographical note
market_exclusions Only for sale in: Wales, Scotland, Algeria Generated from market exclusions in the contract
#{author_name}[0..29] [Biographical note] The key to this metafield is the first 28 characters of the author’s name. The value is the biographical note from the contact’s edit page (not from the product).
#{review}_#{i} where i is the index of the count of the total reviews. #{marketing_text.pull_quote}
#{marketing_text.contact}   #{marketing_text.publication_name}
#{marketing_text.publisher}
e.g.A great book Bob Cratchett, Financial Times FT.com
Generated from the marketing texts marked as Reviews.

2. Tags

Consonance constructs metatags for use in the meta section of Shopify’s pages, for selection by tag type and for use in some of the search filter plugins that are available.

Some of the tags are dynamically named: in the table, we’ve shown how they are generated using the Ruby string interpolation syntax #{...}.

Tag Example Consonance location
Subject#{work.mainsubject[0]}-#{work.main_subject.gsub(/[^0-9a-z ]/i, “) } Subject_A-archaeology Metadata > Subjects
product.tag_list lemmings, teeth, rocks Metadata > Subjects > Keywords
Edition#{product.proprietaryeditiondescriptionname[0]}-#{product.proprietaryeditiondescription_name} P-Paperback Metadata > Format
Age range#{product.work.agerangecode.try(:proprietaryagerange).try(:sequence)}-#{product.work.agerangecode.try(:proprietaryagerange).try(:tos)} Age range113+ Metadata > Subjects
product.augmentededitiontype_codes SPE (for special edition). other options:MDTADPUNNNEDDGO Metadata > Editions
Price#{product.priceband.try(:sequence)}-#{product.price_band.try(:name)} PriceA0-5.99 Metadata > Price
Series The Black Road Metadata > Series
Contributor.to_s Robert Smith Metadata > Contributors
product_type Paperback Metadata > Format

3. Shopify variants

The variants model that Shopify provides is too restrictive for publishing. For example, there might be different reviews, descriptive text, illustration detail or contributors for an ebook and a hardback. Critically, you don’t apply different tax treatments to variants, so that means we couldn’t sell ebooks legally in the EU. So make each Consonance product a Shopify product.

That said, for each product in Shopify there must be at least one variant, so we send over the following data.

Shopify variant attribute Example Consonance location
Barcode 9781905005123 Metadata page
requires_shipping true From Metadata > format, Consonance establishes by format whether it is a physical product.
taxable false !book.isphysicalproduct?
price 7.99 Prices in local currency amount

I rely on the variant ID for my integration!

Some services use the variant ID as well as the product ID, e.g. EditionGuard the DRM enforcement service. Consonance’s data push ensures that the variant ID will not change when a product is updated. We mention this because if you update a variant through the product association (using the Shopify_api Ruby gem), the variant is destroyed and another created, rather than updating. Ticket.

4. Deleting products and collections

Consonance does not send a DELETE notification to the product or collection endpoints on Shopify. If a product or collection should be unpublished from Shopify, Consonance sets the Shopify product or collection attribute published_at and published_scope to nil.

5. Shopify products

Most of the product metadata is contained in metafields, but there are also some Shopify product attributes which Consonance posts data to.

Shopify product attribute Example Consonance location
handle 354672 Consonance’s unique product ID, assigned by the system
title The Great Escape Metadata page > title
product_type PaperbackUnknown Metadata page > format

Here is an example of the product data and its metafields that is sent to Shopify from Consonance.

Fbcd0f7 screen shot 2016 12 07 at 14.41.52

6. Collections

Consonance creates a range of Shopify Custom Collections.

Shopify documentation on custom collections is here: https://help.shopify.com/api/reference/customcollection

Custom Collection handle Example Consonance location
latest-products - Generated automatically
coming-soon - Generated automatically
#{work title} - Metadata > title
category_#{work.subject.parent} History Metadata > Subjects > In house. If this code has a parent, the product is added to this parent collection as well as the child.
subjectcategory#{work.subject.parent}{work.subject} Ancient history Metadata > Subjects > In house primary and additional
subject_category#{work.subject} Ancient history Metadata > Subjects > In house > primary and additional
subject_#{work.subject} Ancient history Metadata > Subjects > In house > primary and additional
series-#{series_name} series-Black-Road Metadata > Series
contact-#{contact.id} contact-60894 Generated automatically
#{imprint} Snowbooks Metadata > Imprint
#{category} Sports and Fitness Metadata > Subjects > In house
#{contact} Marc Smith Metadata > contributors