Products v4
This page documents the CRUD operations for products: creating, retrieving, updating and deleting them, together with every field of the product representation.
A product is a single published work in all the forms it is sold in — ebook, printed book, print on demand, audiobook, or non-book article. One product holds the shared bibliographic metadata and lists the formats and product types actually activated, so an EPUB and its print-on-demand edition are one product rather than two.
Prices, files, suppliers, publishing dates and storefront assignments are managed through the sub-resources linked from _links rather than on the product itself.
The product representation is deliberately lean. It carries identity, titles, status, language, product formats, EANs, imprint and ownership. Descriptive and format-specific metadata — abstract, contributors, keywords, subject categories, print-on-demand settings, prices, publishing dates, series and sets — is not part of the product itself and is reached through the sub-resources linked from _links.
Endpoints
GET /resource/v4/products
Retrieve a list of products
Description
Returns a page of products belonging to the calling realm.
Most filters accept the operator suffixes described in Resource Queries. Where a filter is equality-only that is noted on the parameter.
Input parameters
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
bisac |
string | No | Filter by BISAC subject code assigned to the product (e.g. `HIS002000`). | |
brand_id |
string | No | Filter by the id of a storefront the product is offered in. | |
business_partner_id |
string | No | Filter by the id of an associated business partner (author or contributor). | |
category_id |
string | No | Filter by academic category id. | |
created |
string | No | Filter on the creation date, compared as a date rather than a timestamp. Accepts the comparison and range operators, e.g. `?created__gte=2026-01-01` or `?created__range=2026-01-01,2026-06-30`. | |
doi |
string | No | Filter by DOI, matched exactly. Equality only. | |
ean |
string | No | Filter by EAN, matched exactly against any EAN assigned to the product. Given as 13 digits without hyphens. | |
external_identifier_type |
string | No | Filter by the scheme name of a proprietary identifier. Equality only. | |
external_identifier_value |
string | No | Filter by the value of a proprietary identifier. Equality only. **Used on its own it additionally requires the identifier to have no type**; combining it with `external_identifier_type` searches typed identifiers. | |
imprint_id |
string | No | Filter by the id of the product's imprint. | |
keyphrase |
string | No | Searches the product's search text, and accepts the full operator syntax — `?keyphrase__startswith=hansestadt` works, unlike `q`. It also accepts an **object reference**, which names a single product directly: - `v190` — the product whose `_legacy_id` is 190. The letter identifies the object type (`v` for a product), the digits the identifier. - `document.190` — the same product in the longer `type.id` form. - `190` — a bare number is also read as a `_legacy_id`. - an EAN or ISBN. The reference is **combined** with the text match rather than replacing it: the result set is everything matching the text *or* the product the reference names. That differs from `q`, where a recognised reference returns only that one product and no text search is performed. | |
label |
string | No | Filter by label. The value is normalised before matching, and only `=`, `__contains` and `__startswith` are accepted. | |
language |
string | No | Filter by language, given as the ISO 639-2/B three-letter code (e.g. `ger`, `eng`). Equality only. An unknown code matches nothing. | |
main_subject_id |
string | No | Deprecated. Retained only for backwards compatibility; use `subject_id` instead. | |
page |
integer | No | One-based page number to return. Following the next link in the response is preferable to incrementing this value. | |
page_size |
integer | No | Number of products per page. An unfiltered product collection can be large, so it is retrieved page by page rather than in a single request. | |
q |
string | No | Full-text search across the product's text fields. It also accepts an **object reference**, which names a single product directly instead of searching for it. A recognised reference returns that one product rather than a set of text matches: - `v190` — the product whose `_legacy_id` is 190. The letter identifies the object type (`v` for a product), the digits the identifier. - `document.190` — the same product in the longer `type.id` form. - an EAN or ISBN, for example `9783161484100`. A value that is not recognised as an object reference is searched as text. Note the difference from `keyphrase`: here a recognised reference **replaces** the search and returns only that one product, whereas `keyphrase` returns the text matches *and* the reference hit together. `q` ignores operator suffixes. | |
realm_id |
string | No | Filter by realm id. Only useful to callers whose scope spans more than one realm. | |
status |
string | No | Filter by publication status. Matched case-insensitively, so "published" and "PUBLISHED" are equivalent. See the status field of the product schema for what each value means. | |
subject_id |
string | No | Filter by the id of a publisher subject assigned to the product. | |
thema |
string | No | Filter by Thema subject code assigned to the product (e.g. `NHC`). | |
title |
string | No | Filter on the normalised product title. Supports the operator suffixes, e.g. `?title__contains=teppich`. |
Responses
{
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products?status=deleted&page_size=25",
"first": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=1&page_size=25",
"prev": "string",
"next": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=2&page_size=25",
"last": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=6324&page_size=25"
},
"_pagination": {
"page": 1,
"page_size": 25,
"total": 158091
},
"items": [
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object",
"description": "Ready-made URLs for walking the result set. They carry the current filters forward, so following them is preferable to assembling page URLs by hand.",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "The current request, without a page number.",
"example": "https://api.openpublishing.com/resource/v4/products?status=deleted&page_size=25"
},
"first": {
"type": "string",
"description": "First page of the result set.",
"example": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=1&page_size=25"
},
"prev": {
"type": "string",
"description": "Previous page, or null when this is the first page.",
"nullable": true
},
"next": {
"type": "string",
"description": "Next page, or null when this is the last page. Stop paging when it becomes null.",
"nullable": true,
"example": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=2&page_size=25"
},
"last": {
"type": "string",
"description": "Last page of the result set.",
"example": "https://api.openpublishing.com/resource/v4/products?status=deleted&page=6324&page_size=25"
}
}
},
"_pagination": {
"type": "object",
"description": "Where this page sits in the full result set. Note that total counts every product matching the filter, not the number returned in items.",
"additionalProperties": false,
"properties": {
"page": {
"type": "integer",
"description": "One-based index of the page returned.",
"example": 1
},
"page_size": {
"type": "integer",
"description": "Number of products per page, as set by the page_size query parameter.",
"example": 25
},
"total": {
"type": "integer",
"description": "Total number of products matching the filter across all pages. The number of pages is this value divided by page_size.",
"example": 158091
}
}
},
"items": {
"type": "array",
"description": "The products on this page. Empty when the filter matches nothing; never null.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
POST /resource/v4/products
Create a new product
Description
Creates a product. A title is required. An imprint is assigned by sending only its _id; EANs and formats may be set on creation or added afterwards.
Request body
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
Responses
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
GET /resource/v4/products/{id}
Retrieve a single product by ID
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | The product's UUID, as returned in _id. The legacy integer identifier is not accepted here. |
Responses
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
PUT /resource/v4/products/{id}
Update product
Description
Updates a product. Fields omitted from the request body are left unchanged. The status field is applied last, after all other fields, so a product can be completed and published in a single request.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | The product's UUID, as returned in _id |
Request body
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
Responses
{
"_id": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"_version": "4.0",
"_legacy_id": 12345,
"_links": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"title": "Der unsignierte Teppich",
"subtitle": "Ein Fall fuer Juli Sanwald",
"status": "PUBLISHED",
"language": "eng",
"formats": [
"pdf",
"pod"
],
"product_types": [
"ebook",
"book"
],
"eans": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"imprint": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"labels": [
"autumn-campaign",
"cover-missing"
],
"cover_url": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp",
"external_identifiers": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"created": 1735689600,
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"identifiers": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"doi": "10.5555/9783161484100",
"has_been_published": true,
"shop_url": "https://www.example.com/document/12345"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests.",
"example": "3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
},
"_version": {
"type": "string",
"description": "API version that produced this representation.",
"example": "4.0"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id.",
"example": 12345
},
"_links": {
"type": "object",
"description": "URLs of this product's sub-resources, plus the product itself under \"self\". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files"
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"title": {
"type": "string",
"description": "Main title of the product, without the subtitle. Always present: a product cannot be created without a title.",
"example": "Der unsignierte Teppich"
},
"subtitle": {
"type": "string",
"description": "Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it.",
"nullable": true,
"example": "Ein Fall fuer Juli Sanwald"
},
"status": {
"type": "string",
"description": "Whether the product is currently for sale. Returned in upper case, and\nmatched case-insensitively when writing, so both `published` and\n`PUBLISHED` are accepted on POST and PUT.\n\n* `NEW` — the product is not currently for sale. This covers a product that\n has just been added, and one that has been withdrawn until something is\n resolved.\n* `PUBLISHED` — the product is currently for sale.\n* `UNPUBLISHED` — the product was on sale and its publication has since been\n revoked, so it is not currently for sale. Writing this value revokes the\n publication, and is accepted only while the product is `PUBLISHED`.\n* `DELETED` — the product has been permanently withdrawn.\n\nA product that is not for sale can be published later, or deleted\npermanently. Publishing through the API applies no metadata completeness\ncheck, so a product can be published while its metadata is still\nincomplete. Status describes only the present; whether a product has ever\nbeen on sale is reported by `has_been_published`.",
"example": "PUBLISHED"
},
"language": {
"type": "string",
"description": "Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: \"ger\" for German rather than \"deu\", \"fre\" for French rather than \"fra\", and \"dut\" for Dutch rather than \"nld\". Null when no language has been set.",
"nullable": true,
"example": "eng"
},
"formats": {
"type": "array",
"description": "Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. \"pdf\", \"epub\", \"mobi\" and \"ibooks\" are ebook file formats. \"pod\" is print on demand, where each copy is manufactured per order, while \"edition_print\" is a conventionally printed edition held in stock. \"audiobook\" is the audio edition and \"nonbook\" covers merchandise and other non-book articles. This is finer-grained than product_types: \"pdf\" and \"epub\" are both formats of the single product type \"ebook\". An empty array means no product format has been activated yet.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"edition_print",
"audiobook",
"nonbook"
]
},
"example": [
"pdf",
"pod"
]
},
"product_types": {
"type": "array",
"description": "Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. \"ebook\" appears when any ebook file format is active, and \"book\" when a printed edition is active, whether print on demand or a stocked print run. \"audiobook\" and \"nonbook\" mirror the formats of the same name.",
"items": {
"type": "string",
"enum": [
"ebook",
"book",
"audiobook",
"nonbook"
]
},
"example": [
"ebook",
"book"
]
},
"eans": {
"type": "array",
"description": "EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article.",
"example": [
{
"ean": "9783161484100",
"isbn": "978-3-16-148410-0",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
]
},
{
"ean": "9783161484117",
"isbn": "978-3-16-148411-7",
"formats": [
"pod"
]
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "13-digit EAN, without hyphens. This is the number trade partners order by.",
"example": "9783161484100"
},
"isbn": {
"type": "string",
"description": "The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on.",
"nullable": true,
"example": "978-3-16-148410-0"
},
"formats": {
"type": "array",
"description": "Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list \"epub\" or \"mobi\" even when those formats do not appear in the product's formats array. Stocked print editions share the \"pod\" entry, so \"edition_print\" never appears here.",
"items": {
"type": "string",
"enum": [
"pdf",
"epub",
"mobi",
"ibooks",
"pod",
"audiobook",
"nonbook"
]
},
"example": [
"epub",
"ibooks",
"mobi",
"pdf"
]
}
}
}
},
"imprint": {
"type": "object",
"description": "Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained.",
"example": {
"_id": 42,
"imprint_name": "Zeilenquarz Verlag",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH",
"country": "DE",
"phone": "+49 123 4567890",
"email": "rechte@example.com",
"gln": "4012345678901"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Open Publishing identifier of the imprint.",
"example": 42
},
"_links": {
"type": "object",
"description": "URL of the full imprint resource.",
"example": {
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
}
},
"imprint_name": {
"type": "string",
"description": "Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint.",
"nullable": true,
"example": "Zeilenquarz Verlag"
},
"publisher_name": {
"type": "string",
"description": "Legal or trading name of the publisher, which may differ from the imprint name.",
"nullable": true,
"example": "Zeilenquarz Verlagsgruppe GmbH"
},
"city": {
"type": "string",
"description": "City of publication of the imprint, the place of publication carried in bibliographic metadata.",
"nullable": true,
"example": "Rheinbergen"
},
"country": {
"type": "string",
"description": "Country of the publisher as an ISO 3166-1 alpha-2 code.",
"nullable": true,
"example": "DE"
},
"phone": {
"type": "string",
"description": "Publisher contact telephone number.",
"nullable": true,
"example": "+49 123 4567890"
},
"fax": {
"type": "string",
"description": "Publisher contact fax number, retained for trade partners that still exchange orders by fax.",
"nullable": true,
"example": "+49 123 4567899"
},
"email": {
"type": "string",
"description": "Publisher contact email address.",
"nullable": true,
"example": "rechte@example.com"
},
"gln": {
"type": "string",
"description": "Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party.",
"nullable": true,
"example": "4012345678901"
}
}
},
"labels": {
"type": "array",
"description": "Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping.",
"items": {
"type": "string"
},
"example": [
"autumn-campaign",
"cover-missing"
]
},
"cover_url": {
"type": "string",
"description": "URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail.",
"nullable": true,
"example": "https://cdn.openpublishing.com/thumbnail/products/12345/large.webp"
},
"external_identifiers": {
"type": "array",
"description": "Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with `external_identifier_type` and `external_identifier_value`.",
"example": [
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are \"asin_book\" and \"asin_ebook\" for Amazon, \"apple\", and a bare product format such as \"epub\" or \"pdf\". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system.",
"nullable": true,
"example": "asin_ebook"
},
"value": {
"type": "string",
"description": "The identifier as used by that system.",
"example": "B0C1D2E3F4"
}
}
}
},
"created": {
"type": "integer",
"description": "When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work.",
"nullable": true,
"example": 1735689600
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"identifiers": {
"type": "object",
"description": "ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats.",
"example": {
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
},
"additionalProperties": false,
"properties": {
"isbns": {
"type": "object",
"description": "One entry per product format that has an ISBN assigned, keyed by \"pdf\", \"epub\", \"mobi\", \"ibooks\", \"pod\", \"audiobook\" or \"nonbook\". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one.",
"example": {
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
},
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"ean": {
"type": "string",
"description": "The 13-digit EAN assigned to this product format.",
"example": "9783161484100"
},
"type": {
"type": "string",
"description": "ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by \"::\". Registering an EAN as \"ebook\" assigns it to every ebook format at once; registering one as \"ebook::pdf\" assigns a distinct EAN to the PDF alone. The coarse types are \"book\", \"ebook\", \"audiobook\" and \"nonbook\"; the granular ebook types are \"ebook::pdf\", \"ebook::epub\", \"ebook::mobi\" and \"ebook::ibooks\". Both levels occur, so matching on the part before \"::\" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set.",
"example": "ebook::epub"
}
}
}
}
}
},
"doi": {
"type": "string",
"description": "Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution.",
"nullable": true,
"example": "10.5555/9783161484100"
},
"has_been_published": {
"type": "boolean",
"description": "Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale.",
"example": true
},
"shop_url": {
"type": "string",
"description": "Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present.",
"nullable": true,
"example": "https://www.example.com/document/12345"
}
},
"required": []
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
DELETE /resource/v4/products/{id}
Delete product by ID
Description
Withdraws the product from distribution and publication. Setting status to UNPUBLISHED is preferable when the product may return, since a product that has_been_published may already be referenced by trade partners.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | The product's UUID, as returned in _id |
Responses
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Schemas
Product
| Name | Type | Description | Example |
|---|---|---|---|
_id |
string |
Stable UUID assigned by Open Publishing. It never changes over the lifetime of the product, and is the identifier used in all v4 requests. |
3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3 |
_legacy_id |
integer |
Legacy integer identifier of this product, kept so existing integrations can correlate their own records. Read-only; the product is addressed by the UUID in _id. |
12345 |
_links |
object |
URLs of this product's sub-resources, plus the product itself under "self". Always contains contacts, copyright_statements, files, form_features, identifiers, prices, publishing_dates, storefronts, subjects, suppliers, texts and titles. Following these links is preferable to assembling sub-resource URLs by hand; the descriptive and format-specific metadata that is not part of the product itself is reached through them. |
{
"files": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/files",
"prices": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3/prices",
"self": "https://api.openpublishing.com/resource/v4/products/3f8c1a52-9b7d-4e16-8a0c-2d5f7e91b4c3"
} |
_version |
string |
API version that produced this representation. |
4.0 |
business_partner |
Properties: _id, _legacy_id, _links, screenname| null |
Reference to business partner |
{
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
} |
business_partner._id |
string |
Business Partner ID |
eeee04ea-2752-40f5-a29d-3d67a77ba82c |
business_partner._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
business_partner._links |
object | ||
business_partner.screenname |
string |
Display name of business partner |
Michael Scarn |
cover_url |
string| null |
URL of the full-size cover image, or null if no cover has been uploaded. This is the large rendition rather than a thumbnail. |
https://cdn.openpublishing.com/thumbnail/products/12345/large.webp |
created |
integer| null |
When the product record was created, in seconds since the Unix epoch (UTC). This is the creation of the record in Open Publishing, not the publication date of the work. |
1735689600 |
doi |
string| null |
Digital Object Identifier registered for the product, or null if there is none. A DOI is a citable, permanent reference to the product, expected in academic and library distribution. |
10.5555/9783161484100 |
eans |
Array<Properties: ean, isbn, formats> |
EANs assigned to this product, each mapped to the formats it identifies. Trade partners order by EAN, so a product may carry one EAN per commercially distinct format group; a single EAN may cover several formats where they are sold as one article. |
[
{
"ean": "9783161484100",
"formats": [
"epub",
"ibooks",
"mobi",
"pdf"
],
"isbn": "978-3-16-148410-0"
},
{
"ean": "9783161484117",
"formats": [
"pod"
],
"isbn": "978-3-16-148411-7"
}
] |
eans[].ean |
string |
13-digit EAN, without hyphens. This is the number trade partners order by. |
9783161484100 |
eans[].isbn |
string| null |
The same number in hyphenated ISBN-13 presentation form, or null if no ISBN-13 is registered. A presentation form only; ean is the value sent and matched on. |
978-3-16-148410-0 |
eans[].formats |
Array<string> |
Product formats this EAN is registered for. These are ISBN assignments and are independent of the product's activated formats, so an EAN may list "epub" or "mobi" even when those formats do not appear in the product's formats array. Stocked print editions share the "pod" entry, so "edition_print" never appears here. |
[
"epub",
"ibooks",
"mobi",
"pdf"
] |
external_identifiers |
Array<Properties: type, value> |
Identifiers for this product in third-party systems, for example an Amazon ASIN or a partner's own catalogue key. The values are stored as given and are not interpreted, so they are the supported way to carry an external primary key alongside a product and to retrieve the product again later by searching on it with |
[
{
"type": "asin_ebook",
"value": "B0C1D2E3F4"
},
{
"type": "asin_book",
"value": "3161484100"
}
] |
external_identifiers[].type |
string| null |
The external system the identifier belongs to. The set is open and is not validated, so any string may appear and it cannot be treated as a fixed list. Examples are "asin_book" and "asin_ebook" for Amazon, "apple", and a bare product format such as "epub" or "pdf". An identifier with no type is reported either as an empty string or as null, so both forms have to be handled when grouping by system. |
asin_ebook |
external_identifiers[].value |
string |
The identifier as used by that system. |
B0C1D2E3F4 |
formats |
Array<string> |
Concrete file and manufacturing formats activated for this product; only formats actually enabled are listed. "pdf", "epub", "mobi" and "ibooks" are ebook file formats. "pod" is print on demand, where each copy is manufactured per order, while "edition_print" is a conventionally printed edition held in stock. "audiobook" is the audio edition and "nonbook" covers merchandise and other non-book articles. This is finer-grained than product_types: "pdf" and "epub" are both formats of the single product type "ebook". An empty array means no product format has been activated yet. |
[
"pdf",
"pod"
] |
has_been_published |
boolean |
Whether the product has been published at least once. Once true it stays true, including after the product is withdrawn or deleted. The practical meaning is that its EANs have already been distributed, so other systems may already hold records for this product, whereas a product that has never been published is not known outside Open Publishing. No conclusions should be drawn from this regarding status, which merely indicates whether the product is currently available for sale. |
true |
identifiers |
Properties: isbns |
ISBN assignments grouped by product format. This is a convenience view over the same numbers reported in eans; eans provides the mapping from one number to several product formats. |
{
"isbns": {
"pdf": {
"ean": "9783161484100",
"type": "ebook"
},
"pod": {
"ean": "9783161484117",
"type": "book"
}
}
} |
identifiers.isbns |
object |
One entry per product format that has an ISBN assigned, keyed by "pdf", "epub", "mobi", "ibooks", "pod", "audiobook" or "nonbook". Product formats without an assignment are omitted entirely, so an absent key means no ISBN rather than an empty one. |
{
"epub": {
"ean": "9783161484100",
"type": "ebook::epub"
}
} |
identifiers.isbns.*.ean |
string |
The 13-digit EAN assigned to this product format. |
9783161484100 |
identifiers.isbns.*.type |
string |
ISBN type the EAN is registered under, which controls how widely one EAN applies. The type is either a product type on its own, or a product type and product format joined by "::". Registering an EAN as "ebook" assigns it to every ebook format at once; registering one as "ebook::pdf" assigns a distinct EAN to the PDF alone. The coarse types are "book", "ebook", "audiobook" and "nonbook"; the granular ebook types are "ebook::pdf", "ebook::epub", "ebook::mobi" and "ebook::ibooks". Both levels occur, so matching on the part before "::" is sufficient to determine whether an EAN is an ebook. May also be an empty string where no type was ever set. |
ebook::epub |
imprint |
Properties: _id, _links, imprint_name, publisher_name, city, country, phone, fax, email, gln| null |
Publisher and imprint under which this product appears, or null if none is assigned. Imprints are shared across products within a realm and are identified by _id or by a unique imprint_name. Only that identifier is needed when writing: the remaining fields are filled in from the stored imprint, and the imprints resource is where the imprint's own details are maintained. |
{
"_id": 42,
"country": "DE",
"email": "rechte@example.com",
"gln": "4012345678901",
"imprint_name": "Zeilenquarz Verlag",
"phone": "+49 123 4567890",
"publisher_name": "Zeilenquarz Verlagsgruppe GmbH"
} |
imprint._id |
integer |
Open Publishing identifier of the imprint. |
42 |
imprint._links |
object |
URL of the full imprint resource. |
{
"self": "https://api.openpublishing.com/resource/v4/imprints/b7e94d20-51c8-4f3a-9d62-0ae5c81f7364"
} |
imprint.imprint_name |
string| null |
Name the product is published under. Unique within the realm, so it can be used instead of _id to assign an imprint. |
Zeilenquarz Verlag |
imprint.publisher_name |
string| null |
Legal or trading name of the publisher, which may differ from the imprint name. |
Zeilenquarz Verlagsgruppe GmbH |
imprint.city |
string| null |
City of publication of the imprint, the place of publication carried in bibliographic metadata. |
Rheinbergen |
imprint.country |
string| null |
Country of the publisher as an ISO 3166-1 alpha-2 code. |
DE |
imprint.phone |
string| null |
Publisher contact telephone number. |
+49 123 4567890 |
imprint.fax |
string| null |
Publisher contact fax number, retained for trade partners that still exchange orders by fax. |
+49 123 4567899 |
imprint.email |
string| null |
Publisher contact email address. |
rechte@example.com |
imprint.gln |
string| null |
Global Location Number of the publisher, a 13-digit GS1 identifier used by book-trade partners to route orders and remittances to the correct party. |
4012345678901 |
labels |
Array<string> |
Free-text markers for grouping products within a realm. Labels are private to the realm: they are not part of the product metadata distributed to trade partners, which makes them safe for operational bookkeeping. |
[
"autumn-campaign",
"cover-missing"
] |
language |
string| null |
Main language of the text as a three-letter ISO 639-2/B (bibliographic) code. The bibliographic form differs from the terminology (639-2/T) form for several languages: "ger" for German rather than "deu", "fre" for French rather than "fra", and "dut" for Dutch rather than "nld". Null when no language has been set. |
eng |
product_types |
Array<string> |
Commercial product types this product is sold as — the coarse grouping above formats, and the level at which prices and publication dates are managed. "ebook" appears when any ebook file format is active, and "book" when a printed edition is active, whether print on demand or a stocked print run. "audiobook" and "nonbook" mirror the formats of the same name. |
[
"ebook",
"book"
] |
realm |
Properties: _id, _legacy_id, _links, name, screenname |
Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association. |
{
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
} |
realm._id |
string |
Realm ID |
297fc359-cac6-4c0a-a7db-aaee70c075f2 |
realm._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
realm._links |
object | ||
realm.name |
string |
Name of the realm |
zeilenquarz |
realm.screenname |
string |
Screenname of the realm |
Zeilenquarz Verlagsgruppe |
shop_url |
string| null |
Public storefront URL of the product, or null if it is not currently offered in a shop. It points at the customer-facing shop rather than the API, and is null whenever no shop offers the product, so it cannot be relied on to be present. |
https://www.example.com/document/12345 |
status |
string |
Whether the product is currently for sale. Returned in upper case, and
matched case-insensitively when writing, so both
A product that is not for sale can be published later, or deleted
permanently. Publishing through the API applies no metadata completeness
check, so a product can be published while its metadata is still
incomplete. Status describes only the present; whether a product has ever
been on sale is reported by |
PUBLISHED |
subtitle |
string| null |
Secondary title, shown after the main title, or null when there is none. The subtitle is reported and set separately from the main title rather than appended to it. |
Ein Fall fuer Juli Sanwald |
title |
string |
Main title of the product, without the subtitle. Always present: a product cannot be created without a title. |
Der unsignierte Teppich |
Subresources
Descriptive and format-specific metadata is not carried on the product itself.
It is managed through sub-resources, each reachable from the _links object of
a product representation.
Each bullet is named after the key it appears under in _links.
- Contacts — who to write to about a title, by role: product
safety, metadata corrections, review copies, rights:
/resource/v4/products/{product_id}/contacts - Copyright Statements — the © / ℗ line: who
holds a right in the work and from which year:
/resource/v4/products/{product_id}/copyright_statements - Files — the binary assets of a product: manuscripts,
e-book and print-ready files, cover images and previews:
/resource/v4/products/{product_id}/files - Form Features — physical and digital
characteristics of a product form, in practice the e-book accessibility
declaration:
/resource/v4/products/{product_id}/form_features - Identifiers — the trade identifiers partners order
by, one per product format:
/resource/v4/products/{product_id}/identifiers - Prices — price entries per product format, territory and
distribution channel:
/resource/v4/products/{product_id}/prices - Publishing Dates — dated milestones such as
publication, embargo and out-of-print, held per format:
/resource/v4/products/{product_id}/publishing_dates - Storefronts — which shops offer the product, the
free-preview share and the shop page's SEO metadata:
/resource/v4/products/{product_id}/storefronts - Subjects — subject classification as scheme/code pairs
(BISAC, Thema, VLB):
/resource/v4/products/{product_id}/subjects - Suppliers — who a retailer orders the title from and
whether it can be ordered now:
/resource/v4/products/{product_id}/suppliers - Texts — descriptive copy: blurb, table of contents,
author biography, review quotes:
/resource/v4/products/{product_id}/texts - Titles — additional titles beyond the product's own
titleandsubtitle, per title variant, element and channel:/resource/v4/products/{product_id}/titles