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.