Documentation

Importing contract usage

Bulk import contract rules for rights holders and their products (ISBNs) using a CSV template.

After you’ve added your contract types (reusable contract rules), you can use the contract types to specify how royalties are allocated to each rights holder, for each of the products (ISBNs). This page shows you how to do this in bulk using CSV upload — saving you time, for example when you have multiple rights holders using the same contract type.

Because contract types are reusable, you define the royalty terms once and then apply them across as many rights holders and products as needed. This saves you from entering the same contract terms multiple times.

Important: Contract types must exist before they can be used. If you haven’t already, import your contract types first.

If you only need to link one or two contracts, you may prefer to do this via the user interface.

How contract usage works

In Royalties HQ, a contract type defines the royalty rules (e.g. “25% of net receipts”). Contract usage is the link between a contract type, a rights holder, and a product — it tells the system which royalty terms apply to which rights holder for which product.

For example, if three authors all share the same “Standard Author 25% Net” contract type, you would have three contract usage records — one per author–product combination — all pointing to the same contract type.

For more on how contracts work during royalty runs, see the contracts overview.

Download the CSV template

A CSV template is available to download from the contract usage import page:

  1. Go to the main menu, top left, and click Import.
  2. Under ‘What are you uploading?’, choose ‘Contract Usage’.
  3. Click ‘Download contract usage template file’.
  4. The CSV file template will be downloaded to your device.

You can also export all existing contract usage from the same page. This is useful if you want to review or update existing links in bulk.

Prepare your contract usage data

Open the CSV template (or your exported file) in your spreadsheet software — we recommend Google Sheets over Excel.

Each row links one contract type to one rights holder and one product. The import matches records using codes — so you’ll need to know the relevant contract type codes, rights holder codes (or email addresses), and product identifiers (ISBNs or ASINs).

Tip: Make sure your rights holders, products, and contract types are all imported before importing contract usage.

Beware of spreadsheet auto-formatting

Excel and other spreadsheet software can auto-format your data in ways that corrupt it — particularly ISBNs and other long numbers.

Tip: Format all cells as text before entering or pasting data. For detailed instructions, see Introduction to importing.

Upload your contract usage CSV

When you’ve double-checked your data, save the file as a CSV. In Google Sheets, this is File > Download > CSV.

  1. Go to the main menu, top left, and click Import.
  2. Under ‘What are you uploading?’, choose ‘Contract Usage’.
  3. Under ‘Choose your file’ click ‘Browse’ and navigate to your CSV file.
  4. Click ‘Next’.
  5. The file will be uploaded and validated (checked for problems). You will see the results on a preview page.
  6. If the results look good, click ‘Continue’ and the contract usage records will be imported (or, if the preview step highlights problems, you will need to fix the data — read the error message and check the requirements above).