Integrating with Shipvine using EDI

Integrating with Shipvine using EDI

What integration methods can I use with Shipvine?

There are three ways to integrate your platform (i.e., get orders into and get tracking information and inventory numbers out of) Shipvine.

Shipvine Sync

Shipvine offers dozens of Shipvine-maintained, direct integrations with e-commerce platforms such as Shopify, Amazon Seller Central, ApparelMagic, Mirakl, and so on. These integrations use the target platform's API to exchange order and shipment tracking information and inventory numbers.
If Shipvine has a direct integration with your platform, you should use the direct, Shipvine-provided integration whenever possible.
The majority of Shipvine customers are using this style of integration, where Shipvine is maintaining an integration with the Shipvine Sync platform.

Shipvine Logistics API

Shipvine also offers an XML-based REST API called the Logistics API . The Shipvine-maintained platform integrations described in the "Shipvine Sync" section above end up using this same Logistics API underneath the hood, so it's a "real API" that does everything that you would want it to do. By using the Logistics API, you can integrate your custom platform or WMS directly into Shipvine.
If a direct integration with your platform is not available through Shipvine Sync, where possible, Shipvine recommends using the Logistics API to integrate such custom platforms.

Shipvine EDI

Broadly speaking, EDI accomplishes the same thing that Shipvine Sync and the Shipvine Logistics API do. You can send documents that tell Shipvine to ship an order, and Shipvine can send documents that tell you how it was shipped, and how much inventory you have. Shipvine does this by exchanging these X12 documents in "in" and "out" folders on a Shipvine-provided FTPS server.

For example, you'd drop a file representing a command to ship an order, known as a "940 - Warehouse Shipping Order" in EDI parlance, in the "in" folder on the FTP server, and Shipvine would get to work on it. If you checked the "out" folder a few hours later, you'd see a file that Shipvine dropped in there containing a "945 - Warehouse Shipping Advice" that you could use to retrieve the tracking number and email it to your customer.
Shipvine believes that new implementations of EDI technology should not be created, and existing implementations should not be encouraged to proliferate.
EDI is an old and expensive technology, designed in an era where every character counted. However, many large retailers such as department stores invested lots of money into EDI systems over the course of decades, and they're not about to throw that investment away, and the need to transact EDI documents with these retailers comes up for many of our customers. Shipvine recognizes this reality and has built a standard EDI interface that your EDI provider can use to exchange such documents with Shipvine.
Using Shipvine EDI without the use of a licensed EDI provider will incur an additional monthly fee because Shipvine will need to pay the standards authority on your behalf.
This document discusses Shipvine's EDI capabilities so you can decide how to move forward with establishing an EDI relationship with your retailer.

What is EDI?

EDI is short for "Electronic Data Interchange". It is a system for programmatically (i.e., in a machine-readable way that can be automated) exchanging information between businesses.

It is borne out of a time of businesses automating paper-based processes. You can think of an EDI document as corresponding to a piece of paper, like a sales order or a purchase order, that you might have faxed to a business in days gone by. A lot of the different EDI document types, or "transaction sets" as they're called, have recognizable names relating to common business processes, like "Purchase Order" and "Purchase Order Acknowledgment". As part of the standard, they have a three-digit number assigned to them, which doesn't mean anything other than that's the number it was given. You'll commonly hear people in the industry just talk about these documents by their identification number.

For example, when Shipvine notifies you have to how much inventory you have left, the EDI document you'd receive is called "846 - Inventory Inquiry/Advice". When you tell Shipvine about an order to ship, you'd send a "940 - Warehouse Shipping Order".

In North America, a common format for these EDI documents is called X12. This is named after the organization that sets the standard for what data is supposed to appear in them. In the example below, on the left, you can see the Shipvine XML equivalent of a "940 - Warehouse Shipping Order", which creates a fulfillment request (i.e., a command for Shipvine to ship something to a customer) via the Logistics API. That's just Shipvine's XML format that we dreamed up many years ago. On the right, you can see the equivalent document in X12 format.


An example of a request to ship an order via the Logistics API.


An example of what the same request to ship an order looks like when expressed in X12 format as a "940 - Warehouse Shipping Order" EDI document.

If you squint, you can see that the same information is present in both versions of the document. The X12 version certainly is shorter. The XML version is somewhat self-describing; a human can read this document and immediately have some idea of what the elements mean. In the X12 version, you can guess that the N3 segment contains the street address, but other segments like the W6 segment or the W01 segment are less obvious. If you are looking at an X12 document, how do you know what the segments mean?



You can think of segments as kind of like an XML element, and the data elements as XML attributes, but you don't know what any of it means unless you can look at the standard.

The only way to know what each segment and element within segment indicates is to look it up in the X12 standard specification. The elements are positional; for example, in the "TC2" segment above, the "J" in position 1 corresponds to "Commodity Code Qualifier" and clarifies what the number in position 2 is supposed to mean. (These "positions" are sometimes called "refs" in the standard.) You can only know that "J" means "Harmonized System-Based Schedule B" because you looked it up in the standard.

And because some of the data can be hierarchical (they call these "loops" in EDI) but the format does not have the concept of a closing tag, the only way to parse a transaction set that could contain hierarchical data and extract meaning from it is to "know" what segments cannot exist inside of the loop. In other words, in many X12 transaction sets, the only way you know the loop has ended is when you encounter a segment that can't exist in the loop. While you can write an X12 parser that can parse the transaction set into individual segments, there is no way to meaningful, hierarchical representation of the transaction set without referencing the standard, be it by looking it up in a PDF or by building against a schema format like SEF.

Sure, the syntax is strange, but you can get past the syntax as long as you can get to the documentation. Unfortunately, the entire standard is copyrighted and can't be published online, so you need to pay money just to be able to look at the standard and figure out what the segments and data elements mean. That's also why you can't find free SEF files floating around the Internet. However, the parts that a company has decided to implement for business-to-business interoperability can be shared with their clients as "companion guides", so you can find bits and pieces here and there on the Internet. We've shared our companion guides for the purpose of our client's interoperability in this knowledge base article.

Additionally, the X12 standards are quite large and cover a broad range of industries, and every company ends up implementing just small parts of each standard in specific ways. So it's not as simple to say that "I send 940s to Bob's 3PL, so I can send 940s to Shipvine as well, no problem." Shipvine has a specific form of 940 that it will accept, and Bob's 3PL is probably the same way, too. You will end up creating customized 940s that are "mapped" (i.e., unique to) a given trading partner. You can't just implement it once and be done with it.

Another thing to understand about EDI is that there is no routing mechanism built into the Internet for it. For example, when you send an e-mail to someone, you don't care about their e-mail server, because e-mail is baked into DNS MX records, and your mail server is going to take care of looking up the destination mail server and getting the message there without anybody having to get involved. But EDI transactions between trading partners are ad hoc. Your trading partner might want to receive EDI documents over SMTP ( AS1 ), HTTP ( AS2 , a weird blend of S/MIME on top of HTTP), FTP/FTPS/SFTP (either conforming to AS3 or some other implementation), or specifically require connection through their VAN.

There exist many EDI providers, commonly called VANs or value-added networks, out there who position themselves as solutions to this mapping and routing problem. (Originally they solved the routing problem in the days before commercial access to the Internet took off. As trading partners started exchanging documents directly with each other over the Internet, many have focused on beefing up their mapping abilities and other services.) You get an account with them and they already have established connections with lots of trading partners, so the routing part is pretty much solved. And they can help with mapping a specific transaction set from one trading partner's requirements to another's. At the end of the day, it's important to remember that this is pretty much all these people do, because the entire EDI industry is obfuscated by sales folks that will promise the moon, aggressive contracts for when things go wrong, endless Zoom meetings because no one will actually say what the document will look like until it shows up in production, and limited access to documentation because there is money to be had in the confusion. This becomes very exasperating for small businesses just entering into the world of shipping to department stores.

If you're just starting out with EDI, Shipvine recommends selecting an EDI provider with a web-based portal, and handling the transactions manually, especially for wholesale (B2B) shipments, where chargebacks for inaccurately entered ASNs can be expensive. When the number of transactions makes handling them manually unbearable, then it makes sense to contact your EDI provider and add Shipvine as an EDI trading partner according to our specifications provided below.

Is Shipvine EDI compliant?

Shipvine is EDI compliant in that we will accept and transmit certain EDI documents in X12 format that comply with the companion guides provided in this knowledge base article. Shipvine will not map its EDI documents to a specific trading partner's format. Instead, Shipvine clients would need to contract with an EDI VAN like SPS Commerce, TrueCommerce, or Spring Systems.

For example, an EDI retailer like Nordstrom might transmit to you a "850 - Purchase Order" EDI document indicating that they'd like you to ship something to them or a customer. During the onboarding process with the department store, they'd establish a connection with the EDI provider that you've selected, who would provide you with a web interface to view and manage these documents. Shipvine would work with your EDI Provider to establish a connection as well, so that you could trigger the transmission of EDI documents to Shipvine in our canonical format.


An example scenario for shipping an order

In the above example, the department store transmits an "850 - Purchase Order" EDI document to your EDI provider. You'd be able to log into your EDI provider's web portal to view details about the PO and trigger it to be sent to Shipvine as a "940 - Warehouse Shipping Order". After Shipvine picks, packs, and ships the order, we'd transmit the tracking number and pack-level detail back to your EDI Provider in the form of a "945 - Warehouse Shipping Advice" document. From there, you could use your EDI provider's web portal to transform it into the "856 - Ship Notice.Manifest" format that the department store was expecting.
The important thing to remember about EDI integration with Shipvine is that we will not perform any document mapping, so we cannot establish a trading partner relationship directly with a retailer. For example, Shipvine will send a 945 to your EDI provider, but we will never transmit an 856 directly to a retailer. You will need to select and pay for an EDI provider to manage all of your trading partner connections.

What kind of EDI documents can I exchange with Shipvine?

The EDI documents that you can exchange with Shipvine are described in the table below.
Click on the numbered links to download the complete companion guide as a PDF.
You can send these EDI documents TO Shipvine:
You can receive these EDI documents FROM Shipvine:
This document sends an order to Shipvine for fulfillment. We call them fulfillment requests . It's equivalent to the Fulfillment Request Submissions resource in the Logistics API .

This document creates item groups and items in the Shipvine Logistics catalog . It's equivalent to the Item Group and Item resources in the Logistics API.

This document lets you tell Shipvine that you're sending in inventory to be checked in. We call these inbound shipments . It's equivalent to the Inbound Shipment resource in the Logistics API.
This document tells you how a fulfillment request (a sales order) was shipped. It includes the tracking numbers and a list of what items were in each box. It's the equivalent of the Outbound Shipments resource of the Logistics API.

This document tells you how many units of a given item or SKU you have in stock at Shipvine. It's equivalent to the Inventory resource of the Logistics API. We'll send you a list of just the inventory records that have changed at a predefined interval, such as every 15 minutes.

After Shipvine has checked in an inbound shipment, this document tells you how many units of a given item or SKU that Shipvine actually received. It's the equivalent of the GET version of the Inbound Shipments resource of the Logistics API.

Whenever you send an 832, 940, or 943 to Shipvine, then Shipvine will generate a 997 to let you know if the EDI document was syntactically valid.

How do I exchange these EDI documents with Shipvine?

Shipvine exchanges EDI documents over a Shipvine-provided FTPS (not SFTP) server with "in" and "out" folders. The necessary credentials for accessing the server are provided to your EDI provider during the onboarding process.



The contents of each file should be a full X12 interchange (so it has the ISA and IEA segments, but none of the S/MIME nonsense from AS2 or AS3).
There can be multiple functional groups (GS and GE segments) in the interchange, but all of the functional groups should be of the same type, because the file name should be named after the functional group. For example, you can't mix SC (for the 832) and OW (for the 940) functional groups in the same file because Shipvine expects the file name on the FTP server to be prefixed by the code for the functional group.
The file names must be unique over a six-month period and prefixed by the functional group code. A common convention is to use a sequential number, so files containing 940s that you send to Shipvine might be named "OW000000001", "OW000000002", "OW000000003", and so on. Similarly, files that Shipvine generates might be named "SW00000001", "IB000000001", and so on. The file extension is unimportant and may be omitted.

For files that you're sending to Shipvine, you'd drop them in the "in" folder on the FTP server. Shipvine will delete the file after it's been processed.

For files that you're receiving from Shipvine, you'd check the "out" folder to pick up files that Shipvine has generated. You should delete the file after you've processed it, or Shipvine will delete it automatically after an extended time period.

Shipvine will generate 997 documents (Functional Acknowledgments) for documents that you send to Shipvine and drop them in the "out" folder. Shipvine will not expect any 997s for files that we send to you via the "out" folder, so there's no need for you to generate them.

    • Related Articles

    • Reports provided by Shipvine

      Shipvine provides a wide array of reports that will compliment reporting from your e-commerce and/or other order management platform.  Some reports are easily available from the Reports menu, other reports take a few minutes to generate and are only ...

    • Create shipping label using Shipvine Labels

      How to create a shipment in Shipvine Labels 1. Log into Labels at: https://labels.shipvine.com/pages/dashboard or select Labels from the Sites navigation menu in the top right hand corner of any Shipvine website. 2. To create a shipment, start by ...

    • How do I manage users for my Shipvine merchant account?

      Shipvine is split up into a few separate systems. Users with access to your Shipvine merchant account may have access to all or some of them. Shipvine Logistics — the main warehouse management system where you can view orders, inventory, and ...

    • Integrating with Amazon Seller Central

      As a third-party logistics (3PL) warehouse, Shipvine can physically store your inventory in our warehouse and then pick, pack, and ship your orders to your customers. It's like outsourcing the job of running a warehouse to Shipvine, allowing you to ...

    • How do I bulk import products into the Shipvine Logistics catalog using a CSV file?

      Before you create an inbound shipment to notify us of the products that you're sending to us to store in our warehouse, we'll need them entered into the Shipvine Logistics catalog. You'll tell us things like the item's name, its barcode , the country ...