Table of Contents
SPS Commerce
Updated
by Colin

SPS Commerce offers, among other things, a leading solution for business-to-business data exchange, taking much of the pain out of setting up and maintaining your EDI connections.
ShipStream's SPS Commerce integration makes a direct connection to your SPS Commerce account and simplifies the setup of your trading partners to get you launched quickly and with minimal effort.
Overview
In a nutshell, there are two components to setting up EDI via SPS Commerce:
- Setup the Global Integration to connect to your SPS Commerce account (only performed once)
- Add a Merchant Integration to map your Trading Partners to the correct ShipStream Merchants and Brands by Vendor ID and Trading Partner ID (performed once per merchant)
The Global Integration establishes the connection to SPS Commerce and acts as a communication channel for the SPS Commerce Merchant Integration, of which you may setup any number of subscriptions. This allows the configuration to be managed per-Merchant, giving your merchants maximum flexibility and visibility while keeping the EDI data and connection management siloed appropriately.
- When an EDI file is received from SPS Commerce, ShipStream will parse the file and attempt to match it to a Merchant Integration subscription based on the Vendor ID and Use Test Directories options.
- Merchants will be able to see Integation Errors that are logged for troubleshooting so long as the incoming EDI files matched the Merchant's SPS Commerce integration subscription using the Vendor ID.
- If a Merchant cannot be matched to the incoming file's Vendor ID, the EDI Transaction will be left in "Merchant Not Found" status and will not be visible to any merchants. After you add a new Merchant Integration or update the Vendor ID and Use Test Directories options of an existing one you may click "Retry" on the EDI Document page to resume the processing.
- All sent and received documents can be seen at System > Integrations > EDI Documents for organization users. Client users also have this page, but will only be able to see the EDI Documents that were matched to them based on the Vendor ID.
Supported Fulfillment Models
ShipStream currently supports the Drop Ship (B2C) and Bulk Import (B2B) fulfillment models. Please let us know if you are interested in supporting other fulfillment models.
The following document types are utilized:
- Orders - Receive orders for goods fulfillment
- 850, 875, 940, ORDERS, PurchaseOrders
- Will be read from
/out/*
or/testout/*
paths by default. Override with Order File Paths configuration.
- OrderAcks - Acknowledge receipt of or reject Orders
- 855, ORDRSP, PurchaseOrderAcks
- Will be written to
/in/PR*
or/testin/PR*
paths
- Shipments - Notify of shipped goods including tracking details
- 856, 943, 945, AdvanceShipNotices, DESADV
- Will be written to
/in/SH*
or/testin/SH*
paths
- Inventory Advice - Notify of inventory levels
- 846, INVRPT
- Will be written to
/in/IB*
or/testin/IB*
paths
Setup Global Integration
Before you can start, you will need an account with SPS Commerce. If you don't have one, let us know and we'll get you introduced!
Once you have your SPS Commerce account, head over to your ShipStream instance and follow these instructions.
- Login and click System > Integrations > Global Integrations (if you don't see this you may need to add or update your User Roles).
- Below "Setup new Global Integration" click "SPS Commerce".
- If your Location IDs are known and differ from your ShipStream Warehouse IDs (see System > Enumerations > System > Warehouses), add them to the Location ID Map.
- Click Save and Continue Edit.
- Click the Authorize button and complete the authorization with your SPS Commerce account.
- When you are returned to the ShipStream page for the SPS Commerce integration you should see your company name as designated by SPS Commerce listed in the Connection Status after "Organization".

The connection setup is now complete and ShipStream can now pull and push data files to and from your SPS commerce account!
You are now ready to proceed to Setup Merchant Integration below.
Additional Configuration
There are some additional configuration options that are not typically required but may be necessary in some cases.

Order File Paths
By default, ShipStream will read order files from the out/
and testout/
directories of the SPS Commerce server. Subdirectories are ignored by default, so if you need to read files from a different directory or only with specific prefixes, these must be specified here. For example, a configuration of PO/PO,testout/MyOrders/
would cause ShipStream to read only files matching these paths and ignore all others:
- out/PO/PO*
- testout/PO/PO*
- testout/MyOrders/*
testout/
will only be matched to Merchant Integrations with the Use Test Directories option set to Yes.Setup Merchant Integration
Once your Global Integration is setup you still need to setup a Merchant Integration subscription for each merchant that will use SPS Commerce. Incoming documents are mapped to these Merchant Integrations based on the Trading Partner ID. If different Trading Partners require different settings you can setup multiple Merchant Integrations, but you can also receive multiple Trading Partners to the same Merchant Integration.
- Login and click System > Integrations > Merchant Integrations (if you don't see this you may need to add or update your User Roles).
- Click Add New Subscription.
- Select the appropriate Merchant and click SPS Commerce in the list of integrations.
- Configure the integration as appropriate (details below) and click Save Subscription.
Subscription Configuration
On the subscription page, expand the Subscription Configuration section to configure it to the merchant's specific needs.
Use Test Directories
Selecting "Yes" will cause incoming files to be matched to this integration only if they come from the testout/
directory, and file uploads will be placed in the testin/
directory. Otherwise, incoming files from the out/
directory will be potentially matched and file uploads will be placed in the in/
directory.
Trading Partner ID Map
Add a row for each Trading Partner ID for which you will be receiving orders and select the appropriate Brand for each.

Shipping Method Translation
As every order must have a Shipping Method assigned, the integration will make it's best effort to map the incoming CarrierAlphaCode
and ServiceLevelCode
fields to the closest matching Shipping Method. But, you may override this and specify a Shipping Method Translation to map the CarrierAlphaCode
, CarrierRouting
and ServiceLevelCode
values coming from SPS Commerce to the ShipStream Shipping Method of your choice.
The CarrierRouting
value is a free-form field so will vary by Trading Partner. The ServiceLevelCode
should be somewhat standardized and the expected values are listed in Default Shipping Method Translation.
Example 1
To map any value for CarrierAlphaCode
and any value for CarrierRouting
and the ServiceLevelCode
for "Standard Ground" service (SG) to a Virtual Shipping Method which performs Rate Shopping.

Example 2
To map CarrierAlphaCode
"UPSN" with CarrierRouting
values "NS" or "SG" and ServiceLevelCode
"NS" to UPS Next Day Air you could use the following:

Send Order Acknowledgement
Choose Yes if your trading partners require an Order Ack document for each Order document received.
Send Shipment ASN
Choose Yes if your trading partners require an ASN document for each Shipment when the shipment is packed. These documents will either be sent after the manifest is sealed or at 8am or 8pm warehouse time, whichever comes first.
Inventory Advice
To report your inventory levels to your trading partners you will simply need to add an Inventory Advice configuration for each Trading Partner which is entered in the first field, and the time interval selected for that Trading Partner in the second field.

Once saved, you can also force an upload to occur immediately by clicking "Upload Inventory Advice" in the Actions section.

Order Transform Script
You can provide some basic Javascript code to transform the order data based on the entire SPS Commerce document which is present as a Javscript object in the variable spsCommerceOrder
. This script can modify the order
object before it is submitted.
This example script maps Signature Required and Saturday Delivery values for Target.com orders to the relevant ShipStream order options.
let carrierInformation = spsCommerceOrder.Header.CarrierInformation[0] || {};
switch (carrierInformation.CarrierRouting) {
case 'SG': // Signature Required (UPS/FedEx)
case 'NDSS': // Next Day Air with Signature Required (FedEx)
case 'HDS': // Home Delivery with Signature Required (FedEx)
case 'PONS': // Priority Overnight with Signature Required (FedEx)
case 'NDSS': // Next Day Standard with Signature Required (FedEx)
case 'ESS': // Express Saver with Signature Required (FedEx)
case 'HDS': // Home Delivery with Signature Required (FedEx)
case 'IS': // Through the Door with Signature Required (LTL)
case 'RS': // Room of Choice with Signature Required (LTL)
case 'WS': // White Glove with Signature Required (LTL)
case 'AS': // White Glove Assembly with Signature Required (LTL)
order.options.signature_required = 'any'
break
}
let serviceLevelCodes = carrierInformation.ServiceLevelCodes.map(v => v.ServiceLevelCode)
let saturdayDelivery = serviceLevelCodes.some((v) => {
switch (v) {
case 'NS': // Next Day Saturday
case 'SS': // 2 Day Saturday
return true;
default:
return false;
}
})
if (saturdayDelivery) {
order.options.saturday_delivery = true
}
Shipment Transform Script
The Reference Qualifiers and Order Line Item properties will be copied from the original Order document when generating the Shipment document and we make a best effort to map our shipping methods to the "Carrier Routing" value as well. However, sometimes these may not meet specific requirement of your Trading Partners so we provide the Shipment Transform Script which allows you to customize the generated document before it is transmitted to SPS Commerce.
This script has in it's scope the following variables:
eventData
- data from theshipment:packed
,shipment:shipped
ormanifest:sealed
eventshipment
- the ShipStream shipment being evaluatedorder
- the ShipStream order associated with the shipmentspsCommerceShipment
- the object which will be used to generated the SPS Commerce Shipment documentspsCommerceOrder
- an object representing the original SPS Commerce Order document received
Service Level Codes
These are common qualifiers and definitions for the ServiceLevelCode
field.
Qualifier | Definition |
3D | Three Day Service |
AM | A.M. Service |
CG | Ground |
CX | Express Service |
DC | Delivery Confirmation |
DS | Door Service |
ET | Proof of Delivery with Signature |
FC | First Class |
G2 | Standard Service |
IDL | Inside Delivery |
IE | Expedited Service - Worldwide |
IS | International Service |
IX | Express Service - Worldwide |
LM | Last Mile Delivery (typically services that use USPS for the last-mile delivery - e.g. FedEx Ground Economy, UPS SurePost, DHL SmartMail, etc.) |
LT | Economy |
ME | Metro |
ND | Next Day Air |
NF | Next Flight Out |
NH | Next Day Hundred Weight |
NM | Next Morning |
NXD | Next Day |
ON | Overnight |
PA | Primary Service Area - Next Day by 10:30 A.M. |
PB | Priority Mail |
PC | Primary Service Area - Next Day by 9:30 A.M. |
PI | Priority Mail Insured |
PM | P.M. Service |
PN | Primary Service Area - Next Day by Noon |
PO | P.O. Box/Zip Code |
PR | Primary Service Area - Next Day by 5:00 P.M. |
PS | Primary Service Area - Second Day by Noon |
PT | Pooled Shipment |
PX | Premium Service (typically seen as White Glove Service, but varies by carrier or provider ) |
SA | Same Day |
SC | Second Day Air |
SD | Saturday Service |
SE | Second Day |
SG | Standard Ground |
SH | Second Day Hundred Weight |
SI | Standard Ground Hundred Weight |
Default Shipping Option Translation
ShipStream automatically sets the following service level options based on the CarrierAlphaCode
and ServiceLevelCode
. This can be overridden by the Order Transform Script.
CarrierAlphaCode | ServiceLevelCodes | Service Level |
* | ET | Signature Required |
* | SD | Saturday Delivery |
Default Shipping Method Translation
ShipStream automatically sets the following shipping methods based on the CarrierAlphaCode
and ServiceLevelCode
. This can be overridden by either the Shipping Method Translation or the Order Transform Script.
CarrierAlphaCode | ServiceLevelCodes | Region | Shipping Method |
FDE | SC | US | FedEx 2 Day |
FDE | PS | US (Hawaii outbound) | FedEx 2 Day AM |
FDE | IE | US,EU,LAC,MEISA | FedEx International Priority |
FDE | G2,3D | US,LAC | FedEx Express Saver |
FDE | PC | US,MX,MEISA | FedEx First Overnight |
FDE | IS | US,EU,APAC | FedEx International Economy |
FDE | IX | US,EU,APAC | FedEx International First |
FDE | PN | US,EU,LAC,MEISA | FedEx Priority Overnight |
FDE | SA | US,MX | FedEx Same Day |
FDE | ON,ND | US,LAC,MEISA | FedEx Standard Overnight |
FDEG | G2,SG | US | FedEx Ground |
FDEG | CG | US | FedEx Home Delivery |
FXFE | ND | US | FedEx 1 Day Freight |
FXFE | SE | US,LAC | FedEx 2 Day Freight |
FXFE | 3D | US | FedEx 3 Day Freight |
FXFE | IS | US,APAC,EU | FedEx International Economy Freight |
FXFE | IE | US,LAC,APAC,MEISA,EU | FedEx International Priority Freight |
FXSP | G2,LM | US | FedEx Ground Economy |
LASG | SG | US | LaserShip Ground |
LSOV | AM,NXD | US | LSO Early Next Day |
LSOV | LT,SG | US | LSO Economy Next Day |
LSOV | SG | US | LSO Ground |
LSOV | NXD | US | LSO Priority Next Day |
LSOV | SD | US | LSO Saturday |
ONTC | SG | US | OnTrac Ground |
ONTC | SA | US | OnTrac Same Day |
ONTC | NM | US | OnTrac Sunrise |
SDED | ON | US | Spee-Dee Delivery |
UPSM | PB,IS | US | UPS Economy Mail Innovations International |
UPSM | FC | US | UPS First Class Mail Innovations |
UPSM | PB,CX | US | UPS Parcel Select Mail Innovations |
UPSM | PB | US | UPS Priority Mail Innovations |
UPSM | PB,IE | US | UPS Priority Mail Innovations International |
UPSN | SC | US | UPS 2nd Day Air |
UPSN | SC,AM | US | UPS 2nd Day Air A.M. |
UPSN | 3D | US | UPS 3 Day Select |
UPSN | CG,SG | US | UPS Ground |
UPSN | ND | US | UPS Next Day Air |
UPSN | ND,AM | US | UPS Next Day Air Early |
UPSN | ND,PM | US | UPS Next Day Air Saver |
UPSN | G2 | US | UPS Standard |
UPSN | LM | US | UPS SurePost |
UPSN | IE | US | UPS Worldwide Expedited |
UPSN | IX | US | UPS Worldwide Express |
UPSN | IX,CX | US | UPS Worldwide Express Plus |
UPSN | IS | US | UPS Worldwide Saver |
USPS | FC | US | USPS First-Class |
USPS | FC,IS | US | USPS First-Class International |
USPS | SG | US | USPS Parcel Select Ground |
USPS | PB | US | USPS Priority Mail |
USPS | CX | US | USPS Priority Mail Express |
USPS | IX | US | USPS Priority Mail Express International |
USPS | IS | US | USPS Priority Mail International |