Skip to main content

Importing License Keys

Instead of pasting keys one product at a time, you can add many keys at once from a CSV file, one key per row, with any metadata. This is the quickest way to bring your unsold keys over from another app.

Keys are added unsold, to Download & License products and variants that are already set up in the app. To set those up first, import your products or configure a new product.

Importing a file​

  1. On the License Keys page, click Import.
  2. Click Download the template. It has every column, and example rows to show the format. The template, below, explains what goes in each column.
  3. Fill in one row per key in a spreadsheet, then save it as a CSV file. Keep the header row as it is. Columns can be in any order.
  4. Add the file to the import window. It's validated right away, and nothing is imported yet.
  5. If any rows have problems, the window sums them up. Click Download Validation Report to see what's wrong with each row, fix them, and add the file again. Or tick the box to skip those rows and import the rest. See Validating Your File.
  6. Click Start Import.

The import runs in the background, so you can close the window and leave the page. While it runs, the License Keys page shows its progress. When it's done, the page shows the results, and they're also added to the alerts on your dashboard. Dismiss them in either place, and they're gone from both.

Migrating from another app

Import each product's unsold keys as you take it live, from an export made after you turned off its processing in your other app, so your other app can NOT have sold any of them since. See Taking a product live.

Validating Your File​

When you add your file, it's validated before anything is imported. The import window shows the results in one banner:

  • Red if any rows have problems: how many rows have problems, out of how many, and each kind of problem with how many rows have it.
  • Green if every row is ready to import, with anything you should know about them, such as keys that are already in their product's pool, which will be skipped.

Warnings, such as keys for enabled products with Auto Sync Inventory on, or keys already in another product, show in their own yellow banner. Read them before you start.

The Validation Report​

To see every row, click Download Validation Report. It's your file as a CSV, with two columns added at the front:

ColumnWhat's in it
resultReady, or Problem.
detailsFor a problem, what's wrong and how to fix it. For a ready row, anything you should know, such as that the key will be skipped, because it's already in its product's pool.

Everything else is just as you wrote it: your columns, in their order, with their headers, even ones the import doesn't use.

To fix the problems, edit the rows marked Problem, in the report or in your spreadsheet, and add the file again. The result and details columns are ignored on import, and replaced each time the file is validated, so you can keep fixing the same report until every row is ready. If you open it in Excel, see Editing in Excel first.

The validation report is made in your browser from your file. Nothing is imported or saved until you click Start Import. After the import runs, it has its own report of what happened to each row: see When rows fail.

The Template​

ColumnRequiredWhat to put in it
product_idUnless variant_id is filled inThe product. Enough on its own when the product does not have variants.
variant_idUnless product_id is filled inThe variant. Enough on its own.
license_keyYesThe key. See The key.
metadata: <name>NoAs many as you like, such as metadata: Supplier. See Metadata columns.

Which product gets the key​

product_id and variant_id each take one ID, in the same formats as a product import: an address from your Shopify admin, a plain number, or a Shopify API ID. See Product and variant IDs.

  • With variant_id, the key goes to that variant. If you fill in product_id too, it must be the variant's product.
  • With only product_id, This only works when the product has no variants. A product with more than one variant needs variant_id, to say which.

The product or variant must already be set up in the app as Download & License. It can be disabled.

The Key​

  • Everything in the cell is the key, spaces inside it included, so ABCD 1234 and ABCD1234 are different keys. Spaces at the start and end are removed, as when you paste keys.
  • One line. A key with a line break in it has a problem.
  • Keys made of digits can be changed by Excel. See Editing in Excel.
  • Each key once. The same key twice for the same product is a problem. With Key Uniqueness on, so is the same key anywhere in the file.

Metadata columns​

Each metadata column's header is metadata: followed by a name, such as metadata: Supplier or metadata: Invoice #. Capital letters, and spaces around the colon, don't matter. The name is used exactly as you write it.

Each key gets an entry for every metadata column with a value in its row. An empty cell adds nothing: the key doesn't get that name with an empty value. For example:

license_keymetadata: Suppliermetadata: Invoice #The key's metadata
ABCD-1234Acme SoftwareINV-1001Supplier: Acme Software, Invoice #: INV-1001
EFGH-5678Acme SoftwareSupplier: Acme Software
IJKL-9012None

Each name can only have one column. A column headed just metadata, without a name, is a problem with the file.

Previously Existing Keys​

An import only adds keys. It never changes or removes a key, or its metadata. So once you've fixed the rows that failed, you can import the whole file again.

  • A key that's already in its product's pool is skipped, as when you paste it.
  • With Key Uniqueness on, a key that's already in another product is skipped too. The import warns you before you start, since that's more often a wrong ID than a key you meant to add again. Check those rows' IDs.
  • Deleted keys don't count, so a key you deleted can be imported again.

The report says why each skipped row was skipped.

Previously Sold Keys​

This import adds unsold keys. Keys your previous app already sent to customers belong to their orders, so importing them here would put them back on sale. Leave them out of your file, and bring them in with their orders instead: see Importing Orders. If a sold key does end up in stock, the order import takes it back out for its order.

Editing in Excel​

Excel changes some values when it opens a CSV file, and saves them changed:

  • Long numbers turn into scientific notation. A variant ID like 44123456789012 shows as 4.41235E+13, and that's what's saved, with the rest of its digits gone.
  • Leading zeros are dropped, so 00123 is saved as 123.
  • Some values turn into dates, such as 3-12.

To keep your values as they are, open the file from Excel's Data tab with From Text/CSV, and under Data Type Detection choose Do not detect data types, so every column stays text. Or set a column's format to Text before you paste into it. It matters most for product_id, variant_id, and license_key. Other spreadsheet apps can change values too, so the same goes for them.

Product and variant addresses and Shopify API IDs are text, so they're never changed. If an ID was changed to scientific notation, the import says so: paste it again in a column formatted as Text.

Keys made of digits are the most at risk. The import refuses a key in scientific notation, since importing it would sell a key with digits missing. But it can't tell a key that lost its leading zeros, or became a date, from a real one, so check those before you import.

When Rows Fail​

The results show how many rows were imported, skipped, and failed. Click Download Report to see what happened to each row. It's your file as a CSV, with a result column (Imported, Skipped, or Failed) and a details column that says what went wrong with a failed row, or why a row was skipped. To retry the failed rows, fix them in the report and import it as it is: the result and details columns are ignored, and the keys that were already imported are skipped.

Common problems:

ProblemFix
Missing an IDFill in variant_id, or product_id for a product with one Download & License variant.
The key is emptyFill in license_key, or remove the row.
The key has a line breakPut the key on one line.
An ID or key in scientific notation, such as 5.14516E+13Your spreadsheet app changed it. See Editing in Excel.
The product or variant isn't set up in the appSet it up first: configure it, or import it.
Set up as Download OnlyChange it to Download & License, or remove the row.
The product has more than one Download & License variantAdd the variant's ID in variant_id.
product_id and variant_id don't matchCheck the IDs: the variant belongs to a different product.
The same key as an earlier rowRemove one of them.

Limits​

  • 10 MB and 50,000 rows per CSV file. Split a bigger file into several.
  • One import at a time, of any kind: wait for a product or content import to finish before starting the next.
  • Saving from Excel with ; between columns is fine. The import works out which separator the file uses.
note

Importing keys needs the Create and Edit permission for license keys, the same as adding them by hand. Downloading the import's report needs the Export permission for license keys, unless you started the import. See Staff & Permissions.