EZ Importer Documentation
Getting started with EZ Importer is as simple as uploading your file. Once you have your import file ready go to the home page and click the Import Orders button on the top of the screen. This will display a dialog box for you to start your import.
On the Order Import dialog you will see a Name field, Data Mappings field, Select files button and a Review Import button. The name and Data Mappings fields are required. You should add a descriptive name for your import. The Data mappings field contains a list all "Data Mappings" you've created as well as a Add New Mapping option. On your first import you will see this option only. You can select this option at anytime to create a new data mapping based on the file you are importing.
Once you've filed out the required fields you are ready to select your file. Click the "Select files" button to select the file you want to import. Once you have filled out all the necessary fields you can click the "Review Import" button. This will bring you to the Data Mappings page where you can select the headers from the csv file you've selected to import. If you do not want to continue with the import you can click the "Close" button.
A Data Mapping contains information on how to "map" your import file. The mapping allows you to map your import columns to the shopify fields you wish to import. The mapping uses the column name in the csv file to associate the value in the column with the shopify field so you must have a header row (which must be the first row in the csv file) in your import file. The field name in the "Header Name" column must match exactly with the field name in the csv header row. The "Header Name" field is case sensitive.
The fields section of the data mapping is broken into multiple tabs. You will see an asterisk next to a required field in that tab. If you select one field within the the tab you must select all required fields within that tab. If you have not selected a field within a given tab the required fields will be ignored.
The name field at the top of the "Data Mapping" is required and must be unique. The value provided for name must not be associated with another Order in your store or you will receive an error. We currently do not support Order updates at this time.
EZ Importer requires all import files to have an Order Name field. This field is used to help manage unique orders and orders with multiple line items in your input file. If you don't want to send this order name field to Shopify you can click on the "Ignore order name during import" checkbox. If this checkbox is clicked EZ Importer will not send the "Order Name" to Shopify, allowing Shopify to auto-generate this field for you.
Once you've created your Data Mapping you are now ready to import your first csv file. A "Data Mapping" may be associated with as many imports as you wish, their is no limit to the number of "Import Orders" a "Data Mapping" may be associated with. The idea here is you can import as many orders as you want based on the same Data Mapping.
On the Data Mapping page EZ Importer allows you to add some custom configurations to your imports. These are features that are useful to many stores but are not part of our default configuration.
On the data mapping page you'll see a section called Custom Configuration. At this time we offer to custom configuration options. The first is to let Shopify generate the order name when doing the import. There are times when you may want Shopify to generate the order name instead of using the one in your csv file. You can read more about this in the order name section.
The second configuration is used to link your products by their SKU. This is an optional configuration as it will slow down your imports since EZ Importer will now have to look up product information for each line item. This is an expense process. You also need to ensure all of your SKU numbers are unique. Shopify does not enforce uniqueness on this field, it is up to you to ensure there are no duplicate SKU numbers in your product catalog. You can read more about this feature in the link by sku section
EZ Importer requires all orders to have the "Order Name" field. This field is used by shopify to represent the customer's order name. EZ importer also uses this field to help uniquely identify an order in your import csv. If the csv file has multiple rows with the same "Order Name" EZ Importer looks at these orders as one order with multiple line items. EZ Importer also uses the "Order Name" field to check for duplicate orders. If an order with the same "Order Name" exists in your store EZ Importer will not import the order.
There are times when you do not want to provide the "Order Name" with your import. Although this field is required for EZ Importer, we do allow you to exclude the field when importing to shopify. If you wish to exclude the "Order Name" during the shopify import process you can click the "Exclude order name during import" checkbox on the "Data Mappings" section.
It's important to understand that by "Excluding" the "Order Name" from your shopify import EZ Importer is no longer able to check for duplicate orders. When you click the "Exclude" order name checkbox EZ Importer no longer does the check because the order name is generated by shopify. You will need to ensure you are not importing duplicate orders if you have "Exclude Order Name" turned on.
When doing imports you may want to link your orders to their products. You can do this by either providing the Shopify Product Id and Variant Id or you can link them by SKU. It's preferable that you link the import by Shopify Product Id and Variant Id for two reasons. The first and most important is accuracy. These two fields are unique in the Shopify admin. The second reason we prefer you link your products by their id is because it's more efficient. When linking by Shopify Product Id and Variant Id we just need to provide these values and Shopify will link the products for us. This is a very efficient process.
We understand that providing the Shopify Product Id and Variant Id is not always easy and many of you may be maintaining a list of SKUs with your products. Sometimes getting the SKU for the order is a lot easier than trying to maintain a list of Shopify Product and Variant Ids. To try and make things as easy and flexible as possible we have a feature that will allow you to link the product by its SKU.
In the Custom Configuration section of the Data Mappings you can turn this feature on. From here all you need to do is select the Link product by SKU checkbox. This will tell EZ Importer to try and find the product by SKU when doing an import. Once you've checked this checkbox you'll need to select the line_item.sku Shopify Field. Click on the Line Items tab and click the checkbox to the left of the line_item.sku field. This will activate the field.
There are a few reasons why we've made this a customer configuration. The first and most important is because the SKU numbers are not forced to be unique in the Shopify admin. This means you, the store owner, need to ensure the SKU numbers are unique. EZ Importer looks up the product information using the SKU and will gab the first one it finds. If you have multiple products with the same SKU there is a chance EZ Importer may grab the wrong product. As long as your SKU numbers in Shopify are unique EZ Importer will find the correct product.
The second reason we make this a custom configuration is it slows down your import. When you turn this option on EZ Importer has to look up the product for each line item which is an expensive process. This will slow things down. You may not care about this but we want to ensure EZ Importer runs as fast as possible by default.
EZ Importer allows you to upload CSV files up to 20MB in size. With all fields selected in the "Data Mappings" section this will allow you to upload a little more than 20,000 orders. If you are uploading a subset of the fields in the "Data Mappings" section you may be able to upload more than 20,000 orders.
Uploading large files could take a few minutes so it's best to be patient. We estimate a 20MB file could take up to 5 minutes to upload depending on your internet connection. If you click the "Close" button before your upload is complete it will cancel.
Have a file larger than 20MB? Contact us and we'll help you import your orders!
EZ Importer supports multiple CSV delimiters. Your CSV file can use the following delimiters when importing with EZ Importer; comma, semi-colon, pipe and tabs. If you upload a CSV file that does not use one of these delimiters EZ Importer will will throw an error. Also note that EZ Importer uses the Excel dialect when importing, by default we use double quotes to escape delimiters in your data.
If you have any questions about csv delimiter support or would like us to support a delimiter that your file uses feel free to Contact Us.
Now that we've imported our order we must review it. Clicking the "Review Import" button on the "Order Import" dialog brings you to the review page. Here you can look over the details of the import. You can also review the data from your csv file to ensure it was imported correctly.
There are a few sections to pay attention to here. The first and most import section is the Data to Review section of the page. Here you can look over your import data. It's important you review the data to ensure your import file was read correctly. If you see an error in the file you can click the Decline button (we plan on creating a re-upload feature in the near future), go back fix your import file and create an new "Order import" from the homepage. If your import looks good you can click the Import button which will start your import.
If there is an error importing an individual order the app will log the error and move to the next individual order in the import. At the end of the Import we will display what orders had errors and what orders were successfully imported.
After the order has run if there were errors we will display them in the Error Messages section. This section will list the "Order Name" that had the error and the error itself. In the Import Data section you will see successfully imported orders marked green and orders that have errors marked red.
Shopify allows 1 api call every 2 seconds under normal circumstances. This means a single order will be imported every 2 seconds. During our testing we've seen this number grow with large data imports. We have seen shopify throttle the api calls between 6 and 10 seconds per single order import. So you may see longer upload times for large order imports. EZ Importer processes your orders in the background so once the import has started you can leave the view import page without having to worry about your import stopping.
If an order is successfully imported shopify will send the shop owner an email letting them know an order was imported. This means you will receive a notification from shopify for every import in your import file. If you have a large import file this means you will get inundated with emails. At this time shopify does not have a way for application developers to turn this off so you must do this manually. We've tried to make this as easy as possible for store owners. When you first go to the "Import Order Review" page, you should click the "Disable Email Notifications" button on the page. Remember this does not be disabled per import as it is a store wide setting.
This will bring you to the shopify "settings/notifications" page of your store admin. Once you are here go to the "Order Notifications" section. You will see a section that has an "Enable/Disable" button. You can click this button to turn your notifications on or off. Remember disabling this setting will turn notifications off for your entire store so you may want to put turn this on after the import.
Also note we will NEVER send email notifications to your customers. No matter how many orders you successfully import they will NOT trigger email notifications to your customers.
Shopify Order Calculations
When importing orders shopify will calculate the total and subtotal fields based on your import data. In order to ensure these fields are calculated properly you should have the following fields in your csv file and selected in your "Data Mappings" configuration.
- The "Line Items Price" field will be used to build your subtotals. This field will be multiplied by the "Line Items Quantity" field. This will give you your subtotal.
- You can apply discounts to your orders by mapping your discount fields to the "Discount Codes" tab in the "Data Mappings" section. You should fill out the "Discount Code" and "Discount Amount" fields. This will allow your discounts to show up in the shopify order. The discount will be applied to the order by selecting the "Total Discount" in the "Order Details" section of the "Data Mappings".
- You can apply shipping charges to your orders. You can do this by filling out the "Shipping Lines" tab of the "Data Mappings". The "Shipping Lines Title" will display the shipping title for the order. You must fill out the "Shipping Lines Price" in order for shipping charges to apply.
- You can apply taxes to your order by filling out the "Total Taxes" field on the "Order Details" tab of the "Data Mappings." This will then apply any taxes to the order.
With all these fields filled in Shopify will calculate your Order "Total".
It can be difficult to figure out how far along a large import is. To try and keep you up to date on your import status we have added an import progress bar on the "Review Import Order" while your order is running. This way you can see how far along your import is. Closing this page will not stop your import so if you have a large import you can start the import and then come back to this page to check the status. You do not need to refresh the page for the progress bar to change, it will update itself. However you will need to refresh the page when the order hits 100% to see your final status and what orders were successfully imported and which orders may have failed to import.
Importing Orders with Multiple Line Items
There may be occasions in which you want import multiple line items for an order. You can do this by by using the same "Order Name" for multiple orders with in your csv file. EZ Importer builds the order from the first order with the "Order Name" in the file and it will add the line items for all other orders with the same "Order Name" in the csv file.
For example you have two t-shirts your shop has sold. In the import file you would add an entry for each line-item. We are going to assume the Order Name for this order is 11010. You need to mark each line in the csv file with this order number. EZ Importer will find the first entry for Order Name 11010, when it finds the second entry with the same Order Name it will ignore all fields except for the line item fields you've specified in the Data Mapping.
If you've reviewed your order import and realized you made a mistake you can simply decline the Order Import. At this time we do not allow re-uploading your csv file. Instead you can click the "Decline" button on the Order Import Review page, which will mark the Order Import declined and you will no longer be able to import your order. This will prevent you from importing an order with an error by mistake and it will keep your import history clean.
When you click the "Decline" button you will be brought to another page that will ask you to confirm the decline. From here simply click the "Yes, I'm sure" button and the order will be marked as declined.
Once the button is clicked the order will be marked as declined. The next time you bring up the order review page for this order it will no longer allow you to import and you will see a message at the top of the page letting you know the order has been declined.
Note: You can also decline the order from the "Import Action" buttons on the homepage. See next section for more details.
Once you've imported your orders you may want to go back and delete the orders from shopify. If this is the case, EZ Importer allows you to delete all the orders from an Import (NOTE: We will be releasing a range and single order import in a future release). After your import has completed you the "Import" button will be replaced by a "Delete Imported Orders" button on the bottom of the View Import Order page. If the order was not successfully imported this button will not appear.
The "Delete Imported Orders" button will ONLY delete orders that have successfully been imported by this "Import Order". It will not delete any other orders from your store. Once you click this button you will be presented with a warning page asking you to confirm your order deletion.
This action is NOT reversible, so once you click the "Yes, I'm sure" button you can not get those orders back unless you re-import the file. If you decide to delete the orders associated with this "Import Order" you can go back to the "View Import Order" page to see the progress of your deletion. The progress bar works the same way as the import progress bar.
Once the order is deleted the "Import Order" will have a status of DELETED and you will no longer be able to perform any more actions on that "Import Order". As always, if you have any questions or concerns about the delete action please let us know.
Cancel a Running Import
When an import is running there are times you may want to cancel the job. You can do so by clicking the Cancel Import button at the bottom of the Review Shopify Import page.
Once you click the button you'll be brought to a confirmation page. Click the Yes, I'm sure button to cancel your job. For a more detailed explanation about the feature click here.
On our app's homepage, you will see a bunch of buttons in the Actions column.
Clicking the Review & Import button will bring you to the "Order Import Review" page where you can review your data and import your orders. Clicking the Delete button will delete all orders from that import, this button brings you to the "Delete Order" confirmation page. The View button will be displayed for orders that have been imported, declined or have an error. Clicking this button will bring you to the "View Import Order" page. This page is the same as the "Review Import Order" page except you can not perform any actions (i.e. Import or Decline). This page is here for your records and so you can see the status of your Import Order.
A few other things to know about the Orders Imported section on the homepage. This table will display details about your Import Order. You can see the status, the record count, the orders imported and the data mapping associated with the Import Order. If you want more details for the order click on the View or Review & Import actions.
EZ Importer supports two date fields at this time, "processed_at" and "closed_at". Date Fields take a date and time as input. When working with date fields we recommend you use ISO 8601 Format. We realize that not all systems may be able to support this format type so we also allow other formats. The time part of a date field is not required. If you do not supply a time with a date field we default the time to 12:00AM of the date provided.
Some Formatting Examples
- ISO 8601 Format: 20170701T13:00
- ISO 8601 Format no time: 20170701
- Month/Year/Day format: 07/01/2017
- Month/Day/Year 24 Hour Clock: 07/01/2017 13:00
- Month/Day/Year AM/PM Clock: 07/01/2017 1:00PM
- Month-Year-Day format: 07-01-2017
- Month-Day-Year 24 Hour Clock: 07-01-2017 13:00
- Month-Day-Year AM/PM Clock: 07-01-2017 1:00PM
If you do not provide a timezone with the date field EZ Importer will use the timezone that is associated with your shopify account. If you are comfortable with ISO 8601 Format and would like to provide a UTC offset you can do this as well. Our date fields support the full ISO 8601 Format.
When importing date fields it's important to know that formats that have the day first are NOT supported. EZ Importer has to make an assumption and when the day is less than or equal to 12 it's hard to know if the first two digits are the day or month. Because of this we assume the first two digits are the month. Please make sure you format your date fields accordingly or you will see orders with incorrect dates.
If you have any questions about how date fields work with EZ Importer please feel free to contact us. We're always happy to help!
We provide the last 100 activities so you can tell whether an Import order was run successfully or not. From this log, you can see the Action performed, the File Name, Data Mapping associated with the Import Order, the Status of the action, the Message associated with the action and time it ran.
We also provide a search box for you to quickly filter your log data.
EZ Importer generates logs of all imports that are imported to Shopify. We also keep the csv file that is used to import the orders. When EZ Importer performs an import we store each record in our database which can generate a large amount of data. At this time EZ Importer will keep all import data and logs in our system for a minimum of 30 days. After the 30 days has expired we may need to remove some of the older data and logs from our database to ensure the system performs in the most efficient way. We will NEVER remove any data from your Shopify account (unless you use the "Delete" feature).
At this time we will keep the csv files that were used for all imports. These files may be deleted at your request.
Our billing system is based on credits. When you first install the app we give you 75 free credits. This allows you to test the application at no charge. An individual credit can be used for 1 import. So if you have an "Import Order" with 5 orders, it will take 5 credits to import that order. The credits will be deducted from your account ONLY if an order is successfully imported. If an order errors for any reason EZ Importer will not remove the credit. For example, if you have a csv file with 5 orders in it and 3 orders successfully import and 2 error out, you will only have 3 credits removed.
Your available credits are always displayed on the top bar of EZ Importer, you can see them on the top right hand side in a blue button.
If you would like to purchase credits you can click on the blue button labeled "Credits Available". This will bring you to the "Credit Bank" page. The credits you purchase have no expiration date, they will NEVER expire.
The "Credit Bank" page is where you view the details about your credits and purchase more credits as needed. On the top of the page you can see how many credits you have purchased, how many you have used and how many you have available. On this page you can also see a full list of your credit bank history in the "Billing History" section. Every credit you've purchased will show up in the bank.
On the right side of the "Billing History" is the "Import Credit Packages" section which allows you to purchase credits at any time. Here you will see a drop down that will have a list of the credits packages we offer. You can click the drop down, select the package you want to purchase and click the Purchase Now button. From here you will be taken to the shopify billing page where you can approve your purchase. Once you click approve button the credits will be added to your account and they will show up in the "Billing History".
It's also good to re-iterate that your credits NEVER EXPIRE. They are available FOREVER.