FTP and file exchanges
Overview
ZigZag offers integration via File Transfer Protocol (FTP). This is a standard protocol used to transmit flat files in CSV format (from you to the server over a network). We offer two types of FTP connection:
- FTP V1
- FTP V2
FTP v1 - Trackers
The FTP v1 version allows you to send us your order and tracking information at the same time (i.e. only when the tracking number is known).
This version is simpler to set up, but more restricted than v2.
FTP v2 - Orders
Version v2 introduces the concept of fulfillment (package preparation), which enables the following functions to be activated:
- Multi-packages
- Pre-shipment
- Store process
- Order and package contents
- Smart State "Order without tracker" (to detect package preparation delays)
Important information
- The file must be encoded in UTF-8 to be imported.
- carrier code + tracking number - It is important to fill these in together.If you do not yet know the tracking number, you do not need to enter the
carrier_code. Conversely, if you know the tracking number, thecarrier_codeis mandatory. - v1 vs v2 - Files are uploaded to the upload folder in the case of FTP v1 and uploadV2 in the case of FTP v2.
- Languages - You can enter the languages to be used according to this nomenclature (in lower case), otherwise we will use the language of the recipient's country.
- Avoid double quotes (“”) - Double quotes (“…”) can be present in a CSV file, but you must ensure when uploading the files that there are no double quotes in the fields.
- File update frequency - We syncs information every hour. We recommend that you upload your file several times a day.
- Manual synchronisation - You can manually sync the file import by navigating to Portal Settings -> Notification Settings -> Integrations -> Click the 3 dots next to FTP -> Manual Sync.
Required fields
Below, you will find the fields you need to set up for your CSV files.
Fields required for v1
| Value | Description | Mandatory or Optional |
|---|---|---|
| carrier_code | Use our glossary of carrier code nomenclature to identify the carrier in charge of the package. | Mandatory |
| carrier_service_code | Fill in the carrier service codes for more granularity in the expected delivery dates (mandatory for the SDE functionality). Nomenclature should follow our technical documentation. | Optional (but strongly recommended) |
| tracking_number | Package tracking number (must be an official reference used by the carrier). | Mandatory |
| Customer email address. | Optional (but strongly recommended) | |
| order_number | The reference of the order. | Mandatory |
| order_date | Order creation date. | Optional (but strongly recommended) |
| first_name | Customer first name. | Optional (but strongly recommended) |
| last_name | Customer last name. | Optional (but strongly recommended) |
| address_name | Address name of the customer. | Optional (but strongly recommended) |
| address_street | Customer street address. | Optional (but strongly recommended) |
| address_city | Customer city. | Optional (but strongly recommended) |
| address_zip | Customer postal code. | Optional (but strongly recommended) |
| address_country | Use the international nomenclature (uppercase). Example for France => FR. | Optional (but strongly recommended) |
| language_code | The language to use for the notifications (in lowercase). Please refer to our technical documentation. | Optional (but strongly recommended) |
| phone | The customer's phone number. International format: +33 or 0033. National format: ZigZag will add the international prefix based on the delivery address. | Optional |
| warehouse_merchant_id | Warehouse reference number in case of multiple warehouses (relevant for the implementation of the SDE feature). | Optional |
| store_id | ZigZag account reference (in case of multiple accounts). | Optional |
| order.custom_variable | Custom Liquid variables for a highly personalised customer experience (notification wording, tracking page content, etc.). | Optional |
Fields required for v2
| Value | Description | Mandatory or Optional |
|---|---|---|
| order.merchant_id | Reference that guarantees the uniqueness of the order. When order numbers are unique, you can easily reference them. | Mandatory |
| ordered_at | Order date. | Optional (but strongly recommended) |
| order.order_number | Order number. | Mandatory |
| order.email | Customer email address. | Optional (but strongly recommended) |
| order.first_name | Customer first name. | Optional (but strongly recommended) |
| order.last_name | Customer last name. | Optional (but strongly recommended) |
| order.language_code | The language to use for the notifications (in lowercase). Please refer to our technical documentation. | Optional (but strongly recommended) |
| fulfillment.merchant_id | Unique package reference. | Mandatory |
| fulfillment.fulfillment_number | Package number. | Mandatory |
| fulfillment.status_code | Pre-shipment status (used for pre-shipment notifications). Please refer to our technical documentation. | Optional |
| shipping_address.address1 | Shipping address of the package. | Optional (but strongly recommended) |
| shipping_address.city | Shipping city of the package. | Optional (but strongly recommended) |
| shipping_address.country | Recipient country. | Optional (but strongly recommended) |
| shipping_address.country_code | Use the international nomenclature (uppercase). Example for France => FR. | Optional (but strongly recommended) |
| shipping_address.first_name | Recipient first name. | Optional (but strongly recommended) |
| shipping_address.last_name | Recipient last name. | Optional (but strongly recommended) |
| shipping_address.zip | ZIP code of the shipping address. | Optional (but strongly recommended) |
| line_item.merchant_id | Unique reference of the item. | Optional (but strongly recommended) |
| line_item.title | Name of the item. | Optional (but strongly recommended) |
| line_item.sku | SKU number. | Optional |
| line_item.quantity | Quantity of the item. | Mandatory |
| line_item.thumbnail.src | Item image URL. | Mandatory |
| tracker.carrier_code | Carrier code. Please refer to our technical documentation. | Mandatory |
| tracker.carrier_service_code | Carrier service codes for more granularity in estimated delivery dates (mandatory for SDE). Nomenclature must follow our technical documentation. | Optional |
| tracker.tracking_number | Package tracking number (must be an official reference used by the carrier). | Mandatory |
| fulfillment.warehouse_merchant_id | Warehouse reference in case of multiple warehouses (required for SDE). | Optional |
| order.store_id | Shipup account reference (in case of multiple accounts). | Optional |
| order.custom_variables | Custom Liquid variables for a highly personalized customer experience (notifications, tracking page content, etc.). Please refer to our technical documentation on formatting custom variables. | Optional |
How to set up an FTP Connection
- Contact your Account Manager or the Support Team to request access to the FTP server.
- We will send you your login credentials as soon as they are ready.
- Prepare the CSV file, ensuring all required fields are completed correctly.
- Submit the file to your ZigZag contact for review and validation.
- After validation, a test import will be performed to ensure that packages are tracked properly on ZigZag.
- Once confirmed, you can automate file uploads to the server (it is recommended to schedule synchronisation several times per day).