EZ Exporter Documentation

Knowledge Base

Add a Data Settings

The first step to get started is to create a Data Settings. A "Data Settings" contains information on how to filter your data, which fields to include, the field names in the header row, and the column order in the exported file.

The data will be exported in the order the selected fields appear in the Data Settings page. The fields can be re-ordered on this page by simply dragging and dropping the rows as shown in the screenshot below.

Once you've created a Data Settings, you can now create an Export Profile, where a Data Settings can be assigned. A Data Settings can also be assigned to multiple export profiles. The idea here is you can create multiple export profiles with different configurations using the same set of data based on the Data Settings.

For example, you may want a comma-delimited copy of the report emailed to you daily which you can then import into your accounting software. But a supplier may also need a copy of the report but their system requires you to send them via FTP and the file needs to be tab-delimited. In this case, you simply create two separate export profiles using the same data settings: the first export profile using comma as the data separator/delimiter and set to be delivered via email and the second one using tab and set to be delivered via FTP to your supplier's FTP server.

Add an Export Profile

EZ Exporter allows the creation of up to 10 different export profiles (if you need more, please contact us). We provide a bunch of options for you to customize certain parts of the report, how it should be delivered, and whether to schedule the report to be sent automatically.

We've provided reasonable defaults to make it easier for you to get started.

Some settings worth mentioning:

  • Data separator: This is also known as the data "delimiter." While most systems use comma as the delimiter, some use other characters such as tab, semi-colon, and pipe/vertical bar.
  • Filename pattern: This allows you to specify the exported file's name. The main thing to note here is we provide an optional tag {{ timestamp }} which you can place anywhere in the filename pattern to generate a dynamic timestamp based on when the file was created in yyyymmdd_hhmmss format. For example, open_orders_{{ timestamp }}.csv will produce a filename that looks something like this: open_orders_20161024_010007.csv
  • Use TLS: For additional security, some FTP servers require TLS (also commonly referred to as SSL) to encrypt the data during the file transfer. FTP with TLS/SSL enabled is also known as FTPS.
  • Schedule: You can schedule automatic report generation hourly or daily at a specified time. Note that the time format can be either in 12-hour or 24-hour format. Also note that the schedule will run based on your store's timezone setting.

The ability to create multiple profiles should hopefully help you automate more of your processes. You can create multiple profiles and data settings for different order status, different profiles for different vendors containing only the data they need, or even different profiles with different schedules.

If a profile is scheduled, it will just run automatically at the scheduled time. Though we also provide you an option to run them on demand or simply download the file right away from the EZ Exporter app homepage.

Export Profile Actions

On the app's homepage, you will see a bunch of buttons in the Actions column.


Clicking Run will generate the report and send it to the Destination (email or FTP) right away. Clicking Download will generate the report to be downloaded by your web browser.

Activity Log

We provide the last 100 activity log so you can tell whether a task ran successfully or not and other information that could be useful to you. From this log, you can see what time a report was generated, how many records were included in the report, the data settings associated with an export profile at run time, who/where the report was sent to, and whether the task was successful.

The activity log is particularly useful when initially setting up an export profile that is set to run on schedule. This way you can run it on demand from the app's homepage first to see whether it will successfully run. If there are problems, we try to provide useful information for you in the Message column.

For example, in the screenshot below the FTP task failed due to an incorrect login:

Also note here that we provide a search box for you to quickly filter the log data.

Data Settings Primary Filters

We provide a set of primary filters you can use to filter your data.

Created

Filter data based on when the order was created.

  • Any - Orders placed since the very beginning.
  • Today - Orders placed today.
  • Yesterday - Orders placed yesterday.
  • Since Yesterday - Orders placed from yesterday until today so far.
  • Since Last Run - New orders placed since the last time the report successfully ran (based on the Export Profile this Data Settings is assigned to). The "Run" can be manual or scheduled. Note that the "Download" action is not considered a "run" and thus ignored.
  • Last 7 Days - Orders placed from the last 7 days until today so far.
  • Last 30 Days - Orders placed from the last 7 days until today so far.
  • Month to Date - Orders placed from the beginning of this month until the current day.
  • Year to Date - Orders placed from the beginning of the year until the current day.
  • Custom - Specify a custom date range.

Advanced Options

For additional flexibility, we've provided the options below.

Custom Filters (Optional)

You can filter your data further using Custom Filters, which can be found in the Data Settings.

EZ Exporter Shopify App - Custom Filters

Custom Filters gives you the flexibility to filter your data based on values of one or more additional fields and a set of conditions assigned to them. When using multiple conditions, you can specify whether the data should match any or all of those conditions. You can get really creative here.

A couple of examples:

I want to create a report of orders placed by VIP customers that are shipping outside of Canada where the total amount is over 1000.

To meet the conditions above, simply set your custom filters as shown below.

Data matching all of the following conditions:

  • Shipping Country is not Canada
  • Customer Tags contains vip
  • Total is greater than 1000

Another example.

I want to create a report of only the orders shipping to US, Canada, or Mexico.

Data matching any of the following conditions:

  • Shipping Country Code is US
  • Shipping Country Code is CA
  • Shipping Country Code is MX

Here's the full list of conditions you can use:

  • is
  • is not
  • contains
  • not contains
  • starts with
  • ends with
  • is greater than
  • is less than

If you're filtering date fields, please see this article.

Custom Fields (Optional)

You can find the Custom Fields option in the Data Settings.

With Custom Fields, you can include additional columns in your report based on the value you specify. The value can be a simple static value or a combination of static values and those coming from other fields.

For example, you may want add to add a custom field called "Comments" and assign it a value "Please ship by 1/17."

To use a combination of static values with values derived from other fields, simply reference the field names enclosed by double curly braces ({{ field_name }}).

For example, you may want a custom field called "Alternate Product Title" with this value assigned:

{{ line_items.title }} (SKU: {{ line_items.sku }}) - Order {{ name }}

The above will result in something like this: Stretchy Blue Jeans (SKU: BLJE1234) - Order #1203

Another example, you may want a field called "Product Admin URL", you can do something like this:

https://mystore.myshopify.com/admin/products/{{ line_items.product_id }}

You can find the list of field names you can use in the Fields section at the bottom of the Data Settings page.

Calculated Fields (Optional)

You can find the Calculated Fields option in the Data Settings.

With Calculated Fields, you can create a column in your report with a dynamic value based on the formula you specify. The formula can be arithmetic operations, text operations, functions, or conditional expressions.

Arithmetic Operations

Arithmetic operations provide a way to generate new values from one or more number fields (e.g. total_weight, total_price, line_items.quantity, etc.).

Available Operators

  • + (add, 1 + 1 = 2)
  • - (subtract, 5 -1 = 4)
  • / (divide, 10 / 2 = 5)
  • * (multiply, 3 * 2 = 6)
  • ** (exponent, 2 ** 3 = 8)
  • % (modulus/remainder, 15 % 4 = 3)

Examples:

I want an additional column that will give me the order's total_weight in pounds as the default weight is in grams:
{{ total_weight }} * 0.0022046
I want an additional column showing the order's total_price with 40% off before taxes:
({{ total_price }} - {{ total_tax }}) * 0.60
Text Operations

Text operations let you manipulate text fields in your report.

Available Operators

  • +, Combines text (e.g. {{ text_field }} + "hello", {{ text_field1 }} + {{ text_field2 }}).
  • [], Slice part of the text (gives the character from a given index, e.g. if the value of a text_field is "hello", {{ text_field }}[1] will give "e", note that the index count starts at 0).
  • [:], Range slice (gives the characters from a given range, e.g. if the value of text_field is "hello", {{ text_field }}[1:4] will give "ell", note that the index count starts at 0 and the ending index is exclusive. You can also count backwards, for example {{ text_field }}[-3:] will give the last 3 characters "llo").
  • {{ text_field }}.replace("text_to_replace", "new_text"), Replace part of the text with new text.
  • {{ text_field }}.upper(), Converts the entire text to uppercase.
  • {{ text_field }}.lower(), Converts the entire text to lowercase.
  • str({{ number_field }}).replace(".", ","), Converts a number field into text/string so you can perform text operations on it.

Examples:

I want to remove parentheses and dashes in the shipping phone number:
{{ shipping_address.phone }}.replace("(", "").replace(")", "").replace("-", "")
I want a field of the product title all in capital letters:
{{ line_items.title }}.upper()
I want a field of just the first five letters of the SKU (note that the index starts at 0) and add the text "snipped" to it:
{{ line_items.sku }}[0:5] + "snipped"
Functions

md5_hash(data)

Returns the MD5 hash of the given data.

A sample output of an MD5 hash is ca57ba9132bd6da76c452f8f4abfa1fc.

Examples:

You may want to get the MD5 hash of your customer's email addresses to see their avatar (if they're using Gravatar).

md5_hash({{ email }})

Another potential use case is to get the MD5 hash of your product descriptions to quickly check if they're identical. Even a 1 character difference will give a completely different MD5 hash.

md5_hash({{ body_html }})

search_attributes(data, keyword, search_key="name", result_key="value", default="", return_all_results=False, results_separator=",")

Searches a list of attributes for a specific key and returns its value.

Examples:

You have the following Line Item Properties:

subcategory: "Birthday Rings"
engraving: "Jane Doe"
birthday_message: "Happy Birthday! Hope you like this gift.

In your report, you only want the "engraving" property to be included. With the search_attributes() function, you can use this formula:

search_attributes({{ line_items.properties }}, "engraving")

This will pull just the value of the "engraving" property and put that value in the column you specified. If the order doesn't have that property, it will simply be blank in the report. If you want the default value to be something else, you can do something like this:

search_attributes({{ line_items.properties }}, "engraving", default="N/A")

In this case, if the "engraving" property doesn't exist, the value in the exported CSV will be "N/A" instead.

The search_attributes() function can be used in other dynamic fields as well such as Note/Cart Attributes and Tax Lines. By default, the function specifically searches the "name" key and returns the content of the "value" key as returned by the Shopify API. We built the search_attributes() function with flexibility in mind so it can be used in other fields where the keys are different.

To give you an example, let's say multiple taxes are applied to your orders. In this case, you'd want to search the line_Items.tax_lines field, which could look something like this:

[
    {
        "title":"NY State Tax",
        "price":"4.00",
        "rate":0.04
    },
    {
        "title":"New York County Tax",
        "price":"4.87",
        "rate":0.04875
    }
]

In your report, you may want a column called "NY State Tax Price" and "NY County Tax Price". You can use the search_attributes() function this way:

"NY State Tax Price" column

search_attributes({{ line_items.tax_lines }}, "NY State Tax", search_key="title", result_key="price", default="N/A")

"NY County Tax Price" column

search_attributes({{ line_items.tax_lines }}, "New York County Tax", search_key="title", result_key="price", default="N/A")

strip_html_tags(data)

Remove the HTML tags from the data.

For example, if the data field looks something like this:

<p>Hello world!</p>

Using strip_html_tags({{ field_data }}) will result in:

Hello world

This is particularly useful when trying to get the product description without the HTML code:

strip_html_tags({{ body_html }})

format_datetime(datetime, format_str="%Y-%m-%d %H:%M:%S")

Formats a datetime value to a string. Please click here for a detailed explanation with examples.

to_datetime(datetime_strIng, dayfirst=False, yearfirst=False)

Convert a string to a datetime type which can be used for calculation with other dates.

For example, to convert the string "05/27/2017" (MM/DD/YYYY) to a datetime (the time is optional), you can use this formula:

to_datetime("05/27/2017")

If the format is in DD/MM/YYYY, set the dayfirst parameter to True.

to_datetime("05/08/2017", dayfirst=True)

days_diff(end_date, start_date)

Returns the number of days between two dates.

days_diff(to_datetime("09/28/2017"), to_datetime("09/25/2017"))

The above will return 3.

You can use this function with built-in fields as well.

days_diff(to_datetime({{ updated_at }}), to_datetime({{ created_at}}))

For differences in hours, minutes, or seconds, you can use:

  • hours_diff(end_date, start_date)
  • minutes_diff(end_date, start_date)
  • seconds_diff(end_date, start_date)

normalize_text(text)

This function will automatically convert special accented characters such as Á, Ç, and ô to their closest ASCII equivalent.

This is particularly useful if your supplier or dropshipper's systems do not support unicode/UTF-8 data.

For example, if the customer's name is Jôam Doê, you can use a formula like this:

normalize_text({{ shipping_address.name }})

In the exported CSV file, the text will be converted to Joam Doe (the special accented characters are replaced with Latin characters).

replace_text_with_html_entities(text, entity_type="mnemonic")

This function will search and replace special characters in your data with HTML entities.

For example, if you data contains Greek character, your supplier or dropshipper may ask you to have them converted because their systems don't support them. This is actually a use case one of our customers encountered.

HTML entities can be encoded in different ways, such as mnemonic or code points. By default the function will convert special characters in the text to mnemonic:

replace_text_with_html_entities("Γ")

The above formula will convert the gamma character to & Gamma;

To replace them using code points instead, simply specify code in the entity_type parameter:

replace_text_with_html_entities("Γ", entity_type="code")

The above formula will output & #915;

Conditional Expressions

Conditional expressions allow you to include logic when generating your report.

Available Operators

  • if ("this value" if "condition" else "", must be used with "else")
  • else ("this value" if "condition" else "this other value", must be used with "if")
  • not (if not "condition")
  • and (both conditions must be True, if "condition1" and "condition2", if 1 == 1 and 1==2 -> False)
  • or (either condition can be True, if "condition1" or "condition2", if 1 == 1 or 1 == 2 -> True)
  • > (greater than, if 3 > 1 -> True)
  • < (less than, if 1 < 3 -> True)
  • >= (greater than or equal to, if 3 >=3 -> True)
  • <= (less than or equal to, if 3 <= 3 -> True)
  • == (equals, if 5 == 5 -> True)
  • in (contains, if "shop" in "shopify" -> True)
  • {{ text_field }}.startswith() (text starts with characters, "hello".startswith("he") -> True)
  • {{ text_field }}.endswith() (text ends with characters, "hello".endswith("h") -> False)

Examples:

I want to categorize my orders based on total_price:
"High" if {{ total_price }} >= 1000 else "Medium" if {{ total_price }} >= 100 else "Low"

This will assign the value "High" if the order's total_price is greater than or equal to 1000, "Medium" between 100-1000, and "Low" if below 100.

I want an additional field for the destination's region:
"North America" if {{ shipping_address.country_code }} in "US, CA, MX" else "Other"

If the shipping address' country code is US, CA, or MX, assign the value "North America", otherwise, use "Other".

I want an additional field to set an order's priority based on price or weight:
"High" if {{ total_price }} > 500 or {{ total_weight }} > 1000 else "Normal"

If the order's total price is above 500 or if the total weight is over 1000, mark this order as high priority.

Metafields (Optional)

You can find the Metafields option in the Data Settings.

EZ Exporter Shopify App - Product MetafieldsThere may be cases where you'd want to include custom Order Metafields, Product Metafields, or Product Variant Metafields you've created in your report. For example, for some products you may have an Amazon ASIN metafield attached to them if you also sell your products on the Amazon Marketplace. You may have other metafields as well that you use for accounting such as Cost to Acquire and Additional Fees.

There are also some Shopify data that can only be retrieved via metafields. For example, the "HS Tariff Code" field in the product variants is stored in the Product Variant Metafield API using the key "harmonized_system_code".

With EZ Exporter, we've provided an option for you to include them. Simply specify the metafield key and the label to assign to that key (the label is basically the field/column name in the exported report).

Extra Options (Optional)

We provide additional options for further customization of your reports.

  • Create a duplicate row per line item quantity - Applies only to Order data. This option will repeat a row based on the quantity of each line item in the order. For example, if a customer orders 5 of a particular product/variant, instead of having one row for that product/variant with quantity of 5 in the report, this option will instead create 5 rows with quantity set to 1. Some systems may require the CSV file formatted this way when shipping items separately.