ONIX 3 RPC API Documentation
Overview
This API allows you to request ONIX 3.0 or ONIX 3.1 XML files from the Open Publishing system. You submit a JSON payload containing global configuration and a list of product records. The response is an ONIX XML file tailored to your specifications.
- Base URL:
https://api.openpublishing.com/rpc/onix3/v2
- Method:
POST
- Request Content-Type:
application/json
- Response Content-Type:
application/xml
Request Schema
Root Object
| Field |
Type |
Description |
configuration |
object |
General settings for the ONIX output → Configuration Object |
products |
array |
List of products to include in the ONIX file |
Configuration Object
Customizes ONIX output formatting, metadata structure, and feature toggles.
Basic Configuration
| Field |
Type |
Default |
Description |
version |
string |
3.0 |
ONIX version to use (3.0 or 3.1) |
type |
string |
reference |
short for short tags, reference for reference names |
codelist_issue |
string |
null |
Use specific ONIX codelist version. This parameter controls which codes are supported. If no value is specified, all the codes currently supported by the codelists will be used. Otherwise, only the codes from the specified code issue will be used. |
include_dtd_declaration |
boolean |
true |
Include ONIX DTD in the XML header. if set to true, a reference to the DTD (Document Type Definition) is included in the ONIX XML output. This is typically required by systems that validate against a DTD. |
include_namespace_declaration |
boolean |
true |
Add standard ONIX XML namespace declaration. when true, the standard ONIX XML namespace declaration is included in the output. This is generally required for schema compliance. |
include_xsi_namespace |
boolean |
false |
Include xmlns:xsi schema instance namespace (used for XML Schema Instance) is added to the ONIX document. Useful when the output must validate against an XSD schema. |
include_release |
boolean |
true |
Add ONIX release version to <ONIXMessage release="..."> |
add_comments |
boolean |
true |
Insert human-readable comments (e.g., VAT calculation context) |
sent_date_time |
integer |
current datetime |
Unix timestamp at which the ONIX is created. This value also affects data that are dependent on the time (e.g. prices). |
Price Time Scope
| Field |
Type |
Default |
Description |
include_future_prices |
boolean |
true |
Include prices scheduled for future dates |
include_past_prices |
boolean |
false |
Include historical pricing |
Tolino Features
| Field |
Type |
Default |
Description |
support_text2speech |
boolean |
false |
Indicates text-to-speech capability. Useful for accessibility features and compliant reading systems. |
support_read_in_store |
boolean |
false |
Product supports in-store reading, typically used in retail environments offering limited on-site access. |
support_tolino_family |
boolean |
false |
Product is compatible with Tolino devices. Should be enabled when targeting the Tolino ecosystem. |
support_send_previews |
boolean |
false |
Allows sending of preview content (e.g., sample chapters) to be sent or made available before purchase. |
tolino_family_concurrent_users |
integer (nullable) |
null |
Defines the maximum number of concurrent users permitted for Tolino devices, required when support_tolino_family is true. Omit or set to null if not applicable. |
Price Policy
Price Policy Object
| Field |
Type |
Description |
min_prices |
array[object] |
List of minimal prices → Price Policy > Min Price Object |
campaign_force_from |
boolean |
If true campaigns will always have a price effective from date. |
price_per_country_limit |
integer |
If set, limit the number of price nodes pre country. |
Price Policy > Min Price Object
| Field |
Type |
Default |
Description |
value |
integer (req.) |
|
Any prices lower than this value will be transmitted at this price, except for zero prices and promotional prices. |
currency |
string (req.) |
|
Currency of the price. |
gross |
boolean |
false |
The comparison of gross prices, if true, is made otherwise net. |
Text Policy
Text Policy Object
| Field |
Type |
Default |
Description |
max_length |
integer |
|
If specified, the maximum length of the text fields is set. Texts are truncated to this length. |
follow_recommendations |
boolean |
true |
Follow the recommended text lengths specified in the ONIX documentation, and truncate texts if they exceed these lengths. |
Configuration Example
"configuration": {
"version": "3.1",
"type": "reference",
"include_dtd_declaration": true,
"include_namespace_declaration": true,
"include_xsi_namespace": false,
"include_future_prices": true,
"include_past_prices": false,
"add_comments": false,
"sent_date_time": 1656654963,
"support_text2speech": true,
"support_read_in_store": true,
"support_tolino_family": true,
"tolino_family_concurrent_users": 5,
"support_send_previews": true
}
Example XML specific configuration
"configuration": {
"version": "3.0",
"include_dtd_declaration": true,
"include_namespace_declaration": true,
"include_xsi_namespace": true
}
generates the following XML header:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE ONIXMessage SYSTEM "http://www.editeur.org/onix/3.0/reference/onix-international.dtd">
<ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" release="3.0" xsi:schemaLocation="http://ns.editeur.org/onix/3.0/reference http://www.editeur.org/onix/3.0/reference/ONIX_BookProduct_Release3.0_reference.xsd">
"configuration": {
"version": "3.0",
"add_comments": true
}
generates the following comment:
<Tax>
<!-- VAT for CH on 2022-07-29: reduced (2.50%) -->
<TaxType>01</TaxType>
<TaxRateCode>R</TaxRateCode>
<TaxRatePercent>2.5</TaxRatePercent>
</Tax>
Price Policy Example
"configuration": {
"price_policy": {
"min_prices": [
{"value": 0, "currency": "BRL", "gross": false },
{"value": 1, "currency": "CNY", "gross": false },
{"value": 75, "currency": "GBP", "gross": false },
{"value": 4900, "currency": "INR", "gross": false },
{"value": 8800, "currency": "JPY", "gross": false },
{"value": 99, "gross": false }
],
"campaign_force_from": false,
"price_per_country_limit": 3
}
}
Text Policy Example
"configuration": {
"text_policy": {
"max_length": 3000,
"follow_recommendations": true
}
}
Product Object
Notes:
- For details of all ONIX codelists used in this documentation, please refer to the ONIX codelists on the Editeur's page.
- For all fields that are not required and have not been set, the values are taken from the database.
| Field |
Type |
Description |
product_id |
integer (req.) |
Unique numeric product ID |
format |
string (req.) |
One of: pod, pdf, epub, mobi, ibooks, audiobook, software |
record_reference |
string |
Value used for <a001/RecordReference> |
notification_type |
string |
ONIX code indicating update status. Used in <a002/NotificationType> (codelist 1) |
publishing_status |
string |
ONIX publishing status. Used in <b393/PublishingStatus> (codelist 64) |
record_source_type |
string |
ONIX code describing who generated the record. Used in <a194/RecordSourceType> (codelist 3) |
limit_to_countries |
array[string] |
Restrict sales rights to specific countries (codelist 91). |
product_form |
string |
ONIX product form (codelist 150) |
product_form_details |
array[string] |
Additional detail codes (codelist 175) |
product_form_features |
array[object] |
Technical features (e.g., screen reader compatibility) → Product Form Feature Object |
contributors |
array[object] |
People or organizations credited → Contributor Object |
collections |
array[object] |
Series or collections the product is part of → Collection Object |
supply_details |
array[object] |
Objects which together give details of a trade supply source and the product price and availability from that source. Supply Details |
collateral_detail |
object |
The collateral detail block covers data, all of which are primarily concerned with information and/or resources which in one way or another support the marketing of the product. |
publishing_detail |
object |
Publisher Detail Object → Publishing Detail Object |
| Field |
Type |
Description |
product_form_feature_type |
string (req.) |
ONIX code to specify the feature (codelist 79). |
product_form_feature_value |
string |
Code that describes the feature. For details, see <b335/ProductFormFeatureValue> in the ONIX 3.x documentation. |
product_form_feature_description |
array[string] |
List of descriptions for the feature. . For details, see <b336/ProductFormFeatureDescription> in the ONIX 3.x documentation. |
Contributor Object
| Field |
Type |
Description |
contributor_role |
string |
ONIX code indicating the role of the contributor (codelist 17). |
last_name |
string |
String with the last name of the contributor. |
first_name |
string |
String with the first name of the contributor. |
unnamed_persons |
string |
ONIX code allowing a positive indication to be given when authorship is unknown or anonymous, or when as a matter of editorial policy only a limited number of contributors are named (codelist 19). |
titles_before_name |
string |
String with the first part of a structured name of a person who contributed to the creation of the product: qualifications and/or titles preceding a person’s names, eg "Professor" or "HRH Prince" or "Saint". |
corporate_name |
string |
String with the name of a corporate body which contributed to the creation of the product. |
Collection Object
| Field |
Type |
Description |
collection_type |
string |
ONIX code indicating the type of a collection: publisher collection, ascribed collection, or unspecified (codelist 148). |
identifiers |
array[object] |
Indentifiers → Collection > Identifier Object |
Collection > Identifier Object
| Field |
Type |
Description |
collection_id_type |
string (req.) |
ONIX code identifying a scheme from which an identifier in the id_value element is taken (codelist 13). |
id_type_name |
string |
Name which identifies a proprietary identifier scheme (ie a scheme which is not a standard and for which there is no individual ID type code). For details, see <b233/IDTypeName> in the ONIX 3x0 documentation. |
id_value |
string (req.) |
Identifier of the type specified in the collection_id_type field. |
title_details |
array[object] |
Title details which together give the text of a collection title and specify its type → Collection > Identifier > Title Details Object |
Collection > Identifier > Title Details Object
Collection > Identifier > Title Details > Title Element Object
| Field |
Type |
Description |
title_element_level |
string (req.) |
ONIX code indicating the level of a title element: collection level, subcollection level, or product level (codelist 149). |
part_number |
string |
When a title element includes a part designation within a larger whole (eg Part I, or Volume 3), this field should be used to carry the number and its ‘caption’ as text. |
title_text |
string |
Text of a title element, excluding any subtitle. |
Supply Details Object
| Field |
Type |
Default |
Description |
supplier_role |
string |
"00" - unspecified |
ONIX code identifying the role of a supplier in relation to the product. Used in <j292/SupplierRole> (codelist 93). |
supplier_name |
string |
name of the product's imprint |
Name of a supply source from which the product may be ordered by a trade customer. Used in <j137/SupplierName>. |
product_availability |
string |
calculated from the product's availability |
ONIX code indicating the availability of a product from a supplier. Used in <j396/ProductAvailability> (codelist 65). |
prices |
array[object] |
|
Objects with price configurations Supply Details > Price Object |
Supply Details > Price Object
| Field |
Type |
Default |
Description |
price_type |
string (req.) |
|
ONIX price type code used in <x462/PriceType> (codelist 58). |
price_status |
string |
|
Price status code used in <266/PriceStatus> (codelist 61). If set to null no price status will be added to the ONIX. |
price_qualifier |
string |
|
Further price qualifiers (e.g., member price) used in <j261/PriceQualifier> (codelist 59). If set to null no price qualifier will be added to the ONIX. |
countries |
array[string] |
|
Country codes to elements which together identify a territory forming part or all of a market for which supply detail is given. Used in <x449/CountriesIncluded> in the <price/territory> nodes (codelist 91). |
territories |
array[string] |
|
Territory codes to elements which identify a territory forming part or all of a market for which supply detail is given. Currently only "WORLD" is supported. Used in <x450/RegionsIncluded> in the <price/territory> nodes (codelist 91). |
currency |
string |
curency of the countries |
ISO standard code identifying the currency in which the monetary amounts are converted. Used in <j152/CurrencyCode> (codelist 96). |
include_vat |
boolean |
true |
Include VAT in price nodes. |
include_campaigns |
boolean |
true |
Include price campaigns are added (for some ONIX recipients, price campaigns are not significant, e.g. book directories). |
price_factor |
number |
1.0 |
Value by which the prices are multiplied, for example, if prices are to be reduced for certain recipients, e.g. libraries. |
source_region_priority |
array[string] |
|
An ordered list of region codes from which the price is to be taken. A region code is either a country code or a territory code. The price is determined from the first region. If this is not available, it is determined from the next region, and so on. These prices are included in ONIX without any region specified. |
discount_coded |
object |
|
Object with discount code → Supply Details > Price Object > Discount Coded |
Supply Details > Price Object > Discount Coded
| Field |
Type |
Default |
Description |
type |
string |
02 |
Code identifying the scheme from which the value in the <DiscountCode> element is taken (codelist 100). |
type_name |
string |
|
Name which identifies a proprietary discount code. |
value |
string |
|
Discount or commission code from the scheme specified. |
Collateral Detail Object
Collateral Detail Object > Supporting Resource Object
| Field |
Type |
Description |
resource_content_type |
string (req.) |
Code indicating the type of content carried in a supporting resource (codelist 158) |
resource_mode |
string |
Code indicating the mode of the supporting resource, eg audio, video (codelist 159) |
Publishing Detail Object
Publishing Detail > Product Contatct Object
| Field |
Type |
Description |
role |
string (req.) |
Code which identifies the role played by the product contact in relation to the product – for example answering enquiries related to sales or to promotion. Used in <x482/ProductContactRole> (codelist 198). |
product_contact_name |
string |
Name of the product contact organization, which should always be stated in a standard form. Used in <x484/ProductContactName>. |
contact_name |
string |
Free text giving the name, department, phone number, etc for a contact person in the product contact organization who is responsible for the product. Used in <x299/ContactName>. |
telephone_number |
string |
Telephone number of the contact person in the product contact organization who is responsible for the product, wherever possible including the plus sign and the international dialing code. Used in <j270/TelephoneNumber>. |
email_address |
string |
E-mail address for a contact person in the product contact organization who is responsible for the product. Used in <j272/EmailAddress>. |
street_address |
string |
Street address and forming the first part of the postal address of the product contact organization. Used in <x552/StreetAddress>. |
location_name |
string |
City or town location, forming part of the postal address of the product contact organization. Used in <j349/LocationName>. |
postal_code |
string |
Postal code (postcode, zip code etc), forming part of the postal address of the product contact organization. Used in <x590/PostalCode>. |
country_code |
string |
Code identifying the country within which the product contact organization is located. Used in <b251/CountryCode> (codelist 91). |
Example: Minimalist Request
{
"configuration": {
"type": "reference",
"include_namespace_declaration": true
},
"products": [
{
"product_id": 654351,
"format": "epub"
},
{
"product_id": 713551,
"format": "pdf"
}
]
}
Example: Minimalistic Product
{
"product_id": 456355,
"format": "epub",
"supply_details": [
{
"prices": [
{
"price_type": "04",
"countries": [
"DE",
"AT",
"IT"
]
},
{
"price_type": "02",
"countries": [
"CH"
],
"currency": "CHF"
},
{
"price_type": "01",
"territories": [
"WORLD"
]
}
]
}
]
}
Example: Extended Product
{
"product_id": 456355,
"format": "epub",
"notification_type": "03",
"publishing_status": "04",
"record_source_type": "02",
"limit_to_countries": [
"DE",
"AT",
"CH",
"LI",
"PT"
],
"product_form": "ED",
"product_form_details": [
"E101",
"E200",
"E134"
],
"product_form_features": [
{
"product_form_feature_type": "06",
"product_form_feature_value": "03",
"product_form_feature_description": [
"4.1 or later",
"18pt Tiresias LP"
]
}
],
"contributors": [
{
"contributor_role": "A01",
"last_name": "Ernest",
"first_name": "Hemmingway",
}
],
"collateral_detail":
{
"supporting_resources": [
{
"resource_content_type": "01"
},
{
"resource_content_type": "02"
},
{
"resource_content_type": "03"
},
{
"resource_content_type": "05"
},
{
"resource_content_type": "27",
"resource_mode": "04"
}
]
}
},
"supply_details": [
{
"supplier_role": "01",
"supplier_name": "Publishing Company",
"product_availability": "41",
"prices": [
{
"price_type": "42",
"countries": [
"DE",
"AT",
"IT",
"CH"
],
"currency": "EUR",
"include_vat": true,
"include_campaigns": false,
"discount_coded": {
"type": "02",
"type_name": "BB",
"value": "AHACP033"
}
},
{
"price_type": "02",
"countries": [
"LI",
"CH"
],
"currency": "CHF"
},
{
"price_type": "01",
"territories": "WORLD"
},
{
"price_type": "01",
"currency": "EUR",
"source_region_priority": ["DE", "WORLD"]
}
]
}
],
"collections": [
{
"collection_type": "10",
"identifiers": [
{
"collection_id_type": "02",
"id_type_name": "Springer",
"value": "12345678"
}
],
"title_details": [
{
"title_type": "01",
"title_elements": [
{
"title_element_level": "02",
"title_text": "The Old Man and the Sea"
}
]
}
]
}
],
"publishing_detail": {
"product_contacts": [
{
"role": "02",
"contact_name": "Jesse Pinkman",
"product_contact_name": "Gray Matter Technologies",
"location_name": "Albuquerque, New Mexico",
"country_code": "US"
},
{
"role": "10",
"contact_name": "Walter White",
"product_contact_name": "Gray Matter Technologies",
"telephone_number": "ask Jesse",
"street_address": "308 Negra Arroyo Lane",
"postal_code": "87101",
"location_name": "Albuquerque, New Mexico",
"country_code": "US"
}
]
}
}
Response
- Content-Type:
application/xml
- Body: ONIX 3.0/3.1 XML document (not shown)
Error Responses
| Status |
Description |
| 400 |
Malformed request payload |
| 500 |
Internal server error |
Notes
- All [mandatory] fields are enforced
- ONIX versioning, authentication, and extended usage are documented elsewhere
- All field values must comply with standard ONIX codelists, though validation is not enforced here