DSFX - File Format Specifications

DSFX files are formatted as CSV (comma separated values).

There are three file types,

  • Order files — containing the header and line-level data of orders to be fulfilled. These are generated by PackageBee, and sent to the SFTP server /in folder to be picked up and processed by the fulfillment center.
  • Shipment files — containing data about shipped packages, for notification to the sales channel. These are generated by the fulfillment center, to be dropped in the SFTP server /out folder and picked up by PackageBee.
  • Inventory files — containing available quantity levels to be synced to the sales channel. These are generated by the fulfillment center, to be dropped in the SFTP server /out folder and picked up by PackageBee.

Order files

After order data has been imported from the sales channel and successfully processed, Order files are generated by PackageBee and uploaded to the /in directory of the configured SFTP server.

The file name format is ord_ORDERID_YYMMDDHHMMSS.csv, where ORDERID is the ID of the first order in the file, and YYMMDDHHMMSS is the date-time the file was generated.

The first line of an order file is a Pick Header (PH) row, containing the order-level header data of one order. This is followed by Pick Detail (PD) rows, one per order line.

An order file may contain multiple orders, each with its own PH and PD rows.

Order Pick Header (PH) rows

The Pick Header row contains the order-level data: Order Name, Bill-to Name, Ship-to name, etc.

There are three versions of Pick Header, each with slight differences in the available data fields, listed below. The version is selected in the Warehouse settings. Version 2 is the default.

Pick Header schema (Version 1)

Version 1 Pick Headers have the following fields.

Pos Name Desc Example
1 Record type ("PH") Identifies this as the Pick Header row "PH"
2 Order number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
3 Customer PO number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
4 Ship to name Ship-to name "Jane Smith"
5 Ship to address1 Ship-to address line 1 "123 Main St"
6 Ship to address2 Ship-to address line 2 "Apt 1"
7 Ship to city Ship-to city name "Springfield"
8 Ship to state Ship-to state abbreviation, e.g. "CA" for California "IL"
9 Ship to postal code Ship-to postal code "62629"
10 Ship to country Ship-to country ISO code, e.g. "US" for United States "US"
11 Ship to attention

Ship-to attention

"Attn: Jane Smith"
12 Ship to telephone Ship-to telephone number "(123) 456-7890"
13 Bill to name Bill-to name "John Doe"
14 Bill to address1 Bill-to address line 1 "234 Spring St"
15 Bill to address2 Bill-to address line 2 "Apt. 4"
16 Bill to city Bill-to city name "Chicago"
17 Bill to state Bill-to state abbreviation, e.g. "CA" for California "IL"
18 Bill to postal code Bill-to postal code "60007"
19 Bill to country Bill-to country ISO code, e.g. "US" for United States "US"
20 Ship method Warehouse carrier/service code "UPSG"
21 Ship payment type Shipping payment type / third-party Bill-to code.
Common payment type codes:
"P" - Prepaid (the default if none specified)
"C" - Collect/Consignee
"R" - Bill Recipient
"T" - Third Party
"P"
22 Ship payment account number Carrier account number, if applicable "ACC1234"
23 Order date Ordered-at date in UTC, ISO 8601 format "2024-04-17T15:00:01Z"
24 Order source Order source identifier, if provided "Amazon"
25 Gift message Gift message, if provided

"Happy Birthday"

Pick header schema (Version 2)

In addition to the fields in version 1, version 2 inserts a Customer email field at column 4, and adds a Customer notes field at column 27.

Pos Name Desc Example
1 Record type ("PH") Identifies this as the Pick Header row "PH"
2 Order number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
3 Customer PO number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
4 Customer email Bill-to email address "john.doe@example.org"
5 Ship to name Ship-to name "Jane Smith"
6 Ship to address1 Ship-to address line 1 "123 Main St"
7 Ship to address2 Ship-to address line 2 "Apt 1"
8 Ship to city Ship-to city name "Springfield"
9 Ship to state Ship-to state abbreviation, e.g. "CA" for California "IL"
10 Ship to postal code Ship-to postal code "62629"
11 Ship to country Ship-to country ISO code, e.g. "US" for United States "US"
12 Ship to attention

Ship-to attention

"Attn: Jane Smith"
13 Ship to telephone Ship-to telephone number "(123) 456-7890"
14 Bill to name Bill-to name "John Doe"
15 Bill to address1 Bill-to address line 1 "234 Spring St"
16 Bill to address2 Bill-to address line 2 "Apt. 4"
17 Bill to city Bill-to city name "Chicago"
18 Bill to state Bill-to state abbreviation, e.g. "CA" for California "IL"
19 Bill to postal code Bill-to postal code "60007"
20 Bill to country Bill-to country ISO code, e.g. "US" for United States "US"
21 Ship method Warehouse carrier/service code "UPSG"
22 Ship payment type Shipping payment type / third-party Bill-to code.
Common payment type codes:
"P" - Prepaid (the default if none specified)
"C" - Collect/Consignee
"R" - Bill Recipient
"T" - Third Party
"P"
23 Ship payment account number Carrier account number, if applicable "ACC1234"
24 Order date Ordered-at date in UTC, ISO 8601 format "2024-04-17T15:00:01Z"
25 Order source Order source identifier, if provided "Amazon"
26 Gift message Gift message, if provided

"Happy Birthday"

27 Customer notes Order notes from the customer

"Please leave package on doormat"

Pick header schema (Version 3)

Version 3 adds a Facility field at column 28, but is otherwise compatible with version 2.

Pos Name Desc Example
1 Record type ("PH") Identifies this as the Pick Header row "PH"
2 Order number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
3 Customer PO number String of Letters, Numbers, Dashes, Underscores. No spaces or tildes (~) "ABC-123"
4 Customer email Bill-to email address "john.doe@example.org"
5 Ship to name Ship-to name "Jane Smith"
6 Ship to address1 Ship-to address line 1 "123 Main St"
7 Ship to address2 Ship-to address line 2 "Apt 1"
8 Ship to city Ship-to city name "Springfield"
9 Ship to state Ship-to state abbreviation, e.g. "CA" for California "IL"
10 Ship to postal code Ship-to postal code "62629"
11 Ship to country Ship-to country ISO code, e.g. "US" for United States "US"
12 Ship to attention

Ship-to attention

"Attn: Jane Smith"
13 Ship to telephone Ship-to telephone number "(123) 456-7890"
14 Bill to name Bill-to name "John Doe"
15 Bill to address1 Bill-to address line 1 "234 Spring St"
16 Bill to address2 Bill-to address line 2 "Apt. 4"
17 Bill to city Bill-to city name "Chicago"
18 Bill to state Bill-to state abbreviation, e.g. "CA" for California "IL"
19 Bill to postal code Bill-to postal code "60007"
20 Bill to country Bill-to country ISO code, e.g. "US" for United States "US"
21 Ship method Warehouse carrier/service code "UPSG"
22 Ship payment type Shipping payment type / third-party Bill-to code.
Common payment type codes:
"P" - Prepaid (the default if none specified)
"C" - Collect/Consignee
"R" - Bill Recipient
"T" - Third Party
"P"
23 Ship payment account number Carrier account number, if applicable "ACC1234"
24 Order date Ordered-at date in UTC, ISO 8601 format "2024-04-17T15:00:01Z"
25 Order source Order source identifier, if provided "Amazon"
26 Gift message Gift message, if provided

"Happy Birthday"

27 Customer notes Order notes from the customer

"Please leave package on doormat"

28 Facility Facility/Warehouse ID for fulfillment, if provided

"CHICAGO-WH-5"

Pick Detail row schema

Each Pick Detail row represents a single line on the order. Its schema is the same, regardless of pick header version:

Pos Name Desc Example
1 Record type ("PD") Identifies this as the Pick Detail row "PD"
2 Order number Must match the order number in the corresponding pick header row. "ABC-123"
3 Line number Sequential line number, beginning with 1. "1"
4 Product code Order line SKU "PRODUCT-123"
5 Quantity ordered Order line quantity "3"
6 Unit price Order line unit price "12.34"

Shipment files

Shipment files are CSV files generated by the fulfillment center and dropped in the SFTP server /out folder to be picked up by PackageBee. File name must begin shp_ and end in lowercase file extension .csv. Recommended file name format is shp_YYMMDDHHMMSS.csv, where YYMMDDHHMMSS represents the date-time the file was generated.

The first line of a Shipment file is a required header row identifying the shipment line columns:

"ClientOrderNumber","DateTimeShipped","ProductCode","QtyShipped","TrackingNumber","ShipMethod"

This is followed by one ship detail row per line shipped. Each detail row includes the tracking number of its package (there is no separate "package header" row).

Pos Name Desc Example
1 ClientOrderNumber Must match the order number in the corresponding order file. "ABC-123"
2 DateTimeShipped ISO 8601 date-time that the package shipped "2024-04-17T16:00:00Z"
3 ProductCode The shipment package line SKU. Must match a SKU on the order "PRODUCT-123"
4 QtyShipped The shipment package line quantity "3"
5 TrackingNumber The tracking number of the package this line shipped in "1Z0000000000000000"
6 ShipMethod The shipment carrier and service level. For best parsing, these should be separated by three characters: space, dash, space. "UPS - GROUND"

Surrounding values with double-quotes is recommended, and is required if the data includes a comma.

Inventory files

Inventory files are CSV files generated by the fulfillment center and dropped in the SFTP server /out folder to be picked up by PackageBee. File name must begin inv_ and end in lowercase file extension .csv. Recommended file name format is inv_YYMMDDHHMMSS.csv, where YYMMDDHHMMSS represents the date-time the file was generated.

The first line of an Inventory file is a required header row identifying the columns:

"ProductCode","QtyAvailable"

Each subsequent line contains one SKU and a snapshot of its available quantity:

Pos Name Desc Example
1 ProductCode Product SKU "PRODUCT-123"
2 QtyAvailable Product available quantity "42"

Example CSV files

Example order file (Version 1 pick header)

File name: ord_SO-A0001_240417151001.csv

Download CSV
"PH","SO-A0001","PONUM-001","Jane Smith","123 Main St","Apt 1","Springfield","IL","62629","US","Attn: Jane","(987) 654-3210","John Doe","234 Spring St","Apt. 4","Chicago","IL","60007","US","UPSG","P","","2024-04-17T15:00:01Z","Amazon","Happy Anniversary! Love, John"
"PD","SO-A0001","1","ROSES-1DOZ","2","68.90"
"PD","SO-A0001","2","CHOCOLATES-BOX","1","45.67"
"PH","SO-A0002","PONUM-002","John Doe","234 Spring St","Apt 4","Chicago","IL","60007","US","Attn: John","(987) 654-3210","Jane Smith","123 Main St","Apt. 1","Springfield","IL","62629","US","UPSG","P","","2024-04-17T15:00:02Z","Amazon","Happy Anniversary! Love, Jane"
"PD","SO-A0002","1","PLAYSTATION-5","1","399.99"
"PD","SO-A0002","2","FANCY-COLOGNE-200ML","1","176.59"

Example order file (Version 2 pick header)

File name: ord_SO-A0001_240417151002.csv

Download CSV
"PH","SO-A0001","PONUM-001","john.doe@example.org","Jane Smith","123 Main St","Apt 1","Springfield","IL","62629","US","Attn: Jane","(987) 654-3210","John Doe","234 Spring St","Apt. 4","Chicago","IL","60007","US","UPSG","P","","2024-04-17T15:00:01Z","Amazon","Happy Anniversary! Love, John","Please smile and hand her the flowers in person. Thank you."
"PD","SO-A0001","1","ROSES-1DOZ","2","68.90"
"PD","SO-A0001","2","CHOCOLATES-BOX","1","45.67"
"PH","SO-A0002","PONUM-002","jane.smith@example.org","John Doe","234 Spring St","Apt 4","Chicago","IL","60007","US","Attn: John","(987) 654-3210","Jane Smith","123 Main St","Apt. 1","Springfield","IL","62629","US","UPSG","P","","2024-04-17T15:00:02Z","Amazon","Happy Anniversary! Love, Jane","If it's raining, please make sure the Playstation is left under the awning. Thanks."
"PD","SO-A0002","1","PLAYSTATION-5","1","399.99"
"PD","SO-A0002","2","FANCY-COLOGNE-200ML","1","176.59"

Example order file (Version 3 pick header)

File name: ord_SO-A0001_240417151003.csv

Download CSV
"PH","SO-A0001","PONUM-001","john.doe@example.org","Jane Smith","123 Main St","Apt 1","Springfield","IL","62629","US","Attn: Jane","(987) 654-3210","John Doe","234 Spring St","Apt. 4","Chicago","IL","60007","US","UPSG","P","","2024-04-17T15:00:01Z","Amazon","Happy Anniversary! Love, John","Please smile and hand her the flowers in person. Thank you.","Chicago Warehouse 123"
"PD","SO-A0001","1","ROSES-1DOZ","2","68.90"
"PD","SO-A0001","2","CHOCOLATES-BOX","1","45.67"
"PH","SO-A0002","PONUM-002","jane.smith@example.org","John Doe","234 Spring St","Apt 4","Chicago","IL","60007","US","Attn: John","(987) 654-3210","Jane Smith","123 Main St","Apt. 1","Springfield","IL","62629","US","UPSG","P","","2024-04-17T15:00:02Z","Amazon","Happy Anniversary! Love, Jane","If it's raining, please make sure the Playstation is left under the awning. Thanks.","Chicago Warehouse 123"
"PD","SO-A0002","1","PLAYSTATION-5","1","399.99"
"PD","SO-A0002","2","FANCY-COLOGNE-200ML","1","176.59"

Example Shipment File

File name: shp_240417161004.csv

Download CSV
ClientOrderNumber,DateTimeShipped,ProductCode,QtyShipped,TrackingNumber,ShipMethod
"SO-A0001","2024-04-17T16:00:01Z","ROSES-1DOZ","2","1Z0000000000000001","UPS - GROUND"
"SO-A0001","2024-04-17T16:00:01Z","CHOCOLATES-BOX","1","1Z0000000000000001","UPS - GROUND"
"SO-A0002","2024-04-17T16:00:02Z","PLAYSTATION-5","1","1Z0000000000000002","UPS - GROUND"
"SO-A0002","2024-04-17T16:00:02Z","FANCY-COLOGNE-200ML","1","1Z0000000000000003","UPS - GROUND"

Example Inventory File

File name: inv_240418161005.csv

Download CSV
"ProductCode","QtyAvailable"
"ROSES-1DOZ","42"
"CHOCOLATES-BOX","263"
"PLAYSTATION-5","14"
"FANCY-COLOGNE-200ML","130"

Next: SFTP server credentials and configuration


Attachments

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.