View Categories

Contracts – Examples, Troubleshooting, and Advanced Features

This page completes the contracts section of user guide by showing how to implement real-world royalty agreements in Royalties HQ, troubleshoot common issues, and use advanced features to ensure accurate royalty calculations across even the most complex publishing scenarios.

New to contracts in RHQ? Start here.

Contract Examples #

The following examples demonstrate how to implement different types of royalty agreements in Royalties HQ. Each example shows the contract structure, rule configuration, and expected outcomes. The examples move from simple to complex.

Example 1: Standard Royalty Contract #

Contract Terms: Rights holder receives 10% of Net Receipts for all sales.

Implementation:

  1. Create one rule with no conditions (it will always apply)
  2. Set the action to allocate 10% of Net Receipts

This straightforward contract applies the same royalty percentage to all sales regardless of volume, location, or discount rate. Since there are no conditions, this rule will always match if it’s evaluated.

Example 2: Tiered Royalty Contract #

Contract Terms:

  • Rights holder receives 10% for the first 5,000 units sold
  • Rights holder receives 12.5% for units sold beyond 5,000

Implementation:

  1. Rule 1 (Priority 1):
    • Condition: Units Sold is Less Than or Equal To 5,000
    • Action: Allocate 10% of Net Receipts
  2. Rule 2 (Priority 2):
    • Condition: Units Sold is Greater Than 5,000
    • Action: Allocate 12.5% of Net Receipts

For a title format that has sold 7,000 units, Royalties HQ would automatically split the sales line into two virtual segments: 5,000 units at 10% and 2,000 units at 12.5%.

Example 3: Complex Contract with Multiple Variables #

This example is deliberately complex, mixing conditions types. If you don’t have complex agreements with authors or other rights holders, you can skip this section.

Contract Terms:

  • A flat 5% on all sales in all locations up to 1000 units sold
  • After 1000 units sold, the following rules apply:
    • US sales:
      • 8% of list price for discount under 50%
      • 5% of list price for discount of 50% or higher
    • Rest of world (non-US) sales:
      • 10% of list price for discount under 50%
      • 8% of list price for discount of 50% or higher

Implementation:

  1. Rule 1 (Priority 1):
    • Condition: Units Sold is Less Than or Equal To 1000
    • Action: Allocate 5% of Net Receipts
  2. Rule 2 (Priority 2):
    • Conditions:
      • Units Sold is Greater Than 1000
      • Sale Country is US
      • Discount Rate is Less Than 50%
    • Action: Allocate 8% of List Price
  3. Rule 3 (Priority 3):
    • Conditions:
      • Units Sold is Greater Than 1000
      • Sale Country is US
      • Discount Rate is Greater Than or Equal To 50%
    • Action: Allocate 5% of List Price
  4. Rule 4 (Priority 4):
    • Conditions:
      • Units Sold is Greater Than 1000
      • Sale Country is Not US
      • Discount Rate is Less Than 50%
    • Action: Allocate 10% of List Price
  5. Rule 5 (Priority 5):
    • Conditions:
      • Units Sold is Greater Than 1000
      • Sale Country is Not US
      • Discount Rate is Greater Than or Equal To 50%
    • Action: Allocate 8% of List Price

This complex contract demonstrates how you can combine multiple condition types to create sophisticated royalty structures that account for sales volume, geographic location, and discount rates.

Advanced Features #

Sales Line Splitting with Threshold Conditions #

When using the “Units Sold” or “Total Net Receipts” conditions with thresholds, Royalties HQ automatically splits sales lines that cross these thresholds. This ensures that the correct royalties are allocated based on the rules and conditions you have set.

How Splitting Works:

  1. The system identifies that a sales line crosses a “Units Sold” or “Total Net Receipts” threshold defined in your rules
  2. It creates virtual segments of the sales line, each falling within a different tier
  3. It applies the appropriate rule to each segment
  4. Both the royalty amount and units are divided proportionally between segments

Example: If you have rules for “first 1000 units” and “over 1000 units” and a sales line contains 1500 units, the system will:

  • Apply the first rule to 1000 units
  • Apply the second rule to 500 units
  • Calculate royalties for each segment separately

Using Geographic Conditions Effectively #

The “Sale Country” condition allows you to create country-specific royalty terms:

Regional Groupings: Royalties HQ supports geographic groups such as:

  • North America
  • Europe
  • EU
  • Asia-Pacific

You can use these groupings for broader regional rules instead of selecting individual countries.

Tip: Use the IS NOT operator to select all countries outside a specified country. For example, for all countries outside the US, you would choose ‘Sale country is not US’.

Combining Date Ranges with Other Conditions #

Date Range conditions can be powerful when combined with other condition types:

Common Use Cases:

  • Introductory periods with higher royalties for new titles
  • Seasonal variations in royalty rates
  • Step changes in royalty rates on contract anniversary dates
  • Promotional periods with special terms

To implement these scenarios, add a Date Range condition alongside other conditions in your rules.

Troubleshooting Common Issues #

Rules Not Applying as Expected #

Issue: Rules aren’t triggering as expected during royalty runs.

Common Causes and Solutions:

  1. Rule Priority Order: Check that your rules are in the correct priority order. Remember that the first matching rule applies and the priortity is .
    • Solution: Drag rules to reorder their priorities. More specific rules should have higher priority (lower numbers).
  2. Missing Conditions: Rules with no conditions always match if reached, potentially blocking more specific rules.
    • Solution: Add appropriate conditions to restrict when rules apply, or move “catch-all” rules to the lowest priority.
  3. Condition Logic: All conditions within a rule must be met (AND logic) for the rule to apply.
    • Solution: If you need OR logic between conditions, create separate rules with the same action.

Too Many Royalties Going to Publisher #

Issue: More royalties than expected are being allocated to the publisher. This is typically because, after all rights holders’ contracts are processed, any leftover royalties are allocated to the publisher.

Tip: Your agreement with an author or other rights holder may not state all conditions explicitly. Make sure you include fallback ‘default’ rules with no condition and set to the lowest priority, so that the fallback rule will be checked last. This way, if no other rules match, the final rule will be used.

Common Causes and Solutions:

  1. No Matching Rules: If no rule matches for a rights holder, the rights holder receives no royalty for that sales line. After all rights holders’ contracts are processed, any leftover royalties will go to the publisher.
    • Solution: Add a catch-all rule at the lowest priority to ensure all sales are covered. Even if your agreement with an author or other rights holder doesn’t state it explicitly.
  2. Incomplete Rule Coverage: Your rules might not cover all possible sales scenarios.
    • Solution: Review your rules for gaps in coverage, particularly for different countries, discount rates, or sales channels.
  3. Incorrect Percentage Calculations: The sum of all rights holder percentages may be less than expected.
    • Solution: Verify that your percentages in your contract rules match your agreements with authors and that you’re using the intended royalty model (Net Receipts vs. List Price).

Splitting Not Working Correctly #

Issue: Tiered royalties aren’t calculating properly for sales that cross thresholds.

Common Causes and Solutions:

  1. Overlapping Thresholds: Rules with overlapping “Units Sold” ranges can cause inconsistent results.
    • Solution: Ensure your threshold ranges don’t overlap. For example, use “Less Than or Equal To 1000” and “Greater Than 1000” rather than “Less Than 1000” and “Greater Than or Equal To 1000”.
  2. Missing Middle Tiers: Gaps in your tier ranges can lead to some units not being allocated.
    • Solution: Verify that your tiers cover all possible values without gaps.
  3. Incorrect Priority Order: Tier rules must be in the correct priority order for proper splitting.
    • Solution: Place lower threshold rules at higher priority than higher threshold rules.

Common Misconceptions #

“I need to create a new contract for each title format”

  • Reality: Contracts can be reused across multiple title formats and rights holders. For standard terms, create contract templates once and apply them wherever needed.

“Adding more conditions makes rules more likely to apply”

  • Reality: Each additional condition restricts when a rule can apply, not expands it. All conditions must be met for a rule to apply. If you want to create broader rules, use fewer conditions.

“Rules without conditions never apply”

  • Reality: Rules without conditions always apply if they are reached in the priority sequence. They can be dangerous at high priority levels because they’ll match everything and prevent lower-priority rules from being considered.

“The system automatically knows my royalty terms”

  • Reality: Royalties HQ only applies the rules you explicitly create. If no rules match, the rights holders receive no royalties for the sales line. Always ensure your Royalties HQ contract rules cover all possible sales scenarios, even if they are not stated in your agreements with authors and other rights holders.

Best Practices for Complex Contracts #

  1. Start Simple: Begin with basic rules and add complexity gradually.
  2. Save time by cloning: Clone an existing contract and then make changes.
  3. Test Thoroughly: Create test sales lines that represent different scenarios to verify your rules work as expected.
  4. Document Your Structure: Keep notes about your contract structure and the purpose of each rule, especially for complex arrangements.
  5. Use Clear Naming: Give your contracts and rules descriptive names that indicate their purpose.
  6. Check for Gaps: Ensure your rules collectively cover all possible sales scenarios.
  7. Review Rule Order: Regularly check that your rules are in the correct priority order, especially after making changes.
  8. Consider Fallbacks: Always include catch-all rules at the lowest priority to handle unexpected scenarios.

By mastering these advanced features and troubleshooting techniques, you can create sophisticated contract structures in Royalties HQ that accurately reflect your agreements with authors and other rights holders, ensuring your royalty calculations are correct.