Skip to content

Sales Report Resource

Introduction

The sales resource provides an interface to retrieve all purchases of your product in a normalized way. The main purpose of this resource is to sync all normalized sales with an external accounting system. This includes:

  • Sales through distribution channels with aggregation model. In the aggregation model the products are sold through the contracts of Open Publishing.
  • Sales through distribution. In the distribution model, the publisher has own contracts with distribution channel. Sales are done on the own name of the publisher.
  • Own direct sales to book stores, libraries or consumers.

For placing and modifying orders use the order resource.

Example URL

Get single sale:

https://grin.julius.dev.openpublishing.com/resource/v3/sales/1

Allowed methods: GET.

Search Filters

Filter for IDs

Search for Ids greater then a given number. Display 500 entries per "page":

https://{api_host}/resource/v3/sale?id__gt=1337&display=500

As the id is an incremental number, this functionality may be used to retrieve all updates since the last synchronisation. See Listen for sales example for a reference implementation of a sync daemon.

Filter for previews

Search for previews only:

https://{api_host}/resource/v3/sales?preview=true

Exclude previws (only sales data):

https://{api_host}/resource/v3/sales?preview=false

Fields

Booking Type

booking_type describes the type of the sales record. For a normal sale of a product, the value is sale. Possibel values are:

sale: Sale of a product. cancelation: A cancellation of a product. If a sale is cancelled, the field reference refers to the the original sale. fee: A fee of any type. shipment: Accounted shipping costs.

EAN

ean of the product sold. String or null.

Publication Type

publication_type of the product sold. Possible values are:

  • epub: Ebooks in Epub format.
  • mobi: Ebooks in Mobipocket format.
  • pdf: Ebooks in PDF format.
  • ibooks: Ebooks in apple ibook format.
  • audiobook: Audio books.
  • software: Software.
  • pod: Print on demand titles.

Quantity

quantity of products sold.

Publisher Compensation Net

publisher_compensation_net and publisher_compensation_net_currency the publisher compensation. This is the net amount the publisher will receive from from distribution channel on distribution model and from OP on aggregation model. OP Fee and distribution channel discount are already subtracted. The field is displayed in the currency as it was reported from the channel. The amount is already multiplied by the quantity. The currency is reported with the ISO 4217 currency code.

Publisher Compensation Net in Sale Currency

publisher_compensation_sale_currency_net and publisher_compensation_sale_currency_net_currency contain above amount converted to currency of sale. The conversion rate is the currency conversion rate of the sale date. Open Publishing does not guarantee for the correctness of the conversion rate. The amount is already multiplied by the quantity. The currency is reported with the ISO 4217 currency code.

Amount Received

amount_received and amount_received_currency is incoming amount booked by Open Publishing. For distributon model this amount equals the publisher compensation. For aggregation model this is the publisher compensaton net plus the Open Publishing Fee. Amount received contains the total sum (single amount * quantity). The amount is already multiplied by the quantity. The currency is reported with the ISO 4217 currency code.

Retail Price

retail_price and retail_price_currency is the price with which the product was sold to the consumer. The reported number is taken from the reports of the distribution channels and is in most of the cases reported in the currency of the sale. The amount is the single price for one unit. The currency is reported with the ISO 4217 currency code.

Publisher Price

publisher_price and publisher_price_currency is the net price of the product. For agency model, Retail Price and Publisher price are the same. For reseller contract model, the publisher price is the recommended retail price - and the actual retail price may vary. The amount is the single price for one unit. The currency is reported with the ISO 4217 currency code.

Production Costs

If reported by the channel, production_costs and production_costs_currency contain the costs for production of the product. The amount is the single costs for one unit. The currency is reported with the ISO 4217 currency code. Only relevant for POD channels.

Period

Sales from external distribution channel are usually processed with a delay. The period field describes the time when the purchase happend. As different distribution channel have different granularity the period field is either in the format "YYYY-MM-DD", "YYYY-MM" or "YYYY". The most common format of granularity is month - e.g. for Amazon.

For automated processing the fields period_begin and period_end describe the begin and the end of described period. For the period 2020-03 period_begin is 2020-03-01 and period_end is 2020-03-31. The granularity of these fields is always date.

Country

country ISO 3166-2 code the country in which the product was purchased.

Distribution Channel

distribution_channel is a string describing the main distribution channel of a sale. E.g. for all sales within the Tolino alliance, the sales channel is libri, bc the contract is between publisher or Open Publishing an Libri. For more specific information see field sales_channel.

Sales Channel

sales_channel contains the sales channel of the purchase as string. The sales_channel is more granular then the distribution_channel field and refers to the specific shop within a distribution channel where the purchase happened. For website sales the sales_channel contains the hostname of the shop.

Preview

The field preview is a boolean which indicates if the sales record is a final booking or a provisional preview of a sale.

Reference

The field reference describes the reference to the original sale. This field is used within cancelations to refer to the sale which was changed.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Example JSON

{
   "_id": 1234567,
   "amount_received": 237,
   "amount_received_currency": "GBP",
   "booking_type": "sale",
   "country": "GB",
   "distribution_channel": "amazon",
   "ean": "97812345678",
   "period": "2020-07",
   "period_begin": "2020-07-01",
   "period_end": "2020-07-31",
   "preview": false,
   "production_costs": null,
   "production_costs_currency": null,
   "publication_type": "MOBI",
   "publisher_compensation_net": 237,
   "publisher_compensation_net_currency": "GBP",
   "publisher_compensation_sale_currency_net": 237,
   "publisher_compensation_sale_currency_net_currency": "GBP",
   "publisher_price": 321,
   "publisher_price_currency": "GBP",
   "quantity": 1,
   "realm": {
     "_id": 23,
     "name": "testpublisher",
     "screenname": "Test Publisher"
   },
   "reference": null,
   "retail_price": 385,
   "retail_price_currency": "GBP",
   "sales_channel": "Amazon Kindle",
   "sales_channel_unified": "Amazon Kindle"
}