Send orders and trackers

Overview

You can set up an FTP server and drop on a regular basis CSV exports of your most recently sent orders. Shipup will try to access the FTP every hour and will retrieve all exports generated in the last hour.

Alternatively, we can also provide access to our SFTP server (sftpgo.shipup.co) so you don't need to set up your own.

Format

Data format

Shipup is expecting CSV files encoded with UTF-8.

You'll find at the bottom of this page an example of a CSV file with all available data fields. For a description of those fields with their format and sample values, please refer to our create or update an order API reference: The first payload table refers to order attributes (e.g. order_number becomes order.order_number in your CSV headers) and following tables refer to other resources (e.g. tracking_number field of the tracker payload becomes tracker.tracking_number in your CSV headers).

📘

Importance of carrier_code

When you import tracker data into Shipup using our order FTP integration, it's important to include the tracker.carrier_code field. You can find available values for this field here. If you fail to do so, Shipup will try to guess the carrier based on the tracking number but this process is prone to error.

Datetime format

Datetime fields are expected to be sent using UNIX timestamps (seconds since 1970).

For convenience, ISO 8601 format is also considered valid (e.g. 2019-08-12T09:17:29Z).

Custom variable format

If you wish to pass custom variables in your CSV, you can use the custom_variables field. This field is available for orders, fulfillments, trackers and line_items. There are 2 possibilities to pass this field:

1/ Using the xxx.custom_variables.yyy header (recommended)
The expected format is to use yyy as the key of your custom variables and the pass the value in the associated column.

Example:

order.merchant_id,order.order_number,order.custom_variables.order_type,order.custom_variables.is_guest
ODR1234,YDGE56TYY,web,true
ODR1234,YDGE56TYY,store,false

2/ Using the xxx.custom_variables header
The expected format is a stringified JSON string containing all your custom variables. Please note that you'll need to comply with the specific escaping format of the CSV file.

Example:

1. Given a JSON stringified custom_variables dictionary:
   { "order_type": "web", "is_guest": true }

2. Escape all double quotes by doubling them (CSV standard):
   { ""order_type"": ""web"", ""is_guest"": true }

3. Add double quotes around the final string and add it to your CSV:
   "{ ""order_type"": ""web"", ""is_guest"": true }"

order.merchant_id,order.order_number,order.custom_variables
ODR1234,YDGE56TYY,"{""order_type"":""web"",""is_guest"":true}"
ODR1234,YDGE56TYY,"{""order_type"":""store"",""is_guest"":false}"

Escaping double quotes

The " (double-quote) character can be present in a CSV but must be escaped with another ". Please verify that your CSV is valid using a CSV validator, for example csvlint.io

Here is a correct example:

order.merchant_id,order.order_number,order.email,order.phone,shipping_address.address1,order.first_name,order.last_name,fulfillment.merchant_id,fulfillment.fulfillment_number,fulfillment.status_code,shipping_address.city,shipping_address.country,shipping_address.country_code,shipping_address.first_name,shipping_address.last_name,shipping_address.zip,line_item.merchant_id,line_item.title,line_item.sku,line_item.quantity,tracker.carrier_code,tracker.carrier_service_code,tracker.tracking_number,fulfillment.warehouse_merchant_id
ODR1234,YDGE56TYY,[email protected],+33612345678,"12, rue de Cl√©ry lieu dit ""laville""",Jane,Doe,ODR1234_1,YDGE56TYY_1,shipped,Paris,France,FR,Jane,Doe,75002,12355432,Amazing picture,HJY333452,1,ups,ups_standard_delivery,1Z548V626898567913,location_1
ODR1234,YDGE56TYY,[email protected],+33612345678,"12, rue de Cl√©ry lieu dit ""laville""",Jane,Doe,ODR1234_1,YDGE56TYY_1,shipped,Paris,France,FR,Jane,Doe,75002,55636421,Painting color blue,JUH78899777,3,ups,ups_standard_delivery,1Z548V626898567913,location_2

Here are incorrect examples (wrong double-quote encoding on each line):

order.merchant_id,order.order_number,order.email,shipping_address.address1,order.first_name,order.last_name,fulfillment.merchant_id,fulfillment.fulfillment_number,fulfillment.status_code,shipping_address.city,shipping_address.country,shipping_address.country_code,shipping_address.first_name,shipping_address.last_name,shipping_address.zip,line_item.merchant_id,line_item.title,line_item.sku,line_item.quantity,tracker.carrier_code,tracker.carrier_service_code,tracker.tracking_number,fulfillment.warehouse_merchant_id
ODR1234,YDGE56TYY,[email protected],+33612345678,"12, rue de Cléry lieu dit "laville"",Jane,Doe,ODR1234_1,YDGE56TYY_1,shipped,Paris,France,FR,Jane,Doe,75002,12355432,Amazing picture,HJY333452,1,ups,ups_standard_delivery,1Z548V626898567913,location_1
ODR1234,YDGE56TYY,[email protected],+33612345678,"12, rue de Cléry lieu dit \"laville\"",Jane,Doe,ODR1234_1,YDGE56TYY_1,shipped,Paris,France,FR,Jane,Doe,75002,55636421,Painting color blue,JUH78899777,3,ups,ups_standard_delivery,1Z548V626898567913,location_2

Multiple delivery experiences across multiple Shipup accounts using one FTP integration

If you wish to use a unique CSV file for all your Shipup accounts, you can add a column order.store_id. This column must be filled up with a unique identifier for your different stores. Shipup can then filter orders to only import corresponding stores into associated accounts.

For example, if you have two brands (My Dog and My Cat) with two different branding experiences, you will need two Shipup accounts, one for each brand.

Nevertheless, you can have only one FTP integration, and fill up the column order.store_id with mydog and mycat depending on the brand. Shipup will then be able to import orders with order.store_id mydog in My Dog Shipup account, and orders with order.store_id mycat in My Cat Shipup account

Example of file

Filename: 1477299100.csv

order.merchant_id,order.order_number,order.email,order.phone,order.first_name,order.last_name,order.language_code,fulfillment.merchant_id,fulfillment.fulfillment_number,fulfillment.status_code,shipping_address.address1,shipping_address.city,shipping_address.country,shipping_address.country_code,shipping_address.first_name,shipping_address.last_name,shipping_address.zip,line_item.merchant_id,line_item.title,line_item.sku,line_item.quantity,tracker.carrier_code,tracker.carrier_service_code,tracker.tracking_number,fulfillment.warehouse_merchant_id
ODR1234,YDGE56TYY,[email protected],+33612345678,Jane,Doe,fr,ODR1234_1,YDGE56TYY_1,shipped,"12, rue de Cléry",Paris,France,FR,Jane,Doe,75002,12355432,Amazing picture,HJY333452,1,ups,ups_standard_delivery,1Z548V626898567913,location_1
ODR1234,YDGE56TYY,[email protected],+33612345678,Jane,Doe,fr,ODR1234_1,YDGE56TYY_1,shipped,"12, rue de Cléry",Paris,France,FR,Jane,Doe,75002,55636421,Painting color blue,JUH78899777,3,ups,ups_standard_delivery,1Z548V626898567913,location_2