Introducing Stash:Store and retrieve key-value dataLearn more
Stedi
Sign inBook a demoStart building
Try Stedi free

Start building an EDI system of your own.
No credit card required!

Sign Up Learn More
Blog June 24, 2022

Transaction set variants in the Amazon 850 Purchase Order

Joost Ronkes Agerbeek

A colleague told me about transaction set variants and now I want to get some more experience with them myself. In a nutshell, the problem is that one transaction set can represent different kinds of documents. For example, he showed me an implementation guide that specified that the 204 Motor Carrier Load Tender could be used to create, cancel, modify, or confirm a load tender. That feels like four different documents to me, but they are all represented by the same transaction set. So, how do you deal with that in practice?

My goal isn’t to come up with a solution, but to understand the problem. I’ll take an implementation guide that describes some transaction set variants and then I’ll try to come up with a strategy to deal with them. I don’t want to build a full implementation; I want to get a feel of what it takes to handle this in practice.

I’m going to look at the implementation guide for the 850 Purchase Order from Amazon, because I happen to have a copy. This means that today, I’m a wholesaler! Amazon sends me a purchase order, now what.

Understanding the variants

I don’t sell directly to the consumer; I leave that to Amazon, so they need my product in their warehouse. That’s why they send me an 850 Purchase Order. How do I know that I have to deal with transaction set variants? The implementation guide from Amazon doesn’t contain any preamble. It goes straight into the default information.

The start of the implementation guide, with the heading '850 Purchase Order' followed by a generic description of the transaction set.

That generic description of the transaction set doesn’t do me any good. Fortunately, I know to keep an eye out for transaction set variants, thanks to my colleague. The first segment of the transaction set (I’m not counting the envelopes) seems to contain what I’m looking for.

The details of the BEG segment as described by the implementation guide, with the BEG02 element highlighted. The element lists four codes: CN, NE, NP, and RO.

There seem to be 4 variants. Although, as you can see above, the guide mentions that there are 69 total codes. I assume that means that the standard defines 69 codes, but Amazon only uses 4 of them. Surely, Amazon doesn’t mean to say that they use 65 other codes as well, but they’re not going to tell you any more about them. Let me check that assumption with a look at the standard transaction set. Yes, that one has 69 codes. Good.

The details of the BEG segment as described by the standard. A highlight shows that the standard contains 69 codes for the BEG02 element.

So, what variants do we have? New Order I understand: that’s a new order. I feel so smart right now! Rush Order is an order that needs to be rushed, but I’m not sure how this is supposed to be treated differently than a new order. Maybe it isn’t different in terms of EDI messaging and it’s just a notification to the business: do whatever you need to do to rush this. Perhaps alarm bells should go of to let everyone know to drop whatever it is they’re doing and take care of this order. I have no idea what a consigned order is, so I should ask a domain expert, but I’m going to ask Google instead.

If I understand correctly, with a normal order, Amazon buys a product from me, puts it in their warehouse, and can then do whatever they want with it, although presumably they’ll try to sell it. With a consigned order, Amazon puts the product in their warehouse, but it still belongs to me until Amazon sells it. At that point, Amazon handles the transaction with the customer and they forward me the money, minus a transaction fee they keep for their work. If the product doesn’t sell, that’s my loss and Amazon can ship it back to me to free up some shelfspace.

Let’s see if I can get this confirmed or corrected by someone more knowledgeable than the Internet. Zack confirmed it.

That leaves New Product Introduction. Does that mean that the first time Amazon orders that product from you, it will have a separate code? Why would that be the case? Again, I’m lacking domain knowledge. For now, I’ll assume you can handle it like New Order.

Handling the variants

Now that I have an idea of the variants, I need to decide how to deal with them. That’s not a technical issue; it depends on the business needs. Since this exercise takes place in a fictitious context, there’s no one I can ask questions about the business. No matter, I might not be able to get answers, but I still should be able to figure out the questions.

The first one is whether we use consignment or not. It seems to me that we either do all our orders with consignment or none of them. That implies that we receive either NE-orders (New Order) or CN-orders (Consigned Order). That’s an understanding we need to come to with Amazon before we start processing their EDI messages. Other than that, I don’t expect a difference in the way the orders need to be routed. In both cases, the warehouse needs to fulfill the order and Finance needs to process it. How Finance processes each order will be different, but that’s beyond my concern.

A rush order may be a simple boolean flag in the system, or it may have to kick off its own, separate flow, depending on how the business operates. Does the business need me to do something special in this case? If there’s a separate flow, can we kick that off based on the simple boolean flag? That seems reasonable to me and it means that we can map the message regardless of the impact a rush order has on the business. I might need to route it somewhere else if there’s a special department handling rush orders, though.

The considerations for a new product introduction are similar to those for rush orders. If there’s a special flow, can we kick it off based on a boolean flag? Because that would make mapping simple. If we need to inform specific people of a new product introduction, we can do that based on the flag as well.

A minimal mapping

Even without the answers, I can make some reasonable assumptions about how the system should work and create a mapping based on that. I’m not going to map the entire 850, because that’s not what I’m trying to figure out here. I’m interested in handling the different variants and for that, I only need to map the BEG-segment. I can get away with that, because all three variants—NE, NP, and RO—are basically the same, except for a flag or two. Yes, I’m assuming non-consigned orders, but even that doesn’t make a big difference. For handling consigned orders, just swap out NE for CN and keep the flags. Okay, let’s open Mappings and start mapping.

The starting page for Mappings.

I’ll come up with my own custom target JSON based on the implementation guide. Yes, this is cheating, because typically you have a defined JSON shape you need to map to, but the principle is the same.

An example of the target JSON, with four fields: purchaseOrderNumber, orderDate, isRushOrder, isProductIntroduction.

I decided to go with two flags: one for rush order, one for product introduction. Another option is to create a field type that can be normal, rush, or introduction. Doesn’t matter too much; I just like the flags.

The source JSON is just a BEG-segment. That’s small enough that I can type the EDI by hand. However, in order to do the mapping, I need to convert it to JSON, because that’s what Mappings uses. I’ll use Inspector to translate my handcrafted segment to JEDI, which is Stedi’s JSON representation of EDI.

A screenshot of the Inspector parsing a BEG segment.

Inspector doesn’t like that single segment very much. I guess I should tell it which transaction set it’s dealing with.

Hey, I just noticed that the Amazon implementation guide provides sample data for each individual segment, so I didn’t have to type it by hand. That’s marvelous.

An example of a BEG segment, as provided by the Amazon implementation guide.

I add a transaction set identifier code. That’s still not enough to make Inspector happy, but it’s enough to keep it satisfied and it does its best to produce some JEDI. It looks fine for my purposes, so kudos to Inspector.

A screenshot of the Inspector parsing a BEG segment wrapped in a transaction set envelope.

The purchase order is trivial to map, because it’s a one-to-one copy of a specific field.

The mapping expression for the field purchaseOrderNumber.

The date isn’t much harder. It just requires a minimal bit of conversion, because I like dashes in my date.

The mapping expression for the field orderDate.

Will the flags be more challenging?

The mapping expression for the field isRushOrder.

That’s not quite right. The code in the sample JEDI isn’t NE, but new_order_NE. JEDI makes the values more readable, but now I have to figure out what the JEDIfied versions are of RO and NP. Fortunately, Inspector can help me here.

A screenshot of the Inspector showing the JEDI values for RO and NP.

Now that I know that, the mapping expressions for the flags will be simple.

The corrected mapping expression for the field isRushOrder.The mapping expression for the field isProductIntroduction.

That’s it?

The whole exercise was less of a hassle than I expected to be honest. Granted, I made things easy on myself by assuming only a single transaction set in the EDI message and by mapping only a single segment, but why would I want to make things hard for myself?

That’s not the real reason it was easier than expected, though. The real reason is that the variants of the Amazon 850 purchase order are all pretty much the same. I was able to handle them with nothing more than two flags. Most transaction sets that have variants will be more difficult to handle. If you’re disappointed by the lack of suffering I had to go through this time, then you can take comfort in the fact that the next transaction set with variants is bound to cause me more of a headache.

Featured
Mappings
Map data into any shape

Mappings is a tool that maps JSON documents from one structure to another to integrate with any pipeline.

Try Mappings Learn more 
EDI Reference
X12 EDI documentation

Reference contains all transaction sets, segments, and data element of every X12 release. Just type in what you need and Reference will find it for you.

EDI Inspector
Human-readable EDI

Inspector turns EDI into a human-readable format, complete with descriptions of every field. Quickly visualize, debug, and collaborate on EDI documents.

Share
Previous
Getting started with the X12 file format
Subscribe

Get blog posts delivered to your inbox.

Stedi

Stedi is a developer-focused platform for building automated EDI solutions that integrate with any business system.

Sign up to get an API key and try Stedi’s pay-⁠per-⁠use products with generous free tiers.

Start building
Products
EDI CoreMappingsConverterSFTPBucketsFunctionsStash
Follow
  1. Twitter
  2. GitHub
Backed by
AdditionBloomberg BetaFirst RoundStripeUSV
Customer AgreementService TermsPrivacy Notice

Stedi is a registered trademark of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.