Royalties Resource

Introduction

Royalties are monetary amounts which will invoiced to authors and other royalty recipients on next quaterly, biannual or annual statement.

Royalties may either be created through this API or automatically privisioned through defined royalty rules.

Example URL

https://api.openpublishing.com/resourcev3/business_partners/[ID]/royalties/[ID]

Allowed methods: GET, POST, PUT, DELETE.

List royalties:

https://api.openpublishing.com/resourcev3/business_partners/[ID]/royalties/[ID]

Search within description:

https://api.openpublishing.com/resource/v3/business_partners/147/royalties?description=printing
https://api.openpublishing.com/resource/v3/business_partners/147/royalties?description__contains=printing

external_identifier_type / external_identifier_value : Search for royalties with an external identifier set. The external identifier type is the category of the royalty, e.g. "klopotek" whereas the value is the id itself. If only external_identifier_type is specified, all royalties 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

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.

EAN

ean field may contain a ean. This ean must be registered within a product.

Description

description contains an arbitrary description of the royalty. This string will later show up on credit note.

Net / net currency

net contains the net amount which should be credited to the receiving business partner. If set to a negative value, amount is deducted from credit note. net_currency contains the ISO code of the currency.

Quantity

quantity contains the factor with which the net value should be multiplied.

Total net / total net currency.

Read only field total_net and total_net_currency contain the total amount credited to business partner. It is the net value multiplied by quantity.

Type

Type is an internal arbitrary string used to assing the royalties to internal business cases - may be used to controlling and accounting.

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.

Group Identifier

group_identifier is an arbitrary string or null. If set, it will group all provisions by this string and check if the sum is positive before selecting the royalties for a statment.

Example JSON

{
   "_id": 41,
   "description": "Test Royalty",
   "ean": "9783811588202",
   "external_identifiers": [],
   "group_identifier": "Advance-Payment-2020-01-01",
   "net": 217,
   "net_currency": "EUR",
   "product": {
      "_id": 1448,
      "title": "Test title"
   },
   "quantity": 1,
   "total_net": 217,
   "total_net_currency": "EUR",
   "type": "regular"
}