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.

Each retailerTransactionId must be unique for the calling retailer. A request that reuses an id — either within the same batch or against a previously reported transaction — is rejected as a whole; 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.