Skip to content

Royalty Rules Resource

Introduction

With royalty rules describe rules for creating author royalties for each sale. Generated royalties may be accessed via the Royalties API.

Example URL

https://api.openpublishing.com/resource/v3/royalty_rules/[ID]

Allowed methods: GET, POST, PUT, DELETE.

Search Filters

List royalty rules:

https://api.openpublishing.com/resource/v3/royalty_rules

Search for all royalty rules of product:

https://api.openpublishing.com/resource/v3/royalty_rules?product_id=[PRODUCT-ID]

Search for all royalty rules of business partner:

https://api.openpublishing.com/resource/v3/royalty_rules?business_partner_id=[BUSINESS-PARTNER-ID]

external_identifier_type / external_identifier_value : Search for royalty rules with an external identifier set. The external identifier type is the category of the royalty rule, e.g. "klopotek" whereas the value is the id itself. If only external_identifier_type is specified, all royalty rules with the external identifier type set are returned. If you search for only external_identifier_value - the system will return all identifiers with the value, where the type is not set.

Fields

Business Partner

business_partner Subobject contains link to business partner for whom the royalty should be generated. The business partner object is a dict with the _id field and the screenname of the business partner.

Product

The product field contains a reference to a product. For each sold products royalties are generated. The product object is a dict containing an _id and the title of the product.

Calculations

The calculations field contains a list of rules on how the royalties should be generated. A typical rule for the business partner should get 3% of the net turnover ("Verlagserlös") looks like:

   {
      "channel": "ebook",
      "group_identifier": null,
      "description": "Royalty for Ebook sales",
      "scale": [
         {
            "basis": "net-turnover",
            "threshold": {
               "type": "amount-received",
               "quantity": null,
               "amount": 5000,
               "currency": "EUR"
            },
            "percentage": 3
         },
         {
            "basis": "amount-received",
            "threshold" : {
                  "type": "units-sold",
                  "quantity": 1000,
                  "amount": null,  
                  "currency": null
            },
            "percentage": 3.5
         }
      ]
   }
  • channel: ebook or book. Use to describe different calculations for ebook and book sales. Leave empty if the rule should be applied for all sales.
  • description: Description for royalty rule. This field will be used as position description on PDF invoice.
  • The field percentage describes the percentage of the royalties.
  • The field scale/basis describes the basis on which the percentage is applied. It can have the values external_revenue_net, external_revenue_gross, amount_received_net, amount_received_gross. See corresponding explanation within sales resource for an explanation of these values.
  • scale/threshold/type may be either units_sold, external_revenue_net or amount_received_net. Default is units_sold. See corresponding explanation within sales resource for an explanation of these values.
  • scale/threshold/quantity is used to define scales based on quantity (e.g. 3%, from 1000 copies sold 3.5%). May only be set if scale/threshold/type is units-solds. Set to null if no scale should be applied. First scale always has to be null.
  • scale/threshold/amount and scale/threshold/currency is used to define scale by turnover (e.g. 3%, from 3000 EUR turnover sold 3.5%). May only be set if threshold/type is set to external_revenue_net or amount_received_net. Set to null if not used.
  • If field group_identifier is set, all created royalties will have this group identifier set.

Note: You can't mix different values for scale/threshold/type. Also the scale/threshold/currency has to be the default currency of the realm (usually EUR).

External Identifiers

external_identifiers: List of external/foreign identifiers, e.g. the id of the business partner within Klopotek, Paypal or Amazon. The listed objects are dicts with the values type for the type of the identifier and value for the identifier itself.

Realm

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

Active

active is the flag to enable or disable a rule. A disabled rule does not generate new provision rules.

Start and end date

If start_date and end_date are set, only sales within specified date ranges (inclusive) are used to generate royalties.

Example JSON

{
   "_id": 173440,
   "active": true,
   "business_partner": {
      "_id": 147,
      "screenname": "John Doe"
   },
   "calculations": [
   {
            "channel": "ebook",
            "group_identifier": null,
            "scale":
               [
                  {
                     "basis": "amount_received_net",
                     "threshold": {
                        "type": "amount_received_net",
                        "quantity": null,
                        "amount": 5000,
                        "currency": "EUR"
                     },
                     "percentage": 3
                  }
               ]
         },
         {
            "channel": "book",
            "group_identifier": null,
            "scale":
               [
                  {
                     "basis": "amount_received_net",
                     "from": {
                        "type": "units_sold",
                        "quantity": 1000,
                        "amount": null,
                        "currency": null
                     },
                     "percentage": 2
                  }
               ]
         }
   ],
   "end_date": "2022-01-31",
   "product": {
      "_id": 1387,
      "title": "Jugendliche und Internet-Communities \/ Chats"
   },
   "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
   },
   "start_date": "2022-01-01"
}