Agreements and rules: Royalty Payouts Paladin docs

An agreement is a deal. A rule inside it is one format of that deal: a print rule and a digital rule at different rates, a rule per region, a rule per contract year. Everything a rule needs that the whole deal shares (the recipients, the schedule, the basis, the deductions) lives on the agreement and is inherited; anything a single format does differently is overridden on the rule.

Agreement settings

Details. The name and the effective dates. An order dated outside the window accrues nothing.
Recipients (baseline). The default split. One row per creator, percentages totalling 100. Every rule inherits this unless it overrides it.
Payouts. The payout schedule (monthly, quarterly or annually), which decides the period earnings are bucketed into and the period batches are cut for. When to start running payouts can hold batching back to a date without stopping earnings from accruing before then.
Deductions. The royalty basis (net or gross) and, on a net basis, which deductions apply.
Project Mode. The deal’s advance and how it recoups. See advances and recoupment.
Excluded tags. Orders carrying these tags accrue nothing for the rules in this agreement only.

Rule settings

Rule name and royalty rate (%).
Products. Either a hand-picked list or a query (by vendor, product type, tag, or an explicit selection). A query keeps itself up to date as your catalogue changes, which means a new product that matches starts earning without anybody remembering to add it.
Order criteria. Restrict the rule to or away from B2B orders, and to an include or exclude list of countries. The country used is the shipping country, falling back to billing for orders with no shipping address. An order with no resolvable country fails an include list and passes an exclude list.
Recipients override and Project Mode override, when this format differs from the deal.

Draft and published

A new agreement starts as a draft, with its rules inert. A draft accrues nothing, materialises nothing and appears in no calculation, so you can leave one half finished indefinitely. Publish agreement validates it and makes its rules live.

The validator’s base rule is that a product belongs to at most one live rule inside an agreement. The exceptions are the two cases where double paying is impossible: rules whose effective windows do not overlap, and rules whose order criteria are provably mutually exclusive. That second exception is what makes a region split (“EU at one rate, everywhere else at another”) expressible as two rules sharing the same products.

Across different agreements there is no such restriction. Every live rule covering a product earns on it independently, which is how layered per-author deals work.

Changing a rate

On a live rule the rate field is read only, and Update rate is the way to change it. You give a change date and a new rate; the existing rule is frozen with an end date and a copy of it starts on the new rate at that date. The two versions sit in the same agreement with windows that do not overlap, so earnings keep the rate that was in force when the sale happened.

How a royalty is calculated

In this order, when Shopify reports an order as paid:

Order level carve outs. If the order’s tags match the store’s excluded tags, or it is a B2B order and the store excludes B2B, the whole order accrues nothing.
Line by line. For each line item, the app finds the product, then every rule covering it, oldest rule first.
Per rule checks. The agreement’s own excluded tags and B2B setting, then the rule’s status and effective window, then the rule’s order criteria. A rule that fails any of these is skipped; its siblings still earn.
Gross. Unit price times quantity.
Net, on a net basis only, subtracting in this order: the discount allocated to the line, the line’s prorated share of shipping, and the unit cost times quantity. The result is floored at zero, so deductions can never make a line negative.
Basis. The net amount on a net basis, the gross amount on a gross basis.
Earned. Basis times the rule’s rate.
Split. Each recipient gets the earned amount times their percentage.

Every money figure is rounded to two decimal places as it is stored, half away from zero. Rates are held to four decimal places, so the smallest expressible rate is one hundredth of a percent.

A worked example

The rule pays 10% of net sales, with deduct discounts on and the other deductions off. Its recipients are Ada at 60% and Brun at 40%.

An order line is 3 copies at $24.99, with $7.50 of discount allocated to that line.

Step	Figure
Gross (3 × 24.99)	74.97
Less allocated discount	−7.50
Net, and therefore the basis	67.47
Earned (67.47 × 0.1000 = 6.747, rounded)	6.75
Ada, 60% (6.75 × 0.60)	4.05
Brun, 40% (6.75 × 0.40)	2.70

That writes two ledger rows, one per recipient, each carrying the gross, the net, the basis, the rate applied and the earned amount. Note that each recipient’s share is rounded on its own, so with awkward percentages the recipients’ amounts can differ from the line’s earned amount by a cent.

The ledger

Every figure above is stored, never recomputed. The Ledger page browses the rows and exports them as CSV, and the refunds and adjustments page explains what happens when something has to change after the fact.