Import Formats

ShipStream supports importing orders, products and deliveries either via the Merchant Panel or the Import API. Standard CSV and JSON filters are provided which format the data to use the same values as the respective API ‘*.create’ methods so please see the documentation for those methods for details about supported field names and values.

If you would like to create a custom import format please contact us for help and see the Create custom import format section for more information.

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.

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:
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 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:
For fields that allow multiple values, separate each value with the pipe character |.

Example Input File [Download Sample]

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’ inputs exactly.

Example Input File [Download Sample]

{ 
  "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}
  }
}

Important! JSON for each order must be a single line. Multi-line JSON is not allowed.

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.

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:

Example Input File [Download Sample]

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,confirmation_per_item,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,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’ inputs exactly.

Example Input File [Download Sample]

{
  "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,
  "confirmation_per_item" : 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"
}

Important! JSON for each product must be a single line. Multi-line JSON is not allowed.

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.

There are other possible column headers that can be found at Delivery Properties. Some of these can be used, some are only for values returned by the API.

Example Input File [Download Sample]

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’ inputs exactly.

Example Input File [Download Sample]

{ 
  "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 
    } 
  ] 
}

Important! JSON for each delivery must be a single line. Multi-line JSON is not allowed.

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.

Example Input File [Download Sample]

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’ inputs exactly.

Example Input File [Download Sample]

{
  "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"
    }
  ]
}

Important! JSON for each bill of materials must be a single line. Multi-line JSON is not allowed.

Create custom import format

Logstash uses input {…}, filter {…} and output {…} configuration. “input” and “output” configuration is already defined and only the “filter” part of the configuration can be specified by the user.

The “input” uses stdin and adds “line_number” to each line of the import files. The “output” is different for each import type. A custom import format should get data after “input”, make required modifications and prepare the data for the “output” format corresponding to the import type.

input

input {
  stdin { type => "stdin-type" }
}

filter {
  ruby {
    code => '
      if !$LINE
        $LINE = 0;
      end;
      $LINE += 1; event["line_number"] = $LINE;'
  }
}

filter for JSON format

filter {
  json {
    source => "message"
  }
  ruby {
    code => 'event["raw_data"] = event["message"]'
  }
}

output for Order

filter {
  ruby {
    code => 'event["parsed_data"] = {
      "api_method" => "order.create",
      "args" => {
        "items" => event["items"],
        "address" => {
          "firstname"=> event["firstname"],
          "lastname" => event["lastname"],
          "company"  => event["company"],
          "street1"  => event["street1"],
          "city"     => event["city"],
          "region"   => event["region"],
          "postcode" => event["postcode"],
          "country"  => event["country"],
          "telephone"    => event["telephone"]
        },
        "info" => {
          "unique_id"           => event["unique_id"],
          "order_ref"           => event["order_ref"],
          "shipping_method"     => event["shipping_method"],
          "custom_greeting"     => event["custom_greeting"],
          "note"                => event["note"],
          "signature_required"  => event["signature_required"],
          "overbox"             => event["overbox"],
          "requested_ship_date" => event["requested_ship_date"],
          "delayed_ship_date"   => event["delayed_ship_date"]
        }
      }
    }'
  }
}

output for Product

filter {
  ruby {
    code => 'event["parsed_data"] = {
      "api_method" => "product.create",
      "args" => {
        "sku" => event["sku"],
        "product_data" => {
          "name"           => event["name"],
          "barcode"        => event["barcode"],
          "goods_type"     => event["goods_type"],
          "weight"         => event["weight"],
          "weight_unit"    => event["weight_unit"],
          "length"         => event["length"],
          "width"          => event["width"],
          "height"         => event["height"],
          "dimension_unit" => event["dimension_unit"],
        }
      }
    }'
  }
}

output for Delivery

filter {
  ruby {
    code => 'event["parsed_data"] = {
      "api_method" => "delivery.create",
      "args" => {
        "delivery_type" => event["delivery_type"],
        "data" => {
          "sender_name"       => event["sender_name"],
          "carrier_name"      => event["carrier_name"],
          "expected_delivery" => event["expected_delivery"],
          "delivery_type"     => event["delivery_type"],
          "merchant_ref"      => event["merchant_ref"],
          "sender_ref"        => event["sender_ref"]
        },
        "items" => event["items"]
      }
    }'
  }
}