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 Name||Type||Len Max||Description||Format/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|
|UPC||CHAR||30||UPC Code / GTIN||ALPHA NUMERIC|
|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.
|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|
|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|