View Categories

Importing titles and title formats

This page will walk you through the steps to import your titles, whether importing new title formats or importing updates to existing title formats.

If you want to add only one or two new titles, you may prefer to do this through the user interface. However, if you are looking to import titles and data in bulk, you are in the right place.

Please note that title formats are specific editions of a title. For instance, a title might be called “My Book” and may have multiple formats: softcover, hardcover, ebook and audiobook. Each of these editions/formats is known in Royalties HQ as a title format, and each will have its own product ID (e.g. ISBN).

Title formats can be imported in bulk using the CSV upload feature. A template is available to download from the Rights holders > Import page.

Download the titles import template #

  1. Go to the main menu, top left, and click Titles.
  2. On the Title formats listing page, click the Import Title formats button.
  3. Under ‘What are you uploading?‘, choose ‘Title formats’.
  4. Under this, click ‘Download Title formats template file’.
  5. The CSV file template will be downloaded to your device.

Format your titles data #

  1. Open the Title formats CSV import template downloaded in the previous step (see above) – we recommended using Google Sheets.
  2. Each row is one title format (in royalties GQ, a title is the ‘parent’ and it can have multiple formats – we call these title formats).
  3. Each title format must have at least one of ISBN or ASIN (and these must be unique).
  4. All other fields are optional.
  5. When your data is ready, save as a CSV. In Google Sheets, this is File > Download > CSV.

When formatting your data, you must follow these requirements:

  • You must format numbers as text
  • Dates must be in this format: YYYY-MM-DD (e.g. “December 30, 2020” must be entered as “2020-12-30”)
  • The tier calculation type (tier-type column) must be either units-sold or total-net-receipts (More info on tiers, and tier calculation type is here).
Column Name Description Required Format/Values
name Full title of the book Yes Text string
title-code Unique identifier for the title (parent record) Yes Alphanumeric (e.g., T000047)
royalty-period-start-month Starting month for royalty calculations Yes Number (1-12). For example, 3 = March.
royalty-period-length Length of royalty period in months Yes Number (typically 3, 6, or 12). How many months interval between royalty runs. E.g. Annual = 12.
product-type Format type of this edition Yes softcover, hardcover, ebook, audiobook
status Publication status Yes active, inactive, withdrawn
imprint Publisher imprint name No Text string
isbn ISBN-13 for physical formats Conditional* 13-digit ISBN without hyphens
asin Amazon Standard Identification Number Conditional* 10-character alphanumeric
number-pages Page count for physical books No Integer (e.g., 300). Optional. Leave empty if not needed.
legacy-units-sold Historical units sold before using Royalties HQ No Integer (e.g., 250). Optional. Leave empty if not needed.
legacy-earned-royalties Historical royalties earned before using Royalties HQ No Decimal (e.g., 16.95). Optional. Leave empty if not needed.
rights-holders Rights holder code(s) Yes Single code (e.g., RH0058) or comma-separated for multiple
date-first-published Initial publication date No YYYY-MM-DD format
date-withdrawn Date format was withdrawn from sale No YYYY-MM-DD format

*Either ISBN or ASIN is required for each format

Other data #

Title codes #

  • On Royalties HQ, each title is given a unique identifier – a title code. Note: a title is NOT an ISBN.
  • All formats of the same book share the same title code.
  • A title code will be generated automatically when you create a new title – whether via the user interface or via import. You can specify a title code on import. This is important for grouping title formats under one title. For instance, if you are importing a new edition of a title, you should import it with the relevant title code.
  • If you do not specify a title code on import, any new title formats will be generated under new titles.

Rights Holders #

  • Must match existing rights holder codes in Royalties HQ.
  • Import rights holders first if they don’t yet exist in Royalties HQ.
  • Leave blank if no rights holder is assigned yet.

Legacy Data #

  • Optional.
  • Use legacy fields to record historical sales before you were using Royalties HQ.
  • These amounts are essential where a contract uses total units sold to determine a rights holder’s current royalty rate for a title format (ISBN).

Upload your title formats CSV #

When you’ve double-checked your title format data, you can go ahead and import it into Royalties HQ. Here’s how you do this:

  1. Go to the main menu, top left, and click Titles.
  2. On the Titles listing page, click the Import Title formats button.
  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 title formats 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 below).

Update title formats in bulk #

You can use the above process to update title formats in bulk.

The CSV import will match existing title formats on ISBN or ASIN. Blank fields will be ignored; these will not overwrite existing data.

Note that any new ISBNs or ASINs in your CSV will result in new title formats.