Importing Orders
Some orders need to be imported, because the app doesn't know about them. These include:
- Orders placed before you installed the app.
- Orders another app processed, if you're migrating from another app.
- Orders placed before the product went live. The app only processes orders for products that were live when the order was placed.
- Placed before its products went live in this app: import it.
- Placed after, and missing from the app: run Manual Sync. Do NOT import it: imported orders are treated as historical orders and managed differently in the app.
You can start from a blank template and write every row yourself, or generate a template that lists your Shopify orders for you, so all you add is their license keys and content.
Importing with Blank Template
The blank template has every column, with an example row for each way to fill it in. You write every order and line item yourself, which takes more work than a generated template, but gives you total control over what's imported.
- On the Orders page, click Import.
- Under Get a template, choose Download the template, and click Download Template.
- In a spreadsheet, replace the example rows with your own orders, keys, and content. The Template, below, explains what goes in each column. Save it as a CSV file, keeping 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, 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.
- Click Start Import.
The import runs in the background, so you can close the window and leave the page. It reads each order from Shopify as it goes. While it runs, the Orders page shows its progress. When it's done, the page shows the results, and they're also added to the alerts on your dashboard.
Importing with Generated Template
Instead of writing every order and line item yourself, let the app list them from your Shopify orders, then fill in their keys and content:
- On the Orders page, click Import.
- Under Get a template, choose Generate a template, and pick the dates the orders were placed: a range such as Last 30 Days, or your own dates on the calendar.
- Click Generate Template. The import window closes, and the template is generated in the background, like an import. The Orders page shows its progress, and you can leave the page.
- When it's ready, click Download Template on the Orders page, or in the alerts on your dashboard. The template is kept until you dismiss it, and dismissing it deletes the file.
- In a spreadsheet, put a key in the
license_keycell of each Download & License row. Generated Template Details, below, explains the rows and columns. Save it as a CSV file, keeping the header row as it is. - On the Orders page, click Import again, and add the file. It's validated right away, and nothing is imported yet.
- If any rows have problems, 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.
- Click Start Import.
The import runs in the background, the same as with a blank template.
Generated Template Details
A generated template is an import file the app writes for you. It lists every line item on all missing orders, with a row for each quantity (useful for importing license keys). The order and line item are already filled in on every row, so you don't have to work out all the IDs.
A line item is listed when:
- Its order can be imported: it's paid, has no chargeback, and has a customer. See Which orders are imported.
- Its product is set up in the app, enabled or not.
- It was placed before its product went live here.
- The app doesn't have it yet. Generating the same dates again after an import lists only the line items that are still missing. An empty template means every line item from those dates is in the app.
- Quantity greater than 0. A fully refunded line item isn't listed.
Orders are listed oldest first, and each order's rows are together:
- A Download & License line item has a row for each key, by its quantity. A line item with a quantity of 3 has 3 rows that are the same apart from
license_key, which you fill in with a different key on each. - A Download Only line item has one row. You don't need to fill anything in: its product's content comes with the order.
The first columns are filled in for you. Leave them as they are:
| Column | What's in it |
|---|---|
order | The order's name, such as #1001. |
order_date | When the order was placed. |
product_id, variant_id, line_item_id | The line item, as Shopify API IDs such as gid://shopify/LineItem/15123456789012. They tell the import exactly which line item the row is for, and Excel leaves them as they are. See Order and line item IDs. |
sku, product, variant | The line item's SKU, and its product and variant names, to help you find its keys in your other app's export. |
type | Download & License or Download Only, so you can see which rows need a key. |
quantity | The line item's quantity after refunds. |
The last columns are empty, for you to fill in:
| Column | What to put in it |
|---|---|
content | Optional. Content from your library that your other app delivered to this one order, such as a personalized PDF. See Content. |
license_key | On Download & License rows, one key your other app delivered on this line item. |
metadata: Supplier | Optional. The key's metadata. Rename the column, or add more metadata: columns, as in a key import. |
A row you leave without a key still imports its line item, just without that key, and a new template won't list that line item again. To add the key later, import a row with it, or edit the order.
If you copy a column of keys from your other app's export into the template's empty rows, check the two line up row for row. One missing key shifts every key below it onto the wrong order. It's safer to look each key up by its order number, or to add your export's own rows to the file instead.
The Template
| Column | What to put in it |
|---|---|
order | Required. The order's name as Shopify shows it, such as #1001, with or without the #, its ID, its admin address, or its Shopify API ID. See Order and line item IDs. |
product_id | The line item's product, by ID, admin address, or Shopify API ID, as in a product import. |
variant_id | The line item's variant, by ID, admin address, or Shopify API ID. A variant's address includes its product, so product_id can be left empty. |
line_item_id | The line item's ID or Shopify API ID. Filled in by a generated template. See Order and line item IDs. |
sku | The line item's SKU. |
content | Content from your library to give this line item, as well as its product's. See Content. |
license_key | A key your other app delivered on this line item. One key per row. |
metadata: <name> | The key's metadata, as in a key import. |
order_date, product, variant, type, quantity | Only there to read. A generated template fills them in, and the import ignores them. The blank template leaves them out. |
Order and line item IDs
order takes the order in any of these formats:
| Format | Example | Where to find it |
|---|---|---|
| Order name | #1001, or 1001 without the # | The order's name in your Shopify admin, and in your other app's export. |
| Order address | https://admin.shopify.com/store/your-store/orders/5123456789012 | Open the order in your Shopify admin, and copy the address from your browser. |
| Order ID | 5123456789012 | The number at the end of the order's address. |
| Shopify API ID | gid://shopify/Order/5123456789012 | Exports and apps that use Shopify's API. |
line_item_id takes the line item's ID, such as 15123456789012, or its Shopify API ID, such as gid://shopify/LineItem/15123456789012. A generated template fills it in.
Excel saves IDs this long in scientific notation, which loses digits, and the import marks those rows as problems. To keep them as they are, see Editing in Excel, or use the address or Shopify API ID, which Excel leaves alone. A generated template uses Shopify API IDs for this reason.
License keys
- A key that's new to the app is added to the line item.
- A key that's unsold in that product's stock, such as one you imported as unsold by mistake, is taken out of stock for the order instead of added twice. The import warns you before you start, since your stock goes down.
- A key already on this line item is skipped.
- A key on another order is a problem: a sold key belongs to one order. So is the same key on two rows.
- More keys than the line item's quantity in Shopify, after refunds, is a problem. A fully refunded line item can't take keys.
- With Key Uniqueness on, a key in another product's stock is a problem.
Keys are checked the same way as in a key import: one line each, and safe from Excel's changes. See Editing in Excel.
Content
Your products' content needs nothing in the file: an imported order gets it like any other order. Use content for files your other app delivered to one order, such as a personalized PDF.
The content must already be in your library, so import it first. Then name it in content any of these ways, separated by ; for more than one:
- The URL it was imported from, the same one you put in your content import file,
- a link's URL,
- the address of its page in the app, or its ID,
- or its exact name, ignoring capital letters.
Download and time limits start when the order is imported, not when it was placed, and download counts start at zero.
Which orders are imported
- Paid orders only. An unpaid order, or one with a chargeback, isn't imported.
- With a customer. An order without one has no customer account to show it in.
- With at least one line item for a product set up in the app.
- Orders this app processed only get your other app's line items: those placed before their product went live here. Their other rows are skipped, so the keys this app gave them stay as they are: sync or edit those orders instead. The import tells you how many before you start.
- Orders an earlier import brought in only get what's missing, so once you've fixed the rows that failed, you can import the whole file again.
After an order is imported
Imported orders stay in sync with Shopify, like orders from before the app was installed: refunds and returns take keys back, but nothing assigns them keys from your stock, and their keys are never restocked. A line item the import didn't bring in, such as one whose product you set up later, never gets keys from your stock either, since your other app processed it. Generate a template for the order's date, or add a row for it with its keys, to bring it in. Or edit the order to add keys yourself.
An imported order shows an Imported badge beside its name, and so do its keys, since they can never be restocked. The Orders page's Was Imported filter lists them. An order this app processed, which the import only added your other app's line items to, isn't counted as imported.
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 and a details column that says what went wrong with a failed row, or why a row was skipped. Fix the failed rows in the report and import it as it is: the result and details columns are ignored, and everything already imported is skipped.
| Problem | Fix |
|---|---|
| Order not found in your store | Check the order's name or ID. |
| More than one of the order's line items fits the row | Add the line item's ID, listed in the report, in line_item_id. |
| None of the order's line items match the row | Check its line_item_id, product_id, variant_id, and sku. |
| None of the order's line items are for products set up in the app | Set up its products first. |
| More keys than the line item's quantity | Remove the extra keys, or check they're for the right line item. |
| The key is already on another order | Check the key and the order. A sold key belongs to one order. |
| Not found in your content library | Import the content first, or check its name or URL. |
| Shopify couldn't be reached | Import the report again. |
Limits
- 10 MB and 50,000 rows per CSV file. Split a bigger file into several: a generated template stops at the limit for you.
- One import at a time, of any kind, and generating a template counts as one.
- Orders older than 60 days need the app to be able to read your full order history, which it asks for when you install it.
Importing orders, and generating a template, needs the Create and Edit permission for orders. Downloading a template or an import's report needs the Export permission for orders, unless you started it. See Staff & Permissions.