API docs by Redocly

Retailer API (1.0.0-dev)

Download OpenAPI specification:

License: Propietary

The Publizon Retailer API provides a solution for online retailers to sell digital books and audiobooks. It is designed to facilitate the entire process of purchasing digital books, from catalog discovery and order creation to secure content delivery.

Each publizon order contains a single product. A single retailer order may be mapped to multiple publizon orders. Order status:

  • Processing: The product is being prepared for delivery.
  • Fulfilled: The order is complete, and the product is available for the customer.
  • Canceled: The order has been canceled, and the download link discontinued.
  • Failed: The transaction could not be completed, and no product has been delivered. E.g. invalid email address.

Authentication

An API key and a set of credentials (email and password) must be used to authenticate. Use the auth api to get the short-lived token needed to call the retailer api endpoints.

If the user calling the API belongs to more than one company, the companyid header is required to specify which company should be used. If you are unsure of your company ID, please contact Publizon support.

Alpha and Delta pull

  1. Alpha pull: First time you use the Retailer API you must retrieve all the books metadata using the alpha pull endpoint. Alpha pull is not active by default. Please contact Publizon in order to activate alpha pulls for your account.
  2. Delta pull: Use the delta pull endpoint to retrieve updates (created/updated products).

Both alpha and delta pulls are paginated. You will be able to fetch up to 100 products per request.

If additional pages are available, pagination metadata is included in the response headers:

  • X-Pagination-Cursor: Cursor to be used to fetch the next page of data
  • X-Pagination-Limit: Amount of products returned per page

When the last page of an alpha or delta pull is reached, a X-Next-Delta-Pull-Utc-Timestamp is included in the response header. This is a timestamp in ISO 8601 format with milliseconds precision. It must be stored in the client's system and be used for the next delta pull.

Make sure to delete from your system all the products with NotificationType = 05.

You can also get metadata for a specific book by ISBN using the book metadata in ONIX format endpoint

How to get media files

The links to download media files will be available for each Product as part of the onix metadata at Product/CollateralDetail/SupportingResource Use the Product/CollateralDetail/SupportingResource/ResourceContentType tag to identify the type of resource. For example:

  • 01: Front cover
  • 27: Cover thumbnail
  • 28: Full content. epub/pdf files for ebooks and .zip files for audiobooks
  • 15: Sample content. epub/pdf files for ebooks and .mp3 files for audiobooks

Links to download media files will expire after 48hs.

The last time a supporting resource was updated can be read from: Product/CollateralDetail/SupportingResource/ResourceVersion/ContentDate. It is recommended to store and check this date in your own system to avoid downloading the same media files multiple times.

For each supporting resource, there is a ResourceVersionFeature element with ResourceVersionFeatureType 06. This is the file md5 hash.

Alpha pull

Retrieve onix metadata for all books that are available for the receiver calling the API.

This endpoint uses paginated requests. Each response header includes pagination metadata. Use the X-Pagination-Cursor header to fetch the next batch of data. The X-Pagination-Cursor is updated and returned with each response until there is no more data to fetch.

Once all the data has been pulled, the response header will include a X-Next-Delta-Pull-Utc-Timestamp. This is a timestamp in ISO 8601 format with milliseconds precision that must be used for the next delta pull.

For each product, a publizon propietary id will be provided. For example:

<ProductIdentifier>
   <ProductIDType>01</ProductIDType>
   <IDTypeName>Publizon internal id</IDTypeName>
   <IDValue>9df4f337-41c4-4006-86b7-c4d57194d711</IDValue>
</ProductIdentifier>

this id can be used when creating new orders via retailer api.

Authorizations:
(api_keybearer_auth)
query Parameters
paginationCursor
string
Example: paginationCursor=eyJpZCI6IjEyMyIsImtleSI6InRpbWVzdGFtcF8xMjMifQ==

A string to identify the last retrieved item for pagination. Use this to continue pulling data from where the last request left off. The pagination cursor will be updated and returned on each request until there is no more data to be fetched.

paginationLimit
integer <int32>
Example: paginationLimit=100

The maximum number of items to retrieve. If the specified value exceeds 100, it will be capped at 100.

Responses

Response samples

Content type
application/xml

    <ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0">
    <Header>
        <Sender>
            <SenderName>SenderName</SenderName>
            <ContactName>ContactName</ContactName>
            <EmailAddress>EmailAddress</EmailAddress>
        </Sender>
        <SentDateTime>20240723</SentDateTime>
    </Header>
    <Product datestamp="20240723T081436Z">
        ...
    </Product>
</ONIXMessage>

Delta pull

Retrieve onix metadata for all books that are available for the receiver calling the API and were created/edited after a given date.

This endpoint uses paginated requests. Each response header includes pagination metadata. Use the X-Pagination-Cursor header to fetch the next batch of data. The X-Pagination-Cursor is updated and returned with each response until there is no more data to fetch.

Once all the data has been pulled, the response header will include a X-Next-Delta-Pull-Utc-Timestamp. This is a timestamp in ISO 8601 format with milliseconds precision that must be used for the next delta pull.

It is allowed to fetch data up to 1 month in the past.

For each product, a publizon propietary id will be provided. For example:

<ProductIdentifier>
   <ProductIDType>01</ProductIDType>
   <IDTypeName>Publizon internal id</IDTypeName>
   <IDValue>9df4f337-41c4-4006-86b7-c4d57194d711</IDValue>
</ProductIdentifier>

this id can be used when creating new orders via retailer api.

Authorizations:
(api_keybearer_auth)
path Parameters
fromUtcTimestamp
required
string <date-time>
Example: 2024-11-08T11:43:55.262Z

onix metadata for books edited after this UTC date in ISO 8601 format

query Parameters
paginationCursor
string
Example: paginationCursor=eyJpZCI6IjEyMyIsImtleSI6InRpbWVzdGFtcF8xMjMifQ==

A string to identify the last retrieved item for pagination. Use this to continue pulling data from where the last request left off. The paginationCursor will be updated and returned on each request until there is no more data to be fetched.

paginationLimit
integer <int32>
Example: paginationLimit=100

The maximum number of items to retrieve. If the specified value exceeds 100, it will be capped at 100.

Responses

Response samples

Content type
application/xml

    <ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0">
    <Header>
        <Sender>
            <SenderName>SenderName</SenderName>
            <ContactName>ContactName</ContactName>
            <EmailAddress>EmailAddress</EmailAddress>
        </Sender>
        <SentDateTime>20240723</SentDateTime>
    </Header>
    <Product datestamp="20240723T081436Z">
        ...
    </Product>
</ONIXMessage>

Book onix metadata

Retrieve book metadata in onix format.

Authorizations:
(api_keybearer_auth)
path Parameters
isbn
required
string

book isbn

Responses

Response samples

Content type
application/xml

    <ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0">
    <Header>
        <Sender>
            <SenderName>SenderName</SenderName>
            <ContactName>ContactName</ContactName>
            <EmailAddress>EmailAddress</EmailAddress>
        </Sender>
        <SentDateTime>20240723</SentDateTime>
    </Header>
    <Product datestamp="20240723T081436Z">
        ...
    </Product>
</ONIXMessage>

Create order

Creates a new order in Publizon. Each Publizon order represents a single book. When creating an order, you must provide an orderId, which corresponds to the retailer’s own order ID. This ID serves as a reference that can be associated with one or more Publizon orders.

In case a product is not available for the retailer calling this endpoint, a forbidden (403) status code will be returned.

Delivery source

The delivery source must be one of:

  • Publizon: Publizon will manage DRM/Watermarking (depending on the product) and delivery. Therefore, a buyerId and buyerEmail are required when publizon is the delivery source. The content will be automatically delivered to buyerEmail using the type of protection chosen by the publisher (DRM/Watermarking). The end user can download the book up to 10 times within a 6-month period.
  • Retailer: The retailer manages DRM/Watermarking and content delivery. There is no need to provide a buyerId or buyerEmail
  • RetailerPublizonProtection: Publizon will manage DRM/Watermarking (depending on the product) and the retailer will handle the delivery of the download link. Therefore, a buyerId is required to perform the content protection. The retailer must call the /orders/download-link/{orderId} endpoint to get the download link and deliver it to the end user.
Authorizations:
(api_keybearer_auth)
Request Body schema: application/json
required

Request body required fields depend on deliverySource.

Any of
orderId
required
string

The retailer's own order id. Used for future reference.

productIdentifier
required
string

Publizon propietary id or ISBN. Publizon propietary id is provided by publizon during alpha/delta pulls.

deliverySource
required
string (RetailOrderDeliverySource.Publizon)
Value: "Publizon"
buyerEmail
required
string^(.+)@(.+)$

Download link will be sent to this email.

buyerId
required
string

Identifier for the end user. It can be used to find orders by user id.

orderLanguage
required
string (RetailOrderLanguage)
Enum: "en" "da" "fi" "se" "no"
retailerSupportEmail
required
string^(.+)@(.+)$

This email will be shared with the end user (buyer) as a support email in case of issues with the order.

object (RetailOrderPrice)

Responses

Request samples

Content type
application/json
Example
{
  • "orderId": "IuhkQCHQ4KxUEPcLZY3B",
  • "productIdentifier": "9df4f337-41c4-4006-86b7-c4d57194d711",
  • "deliverySource": "Publizon",
  • "buyerEmail": "test@wedobooks.io",
  • "buyerId": "XNeJJEwxW6uS2ghgQSHu",
  • "orderLanguage": "en",
  • "retailerSupportEmail": "email@wedobooks.io",
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pa52Tzxwsy39K2s5VWun",
  • "retailerOwnId": "string",
  • "status": "Processing",
  • "productPublizonIdentifier": "0df4f337-41c4-4006-86b7-c4d57194d712",
  • "productIdentifier": "9780131920071",
  • "deliverySource": "Publizon",
  • "price": {
    },
  • "downloadCount": 0,
  • "buyerId": "string",
  • "buyerEmail": "test@wedobooks.io",
  • "orderLanguage": "Da",
  • "retailerSupportEmail": "test@wedobooks.io",
  • "author": "Some author",
  • "title": "Some title"
}

Orders by attribute

Get orders by attribute. Supported attributes are:

  • buyerId
  • buyerEmail
  • retailerOwnId A single retailer's own order id may be mapped to multiple publizon orders.
Authorizations:
(api_keybearer_auth)
query Parameters
attribute
required
string
Enum: "buyerId" "buyerEmail" "retailerOwnId"
value
required
string

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Cancel order

Cancel an order order by id. For orders where the delivery source is Publizon: It is only possible to cancel an order if the product has been downloaded a maximum of one time.

Authorizations:
(api_keybearer_auth)
path Parameters
orderId
required
string

Publizon order id. Please note: This is NOT the retailer's own order id.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "retailerOwnId": "string",
  • "status": "Processing",
  • "productPublizonIdentifier": "string",
  • "productIdentifier": "string",
  • "deliverySource": "Publizon",
  • "price": {
    },
  • "retailerPrice": {
    },
  • "downloadCount": 0,
  • "buyerId": "string",
  • "buyerEmail": "string",
  • "orderLanguage": "string",
  • "retailerSupportEmail": "string",
  • "author": "string",
  • "title": "string"
}

Get order by publizon order id

Get order by publizon order id. A single order contains a single book.

Authorizations:
(api_keybearer_auth)
path Parameters
orderId
required
string

Publizon order id. Please note: This is NOT the retailer's own order id.

Responses

Response samples

Content type
application/json
{
  • "id": "IuhkQCHQ4KxUEPcLZY3B",
  • "status": "Canceled",
  • "buyerId": "string",
  • "buyerEmail": "test@wedobooks.io",
  • "retailerOwnId": "string",
  • "productPublizonIdentifier": "0df4f337-41c4-4006-86b7-c4d57194d712",
  • "productIdentifier": "9780131920071",
  • "downloadCount": 0,
  • "orderLanguage": "Da",
  • "retailerSupportEmail": "test@wedobooks.io",
  • "author": "Some author",
  • "title": "Some title",
  • "price": {
    }
}

Get order download link by publizon order id.

This endpoint can only be called for orders with the delivery source RetailerPublizonProtection.

Publizon begins processing an order immediately after creation. Depending on the content protection chosen by the publisher, files may be watermarked or packaged with Adobe Content Server for DRM. The endpoint will return 200 status code with a download link only when the order is ready. If the order is still being processed (for example during watermarking), the response will return a 202 status code. Watermarking large audiobooks may take a few minutes depending on their size.

Authorizations:
(api_keybearer_auth)
path Parameters
orderId
required
string

Publizon order id. Please note: This is NOT the retailer's own order id.

Responses

Response samples

Content type
application/json
{}