> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Formats

ShipStream supports importing [orders](/merchant-api/order#ordercreate), [products](/merchant-api/product#product-create), [deliveries](/merchant-api/delivery#delivery-create) and [BOMs](/merchant-api/bom) either via the Merchant Panel or the [Import](/merchant-api/import) API.

The file formats supported are:

* CSV (delimiters are auto-detected)
* Excel (table format the same as Standard CSV)
* JSON Lines (single-line or multi-line JSON objects delimited by newlines)

The file data may be compressed with GZip or BZip2 compression.

The import formats all conform to the respective API '\*.create' methods so please see the documentation for those methods for details about supported field names and values.

## Order - Standard CSV

The header row defines which columns are used and each following line should consist of the order data, SKU and quantity for one order item. If the order contains multiple items they can be specified using additional rows and the order data can be either repeated (it will be ignored) or omitted as long as the 'order\_ref' column is not omitted since it is used to group the order items together.

**See [Order Properties](/merchant-api/order#order-properties) for the supported field names and values.**

<Note>
  To group multi-product orders together for CSV imports either the `unique_id` or the `order_ref` must be supplied unless there is only one order per file. When the `unique_id` is supplied with no `order_ref` then the `unique_id` will be used to group rows. When the `order_ref` is supplied with no `unique_id` then the `order_ref` will be used to group rows. If both `unique_id` and `order_ref` are supplied then the `unique_id` will be used to group rows.
</Note>

<Note>
  Order Custom Fields can be used in Order Imports. To add an Order Custom Field, add the field's code to the header with a prefix symbol.

  There are two types of prefixes:

  * Prefix with `#` when the values are identified by "id". See [Enumerated Order Custom Field Options](https://help.shipstream.io/article/0hv4sjkn3d-custom-fields-for-orders#enumerated-order-custom-field-options) article section for how to find the "id".
  * Prefix with `@` when the values uploaded are numeric values or text.

  Here's an example of how to use these prefixes:

  ```
  "@claim_reasons","@cost_of_goods","@allow_mailer","#claim-reason"
  "Damaged in shipping|Did not fit",41.32,true,13
  ```
</Note>

<Note>
  For fields that allow multiple values, separate each value with the pipe character `|`.
</Note>

```csv title="order_import_sample.csv" theme={null}
order_ref,shipping_method,firstname,lastname,company,street1,city,region,postcode,country,telephone,sku,qty,@claim_reasons,@cost_of_goods,@allow_mailer,#claim-reason
123456,ups_01,Bill,Gates,Microsoft,11 Times Square,New York,NY,10036,US,212.245.2100,product1,5,Damaged in shipping|Did not fit,41.32,true,13
123456,,,,,,,,,,,product2,1,,,,
123456,,,,,,,,,,,product3,2,,,,
```

## Order - Standard JSON

Importing orders in JSON format should follow the [order.create](/merchant-api/order#ordercreate) inputs exactly.

```json title="order_import_sample.json" theme={null}
{ 
  "order_ref" : "123456", 
  "shipping_method" : "ups_01", 
  "firstname" : "Bill",
  "lastname" : "Gates",
  "company" : "Microsoft", 
  "street1" : "11 Times Square", 
  "city" : "New York", 
  "region" : "NY", 
  "postcode" : "10036", 
  "country" : "US", 
  "telephone" : "212.245.2100", 
  "items" : { 
    "product1" : 2, 
    "product2" : 3, 
    "product3" : 1
  },
  "custom_fields" : {
    "claim_reasons" : ["Damaged in shipping", "Did not fit"],
    "cost_of_goods" : "41.32",
    "allow_mailer" : "true",
    "claim_reason" : {"id" : 13}
  }
}
```

## Product - Standard CSV

The header row should contain all field names and each following row contains product data. Each row must specify a SKU at minimum.

**See [Product Properties](/merchant-api/product#product-properties) for the supported field names and values.**

If a field supports multiple values such as 'hts\_country\_code' or 'special\_other' then multiple values can be assigned by specifying values separated by the 'pipe' character: |

```csv title="product_import_sample.csv" theme={null}
sku,name,barcode,goods_type,weight,weight_unit,length,width,height,dimension_unit,country_of_manufacture,hts_base_code,hts_country_code,requires_packaging,can_contain_other_items,allowed_container_styles,valid_containers,disallowed_containers,special_supplies,special_other,unit_qty,backorders,dynamic_allocation,virtual_inventory
"productsku","Product Name","productbarcode","NORMAL","1.75","lb","123","100","28","in","DK","1234.56","BH:1000|ZW:1001",1,0,"rigid_box|pallet","containerssku1|containerssku2","containerssku3|containerssku4","suppliessku1|suppliessku2","othersku1|othersku2",5,1,2,"optimistic"
```

## Product - Standard JSON

Importing products in JSON format should follow the [product.create](/merchant-api/product#product-create) inputs exactly.

```json title="product_import_sample.json" theme={null}
{
  "name" : "Product 3",
  "sku" : "product-3",
  "barcode" : "product3",
  "goods_type" : "NORMAL",
  "weight" : 1.75,
  "weight_unit" : "lb",
  "length" : 123,
  "width" : 100,
  "height" : 28,
  "dimension_unit" : "in",
  "country_of_manufacture" : "DK",
  "hts_base_code" : 1234.56,
  "hts_country_code" : "BH:1000|ZW:1001",
  "requires_packaging" : 1,
  "can_contain_other_items" : 0,
  "allowed_container_styles" : [ "rigid_box", "bubble_mailer" ],
  "valid_containers" : [ "containersku1", "containersku2" ],
  "disallowed_containers" : [ "containersku3", "containersku4" ],
  "special_supplies" : [ "supplysku1", "supplysku2" ],
  "special_other" : [ "othersku1", "othersku2" ],
  "unit_qty" : 5,
  "additional_regulatory_info" : "EX1995120111C",
  "meets_hazmat_specs" : 1,
  "backorders" : 1,
  "dynamic_allocation" : 2,
  "virtual_inventory" : "optimistic"
}  
```

## Delivery - Standard CSV

The "id" field is only used to group multiple lines into a single delivery. If importing a single delivery it can be blank, but if importing multiple deliveries it should be unique for each separate delivery in the CSV file.

When using Delivery Imports the `merchant_ref` values must be unique to the `delivery_type` specified. i.e.: Merchant Ref supplied to three new ASNs should not match former ASNs already in the system, nor the ASNs within the upload file.

Since an import can create multiple items at once the System uses the Merchant Ref to check for duplicates. Example: Upload a file with 10 different ASNs. After importing, the System states that of the ten, five had errors and five successfully imported. Correct those five, whether that is in the file or by adding a SKU to the System, etc. With the corrections made, import the same file but have the System handle duplicates by Dropping them. This way the same file can be reused without accidentally entering a duplicate ASN. Allowing the focus to be on fixing the ASNs that failed instead of needing to also make a new file to import the ASNs.

**See [Delivery Properties](/merchant-api/delivery#delivery-properties) for the supported field names and values.**

```csv title="delivery_import_sample.csv" theme={null}
id,delivery_type,sender_name,carrier_name,expected_delivery,merchant_ref,sender_ref,sku,qty
1,asn,Bill Gates,FedEx,"2014-07-31",12345,333,product1,50
1,,,,,,,product2,100
2,asn,Bill Gates,FedEx,"2014-08-12",12346,339,product3,40
2,,,,,,,product4,200
```

## Delivery - Standard JSON

Importing deliveries in JSON format should follow the [delivery.create](/merchant-api/delivery#delivery-create) inputs exactly.

```json title="delivery_import_sample.json" theme={null}
{ 
  "delivery_type" : "asn", 
  "sender_name" : "Bill Gates", 
  "carrier_name" : "FedEx", 
  "expected_delivery" : "2014-07-31", 
  "merchant_ref" : "12345", 
  "sender_ref" : "333", 
  "items" : [ 
    { 
      "sku" : "product1", 
      "qty" : 5
    }, 
    { 
      "sku" : "product2", 
      "qty" : 1 
    } 
  ] 
}
```

## Bill of Materials - Standard CSV

The "id" field is only used to group multiple lines into a single bill of materials. If importing a single bill of materials it can be blank, but if importing multiple bills of materials it should be unique for each separate bill of materials in the CSV file.

The header row should contain all field names and each following row contains bill of materials data. Each row must specify a SKU at minimum.

**See [BOM Properties](/merchant-api/bom#bom-properties) for the supported field names and values.**

```csv title="bom_import_sample.csv" theme={null}
id,name,sku,yield_qty,is_kit_on_demand,is_kit_to_stock,assembly_instructions,priority,component_sku,component_qty
1,BOM 1,bom1,1,Yes,No,,0,component1,1
1,BOM 1,bom1,1,Yes,No,,0,component2,1
```

## Bill of Materials - Standard JSON

Importing bill of materials in JSON format should follow the [bom.create](/merchant-api/bom#bom-create) inputs exactly.

```json title="bom_import_sample.json" theme={null}
{
  "id": "1",
  "sku": "bom1",
  "name": "BOM 1",
  "yield_qty": "1",
  "is_kit_on_demand": true,
  "is_kit_to_stock": false,
  "priority": "0",
  "components": [
    {
      "sku": "component1",
      "qty": "1"
    },
    {
      "sku": "component2",
      "qty": "1"
    }
  ]
}  
```