API docs by Redocly

Retailer API (1.0.0)

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.

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.

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.

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 and buyerEmail are required to perform the content protection, but it will not trigger any delivery to the buyerEmail. 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.

isbn
required
string
required
object (RetailOrderPrice)
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.

Responses

Request samples

Content type
application/json
Example
{
  • "orderId": "IuhkQCHQ4KxUEPcLZY3B",
  • "isbn": "9780394320069",
  • "price": {
    },
  • "deliverySource": "Publizon",
  • "buyerEmail": "test@wedobooks.io",
  • "buyerId": "XNeJJEwxW6uS2ghgQSHu",
  • "orderLanguage": "en",
  • "retailerSupportEmail": "email@wedobooks.io"
}

Response samples

Content type
application/json
{
  • "id": "pa52Tzxwsy39K2s5VWun",
  • "retailerOwnId": "string",
  • "status": "Processing",
  • "isbn": "9780472714830",
  • "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",
  • "isbn": "string",
  • "deliverySource": "Publizon",
  • "price": {
    },
  • "downloadCount": 0,
  • "buyerId": "string",
  • "buyerEmail": "string",
  • "orderLanguage": "string",
  • "retailerSupportEmail": "string",
  • "author": "string",
  • "title": "string"
}

Get order by publizon order id

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

Authorizations:
(api_keybearer_auth)
path Parameters
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "IuhkQCHQ4KxUEPcLZY3B",
  • "status": "Canceled",
  • "buyerId": "string",
  • "buyerEmail": "test@wedobooks.io",
  • "retailerOwnId": "string",
  • "isbn": "9780472714831",
  • "downloadCount": 0,
  • "orderLanguage": "Da",
  • "retailerSupportEmail": "test@wedobooks.io",
  • "author": "Some author",
  • "title": "Some title"
}

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

Responses

Response samples

Content type
application/json
{}