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
- On the License Keys page, click Import.
- Click Download the template. It has every column, and example rows to show the format. The template, below, explains what goes in each column.
- 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.
- Add the file to the import window. It's validated right away, and nothing is imported yet.
- 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.
- 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.
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:
| Column | What's in it |
|---|---|
result | Ready, or Problem. |
details | For 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
| Column | Required | What to put in it |
|---|---|---|
product_id | Unless variant_id is filled in | The product. Enough on its own when the product does not have variants. |
variant_id | Unless product_id is filled in | The variant. Enough on its own. |
license_key | Yes | The key. See The key. |
metadata: <name> | No | As 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 inproduct_idtoo, 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 needsvariant_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 1234andABCD1234are 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_key | metadata: Supplier | metadata: Invoice # | The key's metadata |
|---|---|---|---|
ABCD-1234 | Acme Software | INV-1001 | Supplier: Acme Software, Invoice #: INV-1001 |
EFGH-5678 | Acme Software | Supplier: Acme Software | |
IJKL-9012 | None |
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
44123456789012shows as4.41235E+13, and that's what's saved, with the rest of its digits gone. - Leading zeros are dropped, so
00123is saved as123. - 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:
| Problem | Fix |
|---|---|
| Missing an ID | Fill in variant_id, or product_id for a product with one Download & License variant. |
| The key is empty | Fill in license_key, or remove the row. |
| The key has a line break | Put the key on one line. |
An ID or key in scientific notation, such as 5.14516E+13 | Your spreadsheet app changed it. See Editing in Excel. |
| The product or variant isn't set up in the app | Set it up first: configure it, or import it. |
| Set up as Download Only | Change it to Download & License, or remove the row. |
| The product has more than one Download & License variant | Add the variant's ID in variant_id. |
product_id and variant_id don't match | Check the IDs: the variant belongs to a different product. |
| The same key as an earlier row | Remove 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.
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.