Importing titles and products

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

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 products 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 product, and each will have its own product ID (e.g. ISBN).

Products 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, then Products.
2. On the Products listing page, click the Import button.
3. Under ‘What are you uploading?’, choose ‘Products’.
4. Under this, click ‘Download Products template file’.
5. The CSV file template will be downloaded to your device.

Format your titles data #

1. Open the Products CSV import template downloaded in the previous step (see above) – we recommended using Google Sheets.
2. Each row is one product (in royalties GQ, a title is the ‘parent’ and it can have multiple formats – we call these products).
3. Each product must have at least one product ID such as ISBN, ASIN, or other product ID (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).

*At least one product ID (ISBN, ASIN, or other) is required for each product

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 products 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 products 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 product (ISBN).

Additional Product IDs #

• Additional Product ID include ACX, Google Play, and more – these are optional fields for storing alternative product identifiers
• Use these for proprietary codes, internal SKUs, or custom identifiers that aren’t ISBNs or ASINs
• Product IDs must be unique across all products
• This field is useful for tracking titles in multiple systems

Language #

• Language is an optional field for indicating the language of the product
• Use ISO 639-3 three-letter codes (e.g., “eng” for English, “deu” for German, etc), or plain English labels (“English”, “German”, etc.)
• Leave blank if not applicable or if language is not relevant
• This can be automatically populated via Google Books metadata fetch for new products

Month and period format support #

royalty-period-start-month supports flexible month descriptors:

• Full month names: “January”, “February”, “March”, etc.
• Three-letter abbreviations: “Jan”, “Feb”, “Mar”, etc.
• Numeric format: 1-12 (e.g., 3 for March)

Upload your products CSV #

When you’ve double-checked your product 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 Import.
2. For the type, select ‘Titles‘.
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 products 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 products in bulk #

You can also use the above process to update products in bulk.

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

Note that any new product IDs (including ISBNs or ASINs) in your CSV that are not in a row with a recognised product ID will result in a new product.