X12 856 advance ship notice (ASN): format and example

856 structure

The full X12 856 layout from its OpenEDI definition, the same model ediFabric uses to parse, validate and generate it: 7 loops and 58 segment positions, in file order. Loops are shaded and their segments indented; Max use is how many times a segment or loop may repeat.

Segment / loop	Name	Usage	Max use
`ST`	Transaction Set Header	Mandatory	1
`BSN`	Beginning Segment for Ship Notice	Mandatory	1
`DTM`	Date/Time Reference	Optional	10
HL loop	Hierarchical Level	Mandatory	200000
`HL`	Hierarchical Level	Mandatory	1
`LIN`	Item Identification	Optional	1
`SN1`	Item Detail (Shipment)	Optional	1
`SLN`	Subline Item Detail	Optional	1000
`PRF`	Purchase Order Reference	Optional	1
`PO4`	Item Physical Details	Optional	1
`PID`	Product/Item Description	Optional	200
`MEA`	Measurements	Optional	40
`PWK`	Paperwork	Optional	25
`PKG`	Marking, Packaging, Loading	Optional	25
`TD1`	Carrier Details (Quantity and Weight)	Optional	20
`TD5`	Carrier Details (Routing Sequence/Transit Time)	Optional	12
`TD3`	Carrier Details (Equipment)	Optional	12
`TD4`	Carrier Details (Special Handling, or Hazardous Materials, or Both)	Optional	5
`TSD`	Assigned Identification, Position	Optional	1
`REF`	Reference Identification	Optional	>1
`PER`	Administrative Communications Contact	Optional	3
LH1 loop	Hazardous Identification Information	Optional	100
`LH1`	Hazardous Identification Information	Mandatory	1
`LH2`	Hazardous Classification Information	Optional	4
`LH3`	Hazardous Material Shipping Name	Optional	12
`LFH`	Freeform Hazardous Material Information	Optional	20
`LEP`	EPA-Required Data	Optional	>1
`LH4`	Canadian Dangerous Requirements	Optional	1
`LHT`	Transborder Hazardous Requirements	Optional	3
`LHR`	Hazardous Material Identifying Reference Numbers	Optional	10
`PER`	Administrative Communications Contact	Optional	5
`LHE`	Empty Equipment Hazardous Material Information	Optional	1
CLD loop	Load Detail	Optional	200
`CLD`	Load Detail	Mandatory	1
`REF`	Reference Identification	Optional	200
`DTP`	Date or Time or Period	Optional	1
`MAN`	Marks and Numbers	Optional	>1
`DTM`	Date/Time Reference	Optional	10
`FOB`	F.O.B. Related Instructions	Optional	1
`PAL`	Pallet Information	Optional	1
N1 loop	Name	Optional	200
`N1`	Name	Mandatory	1
`N2`	Additional Name Information	Optional	2
`N3`	Address Information	Optional	2
`N4`	Geographic Location	Optional	1
`REF`	Reference Identification	Optional	12
`PER`	Administrative Communications Contact	Optional	3
`FOB`	F.O.B. Related Instructions	Optional	1
`SDQ`	Destination Quantity	Optional	50
`ETD`	Excess Transportation Detail	Optional	1
`CUR`	Currency	Optional	1
SAC loop	Service, Promotion, Allowance, or Charge Information	Optional	>1
`SAC`	Service, Promotion, Allowance, or Charge Information	Mandatory	1
`CUR`	Currency	Optional	1
`GF`	Furnished Goods and Services	Optional	1
`YNQ`	Yes/No Question	Optional	10
LM loop	Code Source Information	Optional	10
`LM`	Code Source Information	Mandatory	1
`LQ`	Industry Code	Mandatory	100
V1 loop	Vessel Identification	Optional	>1
`V1`	Vessel Identification	Mandatory	1
`R4`	Port or Terminal	Optional	>1
`DTM`	Date/Time Reference	Optional	>1
`CTT`	Transaction Totals	Optional	1
`SE`	Transaction Set Trailer	Mandatory	1

Mandatory segments must be sent, Optional ones only when the data applies. Trading partners often add their own rules in companion guides - ediFabric templates can be adjusted to match. Open the element-level definition in the EdiNation spec library.

Sample 856 file

A ship notice with shipment, order, pack and item levels. Paste it into EdiNation to see every element named and validated.

ISA*00*          *00*          *16*SENDER1        *14*RECEIVER1      *071216*1406*U*00204*000000263*1*T*>~
GS*IN*SENDER1*RECEIVER1*20071216*1406*000000001*X*004010~
ST*856*0001~
BSN*00*01140824*20051015*1345*0001~
HL*1**S~
TD1*CTN25*2****G*45582*LB*1000*CF~
TD5*B*2*JBHT*M~
TD3*TL*ABCD*07213567******30394938483234~
REF*BM*01140824~
REF*CN*082131~
REF*CR*01082131~
DTM*011*200~
N1*ST*WAL-MART DC 6094J-JIT*UL*0078742035260~
N1*SF*SUPPLIER NAME~
HL*2*1*O~
PRF*9988776655***20051015~
REF*IA*211555050~
REF*DP*00005~
REF*MR*0073~
REF*IV*01140824~
N1*BY*WAL-MART STORES,INC.*UL*0078742000992~
HL*3*2*P~
MAN*GM*00000010012345614785~
HL*4*3*I~
LIN**UP*008815509183~
SN1**4*EA~
HL*5*3*I~
LIN**UP*008815547321~
SN1**9*EA~
HL*6*1*O~
PRF*2288115555***20051015~
REF*IA*211555050~
REF*DP*00005~
REF*MR*0073~
REF*IV*01140824~
N1*BY*WAL-MART STORES,INC.*UL*0078742000015~
HL*7*6*P~
MAN*GM*00000010012378945698~
HL*8*7*I~
LIN**UP*008815509183~
SN1**4*EA~
HL*9*7*I~
LIN**UP*008815547321~
SN1**9*EA~
CTT*9~
SE*44*0001~
GE*2*000000001~
IEA*1*000000263~

The same 856 as JSON

ediFabric turns every loop, segment and element into a named field. This is the transaction from the sample, in the JSON that ediFabric Native and Cloud return and accept.

{
  "ST": {
    "TransactionSetIdentifierCode_01": "856",
    "TransactionSetControlNumber_02": "0001"
  },
  "BSN": {
    "TransactionSetPurposeCode_01": "00",
    "ShipmentIdentification_02": "01140824",
    "Date_03": "20051015",
    "Time_04": "1345",
    "HierarchicalStructureCode_05": "0001"
  },
  "HLLoop": [
    {
      "HL": {
        "HierarchicalIDNumber_01": "1",
        "HierarchicalLevelCode_03": "S"
      },
      "TD1": [
        {
          "PackagingCode_01": "CTN25",
          "LadingQuantity_02": "2",
          "WeightQualifier_06": "G",
          "Weight_07": "45582",
          "UnitorBasisforMeasurementCode_08": "LB",
          "Volume_09": "1000",
          "UnitorBasisforMeasurementCode_10": "CF"
        }
      ],
      "TD5": [
        {
          "RoutingSequenceCode_01": "B",
          "IdentificationCodeQualifier_02": "2",
          "IdentificationCode_03": "JBHT",
          "TransportationMethodTypeCode_04": "M"
        }
      ],
      "TD3": [
        {
          "EquipmentDescriptionCode_01": "TL",
          "EquipmentInitial_02": "ABCD",
          "EquipmentNumber_03": "07213567",
          "SealNumber_09": "30394938483234"
        }
      ],
      "REF": [
        {
          "ReferenceIdentificationQualifier_01": "BM",
          "ReferenceIdentification_02": "01140824"
        },
        {
          "ReferenceIdentificationQualifier_01": "CN",
          "ReferenceIdentification_02": "082131"
        },
        {
          "ReferenceIdentificationQualifier_01": "CR",
          "ReferenceIdentification_02": "01082131"
        }
      ],
      "DTM": [
        {
          "DateTimeQualifier_01": "011",
          "Date_02": "200"
        }
      ],
      "N1Loop": [
        {
          "N1": {
            "EntityIdentifierCode_01": "ST",
            "Name_02": "WAL-MART DC 6094J-JIT",
            "IdentificationCodeQualifier_03": "UL",
            "IdentificationCode_04": "0078742035260"
          }
        },
        {
          "N1": {
            "EntityIdentifierCode_01": "SF",
            "Name_02": "SUPPLIER NAME"
          }
        }
      ]
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "2",
        "HierarchicalParentIDNumber_02": "1",
        "HierarchicalLevelCode_03": "O"
      },
      "PRF": {
        "PurchaseOrderNumber_01": "9988776655",
        "Date_04": "20051015"
      },
      "REF": [
        {
          "ReferenceIdentificationQualifier_01": "IA",
          "ReferenceIdentification_02": "211555050"
        },
        {
          "ReferenceIdentificationQualifier_01": "DP",
          "ReferenceIdentification_02": "00005"
        },
        {
          "ReferenceIdentificationQualifier_01": "MR",
          "ReferenceIdentification_02": "0073"
        },
        {
          "ReferenceIdentificationQualifier_01": "IV",
          "ReferenceIdentification_02": "01140824"
        }
      ],
      "N1Loop": [
        {
          "N1": {
            "EntityIdentifierCode_01": "BY",
            "Name_02": "WAL-MART STORES,INC.",
            "IdentificationCodeQualifier_03": "UL",
            "IdentificationCode_04": "0078742000992"
          }
        }
      ]
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "3",
        "HierarchicalParentIDNumber_02": "2",
        "HierarchicalLevelCode_03": "P"
      },
      "MAN": [
        {
          "MarksandNumbersQualifier_01": "GM",
          "MarksandNumbers_02": "00000010012345614785"
        }
      ]
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "4",
        "HierarchicalParentIDNumber_02": "3",
        "HierarchicalLevelCode_03": "I"
      },
      "LIN": {
        "ProductServiceIDQualifier_02": "UP",
        "ProductServiceID_03": "008815509183"
      },
      "SN1": {
        "NumberofUnitsShipped_02": "4",
        "UnitorBasisforMeasurementCode_03": "EA"
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "5",
        "HierarchicalParentIDNumber_02": "3",
        "HierarchicalLevelCode_03": "I"
      },
      "LIN": {
        "ProductServiceIDQualifier_02": "UP",
        "ProductServiceID_03": "008815547321"
      },
      "SN1": {
        "NumberofUnitsShipped_02": "9",
        "UnitorBasisforMeasurementCode_03": "EA"
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "6",
        "HierarchicalParentIDNumber_02": "1",
        "HierarchicalLevelCode_03": "O"
      },
      "PRF": {
        "PurchaseOrderNumber_01": "2288115555",
        "Date_04": "20051015"
      },
      "REF": [
        {
          "ReferenceIdentificationQualifier_01": "IA",
          "ReferenceIdentification_02": "211555050"
        },
        {
          "ReferenceIdentificationQualifier_01": "DP",
          "ReferenceIdentification_02": "00005"
        },
        {
          "ReferenceIdentificationQualifier_01": "MR",
          "ReferenceIdentification_02": "0073"
        },
        {
          "ReferenceIdentificationQualifier_01": "IV",
          "ReferenceIdentification_02": "01140824"
        }
      ],
      "N1Loop": [
        {
          "N1": {
            "EntityIdentifierCode_01": "BY",
            "Name_02": "WAL-MART STORES,INC.",
            "IdentificationCodeQualifier_03": "UL",
            "IdentificationCode_04": "0078742000015"
          }
        }
      ]
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "7",
        "HierarchicalParentIDNumber_02": "6",
        "HierarchicalLevelCode_03": "P"
      },
      "MAN": [
        {
          "MarksandNumbersQualifier_01": "GM",
          "MarksandNumbers_02": "00000010012378945698"
        }
      ]
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "8",
        "HierarchicalParentIDNumber_02": "7",
        "HierarchicalLevelCode_03": "I"
      },
      "LIN": {
        "ProductServiceIDQualifier_02": "UP",
        "ProductServiceID_03": "008815509183"
      },
      "SN1": {
        "NumberofUnitsShipped_02": "4",
        "UnitorBasisforMeasurementCode_03": "EA"
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "9",
        "HierarchicalParentIDNumber_02": "7",
        "HierarchicalLevelCode_03": "I"
      },
      "LIN": {
        "ProductServiceIDQualifier_02": "UP",
        "ProductServiceID_03": "008815547321"
      },
      "SN1": {
        "NumberofUnitsShipped_02": "9",
        "UnitorBasisforMeasurementCode_03": "EA"
      }
    }
  ],
  "CTT": {
    "NumberofLineItems_01": "9"
  },
  "SE": {
    "NumberofIncludedSegments_01": "44",
    "TransactionSetControlNumber_02": "0001"
  }
}

Parse and validate an 856 file

Read the file into typed objects with ediFabric .NET, convert it to JSON in process with the ediFabric Native bindings for Python, Java and C, or post it to the ediFabric Cloud REST API from any language.

.NET
Python
Java
C
Cloud

using EdiFabric.Templates.X12004010;

License.SetSerial("YOUR_SERIAL_KEY");

using (var stream = File.OpenRead(@"C:\edi\ShipNotice.txt"))
using (var reader = new X12Reader(stream, "EdiFabric.Templates.X12"))
{
    var items = await reader.ReadToEndAsync();
    foreach (var transaction in items.OfType<TS856>())
    {
        if (transaction.IsValid(out MessageErrorContext errors))
            Console.WriteLine($"{transaction.ST.TransactionSetControlNumber_02} is valid");
        else
            Console.WriteLine(string.Join(Environment.NewLine, errors.Flatten()));
    }
} Install and get started 856 example project Walkthrough
import json
import edifabric_x12 as ef

serial = "YOUR_SERIAL_KEY"
ef.load_library()
ef.set_serial(serial)
ef.set_map(json.dumps({"default": serial, "maps": {}}))

edi = open("ShipNotice.txt", "rb").read()
output, offset = ef.parse(edi, ef.ParseMode.JSON_VALIDATE)
transactions = output[:offset]
report = json.loads(output[offset:])
print(report["errors_count"]) Python bindingsediFabric Native
import com.edifabric.nativex12.EdiFabricX12;
import com.edifabric.nativex12.ParseMode;
import com.edifabric.nativex12.ParseResult;

String serial = "YOUR_SERIAL_KEY";
EdiFabricX12.loadLibrary();
EdiFabricX12.setSerial(serial);
EdiFabricX12.setMap("{\"default\":\"" + serial + "\",\"maps\":{}}");

String edi = Files.readString(Path.of("ShipNotice.txt"));
ParseResult result = EdiFabricX12.parse(edi, ParseMode.JSON_VALIDATE);
System.out.println(result.getTransactions());
System.out.println(result.getReport()); Java bindingsediFabric Native
#include "edifabric_x12.h"

const char *serial = "YOUR_SERIAL_KEY";
ef_parse_result result;

if (ef_load_library(NULL) != 0)
    return 1;
ef_set_serial(serial);
ef_set_map("{\"default\":\"YOUR_SERIAL_KEY\",\"maps\":{}}");

char *edi = read_file("ShipNotice.txt", NULL);   /* helper in example_all_functions.c */
if (ef_parse(edi, EF_PARSE_JSON_VALIDATE, NULL, &result) == 0) {
    /* transactions = output[0 .. offset), report = output[offset .. length) */
    fwrite(result.output.data, 1, (size_t)result.output.length, stdout);
    ef_free(result.output.data);
} C bindingsediFabric Native
curl -X POST 'https://api.edination.com/v2/x12/read' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SERIAL_KEY' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@ShipNotice.txt' TranslateValidateediFabric Cloud

Generate an 856 file

Populate a TS856 object in .NET, or pass JSON in the shape shown above to ediFabric Native or ediFabric Cloud, and get a valid 856 file back.

.NET
Python
Java
C
Cloud

using EdiFabric.Templates.X12004010;

License.SetSerial("YOUR_SERIAL_KEY");

var transaction = new TS856();

//  856 is the Transaction Set Identifier Code for the Advance Ship Notice
//  0001 is the Transaction Set Control Number
transaction.ST = new ST();
transaction.ST.TransactionSetIdentifierCode_01 = "856";
transaction.ST.TransactionSetControlNumber_02 = "0001";

//  00 is the Transaction Set Purpose Code "00" indicates Original.
//  01140824 is the Shipment Identification Number.
//  20051015 is the Document Creation Date.
//  1345 is the Time.
//  0001 is the Hierarchical Structure. "0001" indicates "Pick and Pack Structure". 
transaction.BSN = new BSN();
transaction.BSN.TransactionSetPurposeCode_01 = "00";
transaction.BSN.ShipmentIdentification_02 = "01140824";
transaction.BSN.Date_03 = "20051015";
transaction.BSN.Time_04 = "1345";
transaction.BSN.HierarchicalStructureCode_05 = "0001";

//  Repeating HL Loops
transaction.HLLoop = new List<Loop_HL_856>();

// ... set the remaining loops and segments the same way

// SegmentBuilders is in the Common project of the example repository
using (var stream = new MemoryStream())
{
    using (var writer = new X12Writer(stream))
    {
        writer.Write(SegmentBuilders.BuildIsa("1"));
        writer.Write(SegmentBuilders.BuildGs("1"));
        writer.Write(transaction);
    }
    Console.WriteLine(Encoding.UTF8.GetString(stream.ToArray()));
} Install and get started Full 856 build methodExample repository
import json
import edifabric_x12 as ef

serial = "YOUR_SERIAL_KEY"
ef.load_library()
ef.set_serial(serial)
ef.set_map(json.dumps({"default": serial, "maps": {}}))

# the transactions JSON returned by ef.parse, edited or produced by your application
transactions = open("ShipNotice.json", "rb").read()
edi = ef.build(transactions, postfix="\r\n")
print(edi) Python bindings
import com.edifabric.nativex12.EdiFabricX12;

String serial = "YOUR_SERIAL_KEY";
EdiFabricX12.loadLibrary();
EdiFabricX12.setSerial(serial);
EdiFabricX12.setMap("{\"default\":\"" + serial + "\",\"maps\":{}}");

// the transactions JSON returned by parse, edited or produced by your application
String transactions = Files.readString(Path.of("ShipNotice.json"));
String edi = EdiFabricX12.build(transactions, "\r\n");
System.out.println(edi); Java bindings
#include "edifabric_x12.h"

ef_buffer edi;

if (ef_load_library(NULL) != 0)
    return 1;
ef_set_serial("YOUR_SERIAL_KEY");
ef_set_map("{\"default\":\"YOUR_SERIAL_KEY\",\"maps\":{}}");

/* the transactions JSON returned by ef_parse, edited or produced by your application */
char *transactions = read_file("ShipNotice.json", NULL);
if (ef_build(transactions, "\r\n", &edi) == 0) {
    fwrite(edi.data, 1, (size_t)edi.length, stdout);
    ef_free(edi.data);
} C bindings
# the JSON returned by /read, edited or produced by your application
curl -X POST 'https://api.edination.com/v2/x12/write' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SERIAL_KEY' \
-H 'Content-Type: application/json' \
--data-binary '@ShipNotice.json' \
-o 'ShipNotice.txt' How-tosediFabric Cloud

856 questions

What is the HL structure of an 856?

HL03 gives each level: S shipment, O order, T tare, P pack, I item. Retailers usually require either S-O-P-I (pick and pack) or S-O-T-P-I with pallets.

When should the 856 be sent?

After the goods leave and before they arrive. Most retailers require it within a set time of shipment and charge back late or inaccurate ASNs.

What is the EDIFACT equivalent?

DESADV, the despatch advice message.

How do I parse and generate X12 856 files in .NET, Python, Java and C?

In .NET, install EdiFabric and EdiFabric.Templates.X12, read the file with X12Reader into TS856 objects and write them back with X12Writer. From Python, Java or C, use ediFabric Native, which converts 856 files to JSON and JSON back to X12 inside your process. From any other language, post the file to the ediFabric Cloud REST API.

Related transactions

X12 850 - Purchase Order
X12 810 - Invoice
X12 861 - Receiving Advice/Acceptance Certificate
EANCOM DESADV - Despatch Advice
All EDI transactions →

X12 856 Ship Notice/Manifest (ASN)

At a glance