Reporting API (1.0.0-dev)

This endpoint allows partners to upload structured data regarding the financial performance of content sold or consumed via their platform. It covers the flow of financial information back to Publizon.

retailerTransactionId is your own id for each transaction, and it protects against double reporting: we never insert the same id twice for your account. If a request fails (e.g. a timeout) and you retry it with the same ids, the retry is rejected with DUPLICATE_RETAILER_TRANSACTION_ID when the original request already went through — so it is safe to retry without risking duplicate transactions. A duplicate id, whether repeated within the batch or already reported earlier, rejects the whole request; no transactions are inserted.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to report revenue data.
• PRODUCT_NOT_FOUND: One or more provided product identifiers do not exist. The request is rejected as a whole — if any product is missing, no transactions from the batch are inserted.
• COMPANY_NOT_FOUND: The company specified by the companyId header does not exist.
• DUPLICATE_RETAILER_TRANSACTION_ID: One or more retailerTransactionId values have already been reported by this retailer. The request is rejected as a whole.
• UNPROCESSABLE_ENTITY: The request payload is invalid.

This endpoint allows publishers and sales channels to export transactional revenue data.

• Publishers can access revenue data for the books they own.
• Sales channels can access the revenue data they have reported.

Response:

• customerId: Optional customer identifier from the retailer system.
• productIdentifier: The primary identifier for the title, typically the ISBN-13.
• retailerTransactionId: A unique string generated by the retailer to ensure each consumption event or sale is reported only once and can be audited.
• quantity: The numerical volume of usage. Depending on the QuantityType, this could be a whole number (units / parts) or a decimal (hours/percentage).
• saleTimestamp: Datetime when the transaction occurred.
• unitAmount: The calculated rate paid per single unit of the chosen
• totalAmount: The total net revenue or royalty share to be paid to the publisher for this specific line item.
• market: The geographic market of the user (e.g., SE, DK, FI).

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read revenue data.
• UNPROCESSABLE_ENTITY: Query parameters are invalid.

This endpoint handles the reporting of how end-users consume the digital content. It is only available to outbound channels.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to report usage data.
• PRODUCT_NOT_FOUND: One or more provided product identifiers do not exist. The request is rejected as a whole — if any product is missing, no usage events from the batch are inserted.
• COMPANY_NOT_FOUND: The company specified by the companyId header does not exist.
• UNPROCESSABLE_ENTITY: The request payload is invalid.

This endpoint allows publishers and sales channels to export transactional usage data.

• Publishers can access usage data for the books they own.
• Sales channels can access the usage data they have reported.

Response:

• usageTimestamp: Datetime when the usage started.
• customerId: Optional customer identifier from the retailer system.
• productIdentifier: The primary identifier for the title, typically the ISBN-13.
• part: Part index reported for the usage event.
• format: Format in which the usage happened.
• startPosition: Start position in seconds (audiobooks) or words (ebooks).
• endPosition: End position in seconds (audiobooks) or words (ebooks).
• usageId: Unique identifier generated by the retailer for de-duplication.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read usage data.
• UNPROCESSABLE_ENTITY: Query parameters are invalid.

This endpoint allows retailers to export the retail orders they have placed with Publizon.

Response:

• orderId: The Publizon order identifier.
• orderTimestamp: Datetime when the order was registered.
• retailerOwnId: The order id assigned by the retailer in their own system.
• productIdentifier: The primary identifier for the title, typically the ISBN-13.
• contentType: The type of content ordered.
• publisher: The publisher the ordered title belongs to.
• buyerId: Optional buyer identifier from the retailer system.
• country: The country of the order.
• deliverySource: The source the order was delivered from.
• language: The language of the ordered title.
• netPrice: The net price of the content.
• discountNetPrice: Effective net price after discount; equals netPrice when there is no discount.
• protection: The content protection applied to the order. Chosen by the publisher.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read retail orders.
• UNPROCESSABLE_ENTITY: Query parameters are invalid.

Aggregated consumption per day, customer, product and format.

This data comes from reading inside the WeDoBooks SDK. If your account does not use the SDK the response is an empty page with dataCompleteThrough set to null; the same applies before your first day of data has been assembled.

Three ways to read, mutually exclusive:

• Windowed — pass startDate and endDate. There is no maximum range.
• Full — pass no date parameters to read all available history. Use this for your initial load.
• Changes only — pass fromUtcTimestamp to read only rows added or recalculated since that moment.

Page to the end first — keep sending nextPaginationCursor back as paginationCursor until it comes back null. Only then take toUtcTimestamp and use it as fromUtcTimestamp on your next pull. Every page of one pull reports the same toUtcTimestamp; jumping to a new pull before the last page silently skips whatever was left.

Rows replace, they do not add up. A row you receive replaces any row you already hold with the same date, customerId, productIdentifier and format. If you append instead of replacing, every corrected figure is counted twice. Rows are never removed — a figure corrected to nothing arrives with its metrics set to zero.

To count checkouts over a period, use GET /checkouts and count the rows it returns.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read consumption data.
• UNPROCESSABLE_ENTITY: Query parameters are invalid, or fromUtcTimestamp was combined with a date range.

Aggregated consumption per day and hour, across all customers and titles.

These rows cannot be filtered or broken down by customer or title. Use GET /consumption when you need either.

This data comes from reading inside the WeDoBooks SDK. If your account does not use the SDK the response is an empty page with dataCompleteThrough set to null; the same applies before your first day of data has been assembled.

Supports the same three ways to read and the same replace semantics as GET /consumption. Here a row is identified by date, hour and format.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read consumption data.
• UNPROCESSABLE_ENTITY: Query parameters are invalid, or fromUtcTimestamp was combined with a date range.

One record per checkout, with the consumption accumulated against it over its whole life.

Checkouts that were never opened are included, with zeroed metrics and no activity timestamps.

This data comes from reading inside the WeDoBooks SDK. If your account does not use the SDK the response is an empty page with dataCompleteThrough set to null; the same applies before your first day of data has been assembled.

Three ways to read, mutually exclusive:

• Windowed — pass startDate and endDate, matched against the day the checkout was created.
• Full — pass no date parameters to read every checkout. Use this for your initial load.
• Changes only — pass fromUtcTimestamp to read only checkouts added or recalculated since that moment. A checkout being listened to changes at most once a day, not once per listening event.

Page to the end first — keep sending nextPaginationCursor back as paginationCursor until it comes back null. Only then take toUtcTimestamp and use it as fromUtcTimestamp on your next pull. Every page of one pull reports the same toUtcTimestamp; jumping to a new pull before the last page silently skips whatever was left.

Rows replace, they do not add up. A row you receive replaces any row you already hold with the same checkoutId. If you append instead of replacing, every corrected figure is counted twice.

Counting the rows returned for a period gives the number of checkouts in that period.

Error codes

• UNAUTHORIZED: Authentication failed or the caller is not allowed to access this endpoint.
• FORBIDDEN: The caller is authenticated but does not have permission to read checkout data.
• UNPROCESSABLE_ENTITY: Query parameters are invalid, or fromUtcTimestamp was combined with a date range.