--- updatedAt: 2025-11-11T23:05:20.000Z agentTools: projectIndex: https://developers.shipup.co/llms.txt --- # 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
format info description
**Filename** "[UNIX timestamp].csv" The filename must be the [Unix Time](https://en.wikipedia.org/wiki/Unix_time) at which the file has been generated followed by file format .csv
**Separator** Comma , and semi-comma ; are allowed but must be consistent throughout one file
**Headers** The first line of the CSV must be a comma / semi-comma separated list of attribute names.
**Data** Each following row must be a comma / semi-comma separated list of values.
**Encoding** UTF-8
## 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**](https://developers.shipup.co/reference/create-or-update-an-order): 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](https://developers.shipup.co/reference/carrier-services-codes). 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](https://en.wikipedia.org/wiki/Unix_time) (seconds since 1970). For convenience, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format is also considered valid (e.g. 2019-08-12T09:17:29Z). ## Validation rules Based on the data you send, some fields are **mandatory**. These fields serve as identifiers and cannot be inferred on our side, as this could create inconsistencies between Shipup and your system. ### Mandatory Field Rules You must include the following identification fields depending on which group of fields you send: * **Order fields:**\ If you include any `order` field (e.g. `order.order_number`, `order.language_code`, etc.), you must also include `order.merchant_id`. * **Fulfillment fields:**\ If you include any `fulfillment` field (e.g. `fulfillment.fulfillment_number`, `fulfillment.status_code`, etc.), you must also include `fulfillment.merchant_id`. * **Tracker fields:**\ If you include any `tracker` field (e.g. `tracker.carrier_code`, `tracker.carrier_service_code`, etc.), you must also include `tracker.tracking_number`. * **Line item fields:**\ If you include any `line_item` field (e.g. `line_item.quantity`, `line_item.title`, etc.), you must also include `line_item.merchant_id`. ### Logical Dependencies The following logical relationships between fields must also be respected: * If `tracker.tracking_number` is present → `fulfillment.merchant_id` must be present. * If `fulfillment.merchant_id` is present → `order.merchant_id` must be present. * If `line_item.merchant_id` is present → both `order.merchant_id` and `fulfillment.merchant_id` must be present. > ⚠ Important > > If any of these rules are not followed, the corresponding line in your CSV **will not be imported.** ## 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:** ```text 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 }" ```text 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](https://csvlint.io/) **Here is a correct example:** ```text 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,jane@gmail.com,+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,jane@gmail.com,+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): ```text 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,jane@gmail.com,+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,jane@gmail.com,+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 ```text 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,jane@gmail.com,+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,jane@gmail.com,+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 ``` {` `}