Royalty calculation

This page explains how RoyaltyCentral turns posted transactions into royalty entries. The app creates them automatically as sales post, or in a manual batch. The page also covers consumption royalties on assembled or produced goods, credit-memo handling, and manual adjustments through the Royalty Journal.

When royalties calculate

There are two ways to create a Sale entry. Calculate Royalty on Posting on the Royalty Setup card governs them:

Mode How it runs
On posting (flag on) The app calculates royalties as each sales invoice posts. No manual step. This is a global setting. It applies to the released contracts.
Manual batch (flag off) Run RoyaltyCentral → Calculate → Calculate Royalties for a date range. The range matches the sales invoice posting date. The request page filters on the contract No.. Use the filter pane to add other contract fields.

Run the batch periodically even with on-posting enabled. It re-scans the posted sales and creates the entries that are now eligible but were not at posting time. The batch skips a sale that already has an entry for the contract.

Only a released contract participates. The app matches the Origin Region from the sales document’s location. It matches the Sell Region from the Sell-to Country/Region Code on the entry. It then matches the item or brand on the contract detail lines, inside the line’s date window. See Contracts for how a sale picks a line.

Recalculating a period

The batch skips the sales that already have an entry. This supports a common pattern: sell first, add the item or rate to the released contract later, then recalculate the period. Run Calculate Royalties over the affected date range. The existing entries stay as they are. Only the newly eligible sales produce entries.

What is — and isn’t — picked up

  • Sales are not blocked. The calculation runs after a sale posts. If nothing matches, the sale still posts and produces no royalty entry. There is no error. Licensed and unlicensed items can sit on the same order. A sale does not match when:
    • the item or brand is not on a released contract,
    • the posting date is outside the contract dates,
    • a region mapping is missing, or
    • no detail line matches the sale.
  • Only invoiced sales drive a royalty. Ship-only and undo-shipment value entries carry no invoiced quantity. They do not create entries.
  • Credit memos. The app includes them only when Calculate Royalty on Sales Cr. Memo is on. They post as Return entries.

Consumption royalties

Sometimes the licensed item is a component rather than the finished good, for example a part consumed on an assembly or production order. For this case, switch on Calculate Royalty on Consumption on the Royalty Setup card. Then choose the Royalty Consumption Type:

Consumption Type Royalty is recognized…
Consumption when the component is consumed (the assembly or production order posts).
Sale when the finished item that contains the component is sold.

The app writes the entry with Entry Type = Consumption. So reporting can distinguish a component sold inside a kit from the same item sold on its own.

How the consumption amount is derived

The app applies the royalty rate to a sales amount built from the component’s Item Card Unit Price multiplied by the consumed quantity. The app applies the bill-of-materials factor (how much of the component goes into one finished unit) automatically. The contract detail line’s rate (percentage, fixed amount for each unit, or both) then applies to that amount as usual.

Custom allocation is extensible. An integration event exposes the component price used for the calculation. A partner extension can substitute a cost-based figure or a negotiated allocation instead of the Item Card unit price. Use this seam when a licensor is paid a pre-agreed share of the finished sale value. This share is not a rate on the component’s own price.

Scenario: one finished item, more than one license

A finished item can carry more than one license. For example, a product assembled or produced from two licensed components, where each component belongs to a different licensor with its own contract. RoyaltyCentral handles this with no special item flag:

  1. Set up each licensed component under its own licensor and brand. Rate it on its own released contract. See Regions, licensors & brands.
  2. Create the finished item from those components with an assembly BOM or a production BOM. Selling it then consumes the components.
  3. Switch on Calculate Royalty on Consumption. Choose Consumption Type Sale if the royalty should land when the finished item sells.
  4. Sell the finished item. Business Central posts the assembly or production (which consumes each component) and the sale. RoyaltyCentral evaluates the released contracts against each consumed component. Each component produces its own Consumption entry under its own contract, at its own rate.

The same approach covers a single sellable item whose royalty stacks two agreements. Model the second license as a component that the finished item consumes. Each contract then reports independently from the one sale.

Pattern: a license with no physical product (non-inventory items)

Some royalties attach to intellectual property that has no stocked product of its own. Examples are artwork, a name, or a likeness printed on or built into something you sell. Model the license as a non-inventory item:

  1. Create a non-inventory item to represent the license. Assign it to the licensor’s brand so that a contract detail line rates it.
  2. Include it with the physical goods. Add it as a line on the sales document. Alternatively, add it as a component that the finished item consumes on an assembly or production order. Use consumption when the same physical product carries more than one such license and each is paid separately.
  3. When the document posts, the app rates the non-inventory line like other licensed items. It captures the royalty even though no inventory moved.

Manual entries & adjustments — the Royalty Journal

The Royalty Journal records manual Sale, Return, and Adjustment entries and corrections. Open RoyaltyCentral → Royalty Journals. Each line needs a Contract No., an Item No., a Posting Date, and a Source Type and Source No. The app validates the line against the contract: the contract must be released and the payee must be assigned. Posting writes to the Royalty Entries table.

Enter the payment-side types (Payment, Invoice, Minimum Guarantee, Advance) on the Royalty Payment Journal instead. See Payments and Minimum guarantees.

To reverse a posted entry, use Reverse Entry on the Royalty Entries page rather than a negative journal line. It posts a linked, offsetting Reversal and flags the original.

Posting the Royalty Journal from an API

The Royalty Journal is also available to external systems as a v2.0 web API. Under api/tigunia/royalty/v2.0, the royaltyJournalLines entity supports create, read, update, and delete on journal lines. Send journalTemplateName and journalBatchName to place a line. The app assigns lineNo. Each line exposes a bound post action:

POST .../api/tigunia/royalty/v2.0/companies(<id>)/royaltyJournalLines(<lineId>)/Microsoft.NAV.post

A call to post on a line posts that line’s whole Journal Template and Batch to the Royalty Entries table. The result is the same as the Post action on the page, with no interactive confirmation. The usual gates still apply: royalty must be enabled and the tenant licensed. Otherwise the call returns the corresponding error.

A line created through the API picks up the same defaults that the Royalty Journal page applies to a new line:

  • the posting and document dates,
  • the entry type and the source type,
  • the batch’s reason code and number series, and
  • the origin region derived from the location.

The app keeps a value sent in the request as sent. It fills only the fields left empty.

Like the Royalty Journal page itself, the endpoint serves only the DEFAULT journal template. The endpoint does not return lines under another template. It rejects a create that names another template. Send journalTemplateName as DEFAULT or leave it out.

entryType and sourceType are plain strings rather than API enums. A line that has neither set yet reads back as "" instead of an encoded placeholder. On create or update, entryType accepts Sale, Return, or Adjustment, and sourceType accepts Customer. The API rejects another value.

The line must reference an existing journal batch. You cannot change its template or batch afterward.


See also: Royalty Setup — Sales & Consumption · Contracts · Royalty entries · Payments