Order Integration: Flat File (CSV)

GovX has the ability to process Order exports, ASN's (advanced shipping notices), Inventory, and Product loads via flat file. Flat files are exchanged over FTP or SFTP. GovX hosts an FTP server (recommended) or files can be exchanged over the partner’s specified FTP server.

This article specifically outlines the data dictionary for an order integration. Inventory integration via flat file is covered in a separate document here


Getting Started Guide

Step 1 | Create Account

Before calling the FTP service you will need to have a partner account created in GovX. Your GovX Brand Manager can provide you with the credentials. 

Step 2 | Determine Schedule

Determine the frequency for transmitting new order files and ASN's. We recommend batching order files hourly (this is the default setting). Your GovX Brand Manager can assist you with this decision. 

Step 3 | Coordinate Product Codes

When integrating with GovX it is important to establish the product codes that will be used for integration. Typically, the product codes used for integration are UPC but another unique identifier can also be used. It is important that the GovX Brand Manager knows the product code that will be used in integration as it must be set when loading the products into GovX.

Step 4 | Configure Order Files

The format of the order file that GovX will send you is configurable to meet your needs. You'll need to let your GovX Brand Manager know how you'd like the file configured. Please see the Order File Data Dictionary for configuration options. 

Step 5 | Confirm ASN File Format

ASN's are files you'll send back to GovX to confirm order fulfillment. These files are vitally important in order for us to adequately communicate with our customers. The file format is specified in the ASN File Data Dictionary section below.

Step 6 | Accessing FTP Server

The FTP service is publicly available on both staging and production servers using the ftp.govx.com URI. Supported transfer types are FTP, FTPS, SFTP, HTTP and HTTPS.

New orders for a Partner to download (potentially multiple files) will be located in the 'orders' directory. It is the Partner's job to maintain files and track/delete files that have been processed. Partners can utilize the archive subdirectory to archive files on the GovX server.

Step 7 | Testing

Before we launch the integration, we will test the end-to-end order flow. The test will be deemed successful when an ASN is received by GovX for the test order. 

Order File Data Dictionary

The order file format is configurable. You may request any of the columns below in any order. You can also request blank columns or hard coded values in any column.

Order files represent order information for all the ordered items. The following data dictionary represents a valid GovX Order. If an order has more than one line item the order header information will be repeated for each line in the order. Note: If GovX detects that an order is destined to an APO/FPO address the shipping method will be designated as USPS.

Field NameTypeLen MaxDescriptionFormat/Value
OrderID CHAR 21 GovX Order Number  
OrderDate CHAR 20 GovX Order Date MM/DD/YYYY
CustomerNumber CHAR 15 GovX Customer Number  
ShipmentMethod CHAR 15 Shipping Method Ground, 2-Day, USPS
ShipToFullName CHAR 65 Ship To First and Last Name  
ShipToFirstName CHAR 65 Ship To First Name  
ShipToLastName CHAR 65 Ship To Last Name  
ShipToAddress1 CHAR 65 Shipping to Address 1  
ShipToAddress2 CHAR 65 Shipping to Address 2  
ShipToEmail CHAR 65 Shipping to Email  
ShipToCity CHAR 35 Shipping to City  
ShipToState CHAR 2 Shipping to State  
ShipToZipCode CHAR 10 Shipping to Zip Code  
ShipToPhoneNumber CHAR 21 Shipping to Phone Number  
ItemNumber CHAR 30 Manufacturer Material Number ALPHA NUMERIC
Quantity NUMBER 21 Item Quantity  
UnitPrice NUMBER 21 Item’s Unit Price (Cost of Goods) Decimal 2


ASN File Data Dictionary

Order Status updates, also called Advanced Shipping Notice or ASN, must be posted to GovX on a predetermined frequency to update GovX’s order management system with the latest statuses for each PO. The following data dictionary represents a valid ASN file.

Note: Only the order number, ship date, and tracking number are required. Omitting the additional information will update all items on the order for the partner with the same shipped date (default to current date/time), status (default to Shipped), and tracking number. Omission of the order detail means we'll assumed the order has shipped complete and the requested quantities on the order will be used as the shipped quantities. If an individual ItemNumber is not supplied then the supplied quantity will be ignored.

Once the shipped status is replied on a message you will not be permitted to submit a status other than shipped again for the order.

The fields can be in any order, but the format will need to be configured by GovX upon setup and should not be changed thereafter. Additionally, you can use tab or commas as field delimiter. 

Field NameTypeLengthDescriptionFormat/ValueRequired
OrderID CHAR 21 GovX Order Number   Yes
VendorOrderNumber CHAR 21 Vendor Order number if the loading is successful    
Status CHAR 15 Current Status of the Order Shipped, Cancelled  
ItemNumber CHAR 30 Material UPC code    
Quantitiy NUMBER 21 Order quantity    
ShipDate CHAR 20 Promised ship date / Date shipped, if already done. MMDDYYYY HH:MM Yes
ShipMethod CHAR 10 Carrier SCAC Code UPS,USPS,FedEx and other Standard carrier Alpha Code  
Freight NUMBER 21 Actual Freight Amount for shipping the OrderItem Decimal 2  
TrackingNumber CHAR 30 Shipment Tracking number   Yes
Have more questions? Submit a request


Please sign in to leave a comment.