API docs by Redocly

Reporting API (1.0.0)

Download OpenAPI specification:

License: Propietary

The Publizon Reporting API provides a clear and consistent method for outbound customers (retailers and partners) to report back to Publizon on earnings, content consumption, and reader demography.

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 reporting api endpoints.

Report revenue

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.

Authorizations:
(api_keybearer_auth)
Request Body schema: application/json
required
required
Array of objects (RevenueTransaction) [ 1 .. 250 ] items

Responses

Request samples

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

Get revenue data

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:

  • channel: The sales channel reporting the revenue
  • customer_id: Optional customer identifier from the retailer system.
  • product_indentifier: The primary identifier for the title, typically the ISBN-13.
  • retailer_transaction_id: 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).
  • subscription_type: The specific access model used by the customer. These will be unique pr retailer. Examples include: Unlimited / Trial
  • unit_amount: The calculated rate paid per single unit of the chosen
  • total_amount: 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).
Authorizations:
(api_keybearer_auth)
query Parameters
startDate
required
string

The start date for the query range (ISO 8601 format). The range cannot exceed 31 days.

endDate
required
string

The end date for the query range (ISO 8601 format).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Report usage

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

Authorizations:
(api_keybearer_auth)
Request Body schema: application/json
required
required
Array of objects (ProductUsageReport) [ 1 .. 50 ] items

Responses

Request samples

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

Get usage data

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:

  • usage_timestamp: Datetime when the usage started.
  • customer_id: Optional customer identifier from the retailer system.
  • product_identifier: 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.
  • start_position: Start position in seconds (audiobooks) or words (ebooks).
  • end_position: End position in seconds (audiobooks) or words (ebooks).
  • usage_id: Unique identifier generated by the retailer for de-duplication.
Authorizations:
(api_keybearer_auth)
query Parameters
startDate
required
string

The start date for the query range (ISO 8601 format). The range cannot exceed 31 days.

endDate
required
string

The end date for the query range (ISO 8601 format).

Responses

Response samples

Content type
application/json
[
  • {
    }
]