Over the upcoming weeks we will make several changes pertaining to the transmission of ebook metadata in ONIX 3.0 and proprietary XML feeds.


These changes may require verifications or adjustments on your part. To avoid any problematic situations, please read the following documentation regarding these changes so you may be aware of any possible impact they may have on your interpretation of the ONIX 3.0 and proprietary XML feeds. It is likely that you will have to take certain actions.


The deployment of the changes will take place in two waves.


On August 13 (low-impact changes):

1. Presence of more than one <ProductSupply> tag in a single product description and introducing the concept of markets

2. New “country” and “currency” parameters in the Sales API

3. Formatting text in an author’s biography


On September 30 (changes that require specific attention):

4. New display for publications during pre-order period

5. Information on territories withdrawn from sale

6. Sale start date removed from the first active price in ONIX feeds

7. “Country” and “currency” parameters in Sales API become mandatory



DEPLOYING ON AUGUST 13


An initial wave of low impact changes will be deployed on August 13.


1. Presence of more than one <ProductSupply> tag in a single product description and introducing the concept of markets

At the moment, Cantook supplies only one ProductSupply tag per publication, which includes all prices. The ONIX standard for best practices instead recommends that all prices of a publication be grouped into a ProductSupply tag according to market parameters, including the sale start date. Moreover, Market / Territory / CountriesIncluded tags will be added in order to define the territories related to each ProductSupply.


In accordance with this recommendation, you may find several ProductSupply tags in a single publication’s ONIX file following the deployment. To get the correct information about your market in the right ProductSupply tag, make sure to check that the expected country is included in the Market / Territory / CountriesIncluded tag (recommended) or to take all Price tags into account under ProductSupply since the Territory / CountriesIncluded tag remains there.


The image below showcases those changes:

 



2. New “country” and “currency” parameters in the Sales API

The “country” and “currency” parameters have been added to the Simulating a sale and Sales APIs. The use of these parameters is as follows:

  • country: the country of the customer (ISO 3166-1 Alpha-3 (can, fra, ita) or Alpha-2 (CA, FR, IT) format)

  • currency: the currency of the sale (ISO 4217 format)


This information can be recovered in the Price tag of the ONIX 3.0 feed.


Here is an example of a Sales API call. The new parameters are in green:

POST https://[domaine]/api/organisations/1/publications/9780000000001/sales?format=pdf&cost=199&protection=watermark&customer_id=usr1&transaction_id=tx1&country=can&currency=cad


Note: The use of these parameters will become mandatory following the second deployment have planned for September 30 (see section 7 below). The documentation on Sales API has been updated with this new information.



3. Formatting text in an author’s biography

As with the Summary of the publication field, the <BiographicalNote> field, which contains biographical notes of a title’s contributors, now supports HTML tags for text formatting (bold, underline, italics, etc.).


Example:

<BiographicalNote>

<![CDATA[Author’s biography <em>formatted</em>.]]>

</BiographicalNote>




DEPLOYMENT OF SEPTEMBER 30


The second wave of changes will be deployed on September 30 and will require more specific attention on your part. Matter-of-factly, these changes may have an impact on your interpretation of the ONIX feeds.



4. New display for publications during pre-order period

See CantookONIXChanges4PreorderState.onix sample file attached.


Publications available for pre-order used to be presented as unavailable in the metadata feeds. Some changes will be applied in order to better clarify the way publications available for pre-order are displayed.


The changes in ONIX 3.0 feeds will affect the tags supplying the availability and the sale dates. Availability indicators will become active during the pre-order period:

  • the PublishingDetail/PublishingStatus tag will use the 04 -Active- value (which was 08 -Inactive- or 11 -Withdrawn from sale- before)

  • the PublishingDetail/SalesRights/SalesRightsType tag will use the 01 -For sale with exclusive rights in the specified countries or territories- value (which was 03 -Not for sale in the specified countries or territories (reason unspecified)- before)

  • the ProductSupply/SupplyDetail/ProductAvailability tag will use the 20 -Available- value (which was 40 -Not available (reason unspecified)- before)


Date tags will allow to indicate if the publication is on pre-order or for sale:

  • The sale start date will be added to the PublishingDetail/PublishingDate tag, in which the PublishingDateRole tag will use the 02 -Embargo date- value. During the pre-order period, this tag will contain a future date that corresponds to the sale start date. A copy of that same date will remain available in the ProductSupply / SupplyDetail / SupplyDate tag, in which the SupplyDateRole tag uses the 08 -Expected availability date- value

  • The pre-order start date (optional) remains in the PublishingDetail/PublishingDate tag in PublishingDateRole and uses the 09 -Public announcement date- value


Since the availability indicators for pre-order publications will now be positive—they used to be negative—only one element will differentiate a publication available for pre-order from a publication available for sale: The presence of a future sale start date in the PublishingDetail/PublishingDate/PublishingDateRole tag using a 02 value. If a pre-order start date (optional) is indicated as well, it must be duly observed.


Before the pre-order period, the availability indicators will stay negative.


Changes regarding how publishing details are displayed can be summed up with the following timeline:

 


The tags used to indicate availability, pre-order dates and sale dates are explained above.


In proprietary XML feeds, the format / state tag will now use the preorder value (which was view before).



5. Information on territories withdrawn from sale

See CantookONIXChanges5MarketRemoval.onix sample file attached.


In order to ensure a way to deactivate sales on a territory where a publication is no longer available for sale, we will continue to communicate inactive prices for a certain period of time after withdrawing the territory. These inactive prices will be grouped in a ProductSupply tag, which will contain the additional MarketPublishingDetail/MarketPublishingStatus tag using the 11 -Withdrawn from sale- values.


You may choose to ignore this ProductSupply tag but you may use it to ensure sales have been correctly deactivated on a territory where the publication is not for sale anymore. The inactive prices will be delivered in ONIX 3.0 only.


For instance, the Canadian market (CA) has been removed from the example below. The ProductSupply tag is therefore added and will be sent in the synchronisation feed for a certain period of time after the withdrawal. The values in blue indicate the deactivation:


<ProductSupply>

  <Market>

    <Territory>

      <CountriesIncluded>CA</CountriesIncluded>

    </Territory>

  </Market>

  <MarketPublishingDetail>

    <MarketPublishingStatus>11</MarketPublishingStatus>

    <MarketDate>

      <MarketDateRole>01</MarketDateRole>

      <DateFormat>00</DateFormat>

      <Date>20150101</Date>

    </MarketDate>

  </MarketPublishingDetail>

  <SupplyDetail>

    <Supplier> … <Supplier>

    <ProductAvailability>40</ProductAvailability>

    <SupplyDate> … </SupplyDate>

    <Price> … CA - CAD … </Price>

  </SupplyDetail>

</ProductSupply>



6. Sale start date removed from the first active price in the ONIX feeds

See CantookONIXChanges6CurrentPriceStartDateRemoval.onix sample file attached.


Since the prices are now grouped in a ProductSupply tag according to a sale start date for a given market (see the “Presence of more than one <ProductSupply> tag in a product description and introducing the concept of markets” article in the August 13 deployment section above), the sale start date for active prices (currently in the Price / PriceDate / PriceDateRole tag using a 14 value) will be removed. A price without a sale start date will therefore be considered as immediately active (except if the price's ProductSupply / MarketDate is in the future). If a future price is present, it will have a sale start date and the active price will have a sale end date.


The example below is of an active price. The red tags will no longer be delivered in the ONIX feeds:

<Price>

<PriceType>04</PriceType>

<PriceQualifier>05</PriceQualifier>

<PriceStatus>02</PriceStatus>

<PriceAmount>0,99</PriceAmount>

<CurrencyCode>EUR</CurrencyCode>

<Territory>

<CountriesIncluded>FR</CountriesIncluded>

</Territory>

<PriceDate>

<PriceDateRole>14</PriceDateRole>

<DateFormat>14</DateFormat>

<Date>20150703T113740-0400</Date>

</PriceDate>

</Price>



7. “Country” and “currency” Sales API parameters become mandatory

In order to clarify sales reporting and sales data exchange, the “country” and “currency” parameters in the Simulating sale and Sales APIs will become mandatory as of this deployment.



It's always a pleasure to answer your questions. Do not hesitate to contact our technical support service at help@cantook.net for any additional information.


Best regards,

The De Marque team