EDI 856 ship notice
Cartons and products from your WMS, as an X12 file
- Template
- TXT
- Export as
- TXT, PDF, DOCX, ODT, HTML
- Carbone
- 5.4+
- Loop
- Nested array
- Aggregation
- Set
- Index
- Padding
- Alias
- Math
Generate EDI 856 advance ship notices from your software
Retailers ask their suppliers for an advance ship notice (ASN) with each shipment, in the 856 transaction set of the ASC X12 standard, and set its rules in their routing guide. The ASN reaches the distribution center before the truck and lists each carton by its SSCC and each product by its UPC, so the dock matches the cartons to the purchase order without opening them. Your WMS or ERP sends the shipment to the Carbone API as JSON and gets back the 856 file, ready for your EDI provider or AS2 connection. In this example, Fabrikam Outdoor Supply ships 2 cartons and 3 products to distribution center 6094 of Contoso Retail, marked for store 1187, in X12 version 4010.
856 file structure
Each line is a segment: an ID, then data elements separated by *, then the terminator ~. The HL segments build the hierarchy in Shipment, Order, Pack, Item order (SOPI): each HL has a number, the number of its parent and a level code.
| Segments | Level | Role |
|---|---|---|
ISA and IEA |
Interchange | Envelope: sender and receiver IDs, date, control number. ISA has fixed widths: 106 characters |
GS and GE |
Group | Group of ship notices SH, version 004010, group control number |
ST and SE |
Transaction | Start and end of the 856, with its segment count |
BSN, DTM |
Header | Shipment ID, creation date and time, ship date 011 |
HL (S), TD1, TD5, REF, N1, N3, N4 |
Shipment | Carton count and weight, carrier SCAC, bill of lading, ship-to ST and ship-from SF addresses |
HL (O), PRF, N1 |
Order | Purchase order number and date, and the mark-for store Z7 when the order goes to a store through the distribution center |
HL (P), MAN |
Pack | One per carton: the SSCC of its shipping label |
HL (I), LIN, SN1 |
Item | One per product in the carton: UPC, vendor item number, quantity shipped |
CTT |
Summary | Number of HL segments |
The SSCC in MAN*GM follows the application identifier 00, as on the barcode of the label: see how to print it in the UCC-128 carton label example, which labels the 2 cartons of this shipment, with the same mark-for store.
EDI 856 example
Template
{o.timezone=America/New_York}{#x12($text) = $text:unaccent:upperCase:replace('*', ' '):replace('~', ' '):replace('>', ' ')}{d.cartons[].items:len:set(.itemCount)}{d.order.markFor.storeNumber:ifNEM:show(1):elseShow(0):set(c.markForCount)}ISA*00* *00* *ZZ*{d.envelope.senderId:padr(15)}*ZZ*{d.envelope.receiverId:padr(15)}*{d.envelope.createdAt:formatD('YYMMDD*HHmm')}*U*00401*{d.envelope.interchangeNumber:padl(9, '0')}*0*P*>~
GS*SH*{d.envelope.senderId}*{d.envelope.receiverId}*{d.envelope.createdAt:formatD('YYYYMMDD*HHmm')}*{d.envelope.groupNumber}*X*004010~
ST*856*{d.envelope.transactionNumber:padl(4, '0')}~
BSN*00*{d.shipment.id}*{d.envelope.createdAt:formatD('YYYYMMDD*HHmm')}*0001~
DTM*011*{d.shipment.shipDate:formatD('YYYYMMDD')}~
HL*1**S~
TD1*CTN25*{d.cartons:len}****G*{d.cartons[].weight:aggSum:round(1)}*LB~
TD5*B*2*{d.shipment.carrierScac}*M~
REF*BM*{d.shipment.billOfLading}~
N1*ST*{$x12(d.shipTo.name)}*92*{d.shipTo.dcNumber}~
N3*{$x12(d.shipTo.street)}~
N4*{$x12(d.shipTo.city)}*{d.shipTo.state}*{d.shipTo.zip}*{d.shipTo.country}~
N1*SF*{$x12(d.shipFrom.name)}*UL*{d.shipFrom.gln}~
N3*{$x12(d.shipFrom.street)}~
N4*{$x12(d.shipFrom.city)}*{d.shipFrom.state}*{d.shipFrom.zip}*{d.shipFrom.country}~
HL*2*1*O~
PRF*{d.order.poNumber}***{d.order.poDate:formatD('YYYYMMDD')}~{d.order.markFor.storeNumber:ifNEM:showBegin}
N1*Z7*{$x12(d.order.markFor.name)}*92*{d.order.markFor.storeNumber}~{d.order.markFor.storeNumber:showEnd}
{d.cartons[i]}HL*{d.cartons[i].itemCount:add(1):cumSum:add(2):sub(.itemCount)}*2*P~
MAN*GM*00{d.cartons[i].sscc}~
{d.cartons[i].items[i]}HL*{d.cartons[i].items[i].upc:cumCount:add(.i):add(3)}*{d.cartons[i].items[i].upc:cumCount:add(.i):add(2):sub(..i)}*I~
LIN**UP*{d.cartons[i].items[i].upc}*VN*{d.cartons[i].items[i].vendorItem}~
SN1**{d.cartons[i].items[i].qty}*{d.cartons[i].items[i].unit}~
{d.cartons[i].items[i+1]}{d.cartons[i+1]}CTT*{d.cartons[].itemCount:add(1):aggSum:add(2)}~
SE*{d.cartons[].itemCount:mul(3):add(2):aggSum:add(17):add(c.markForCount)}*{d.envelope.transactionNumber:padl(4, '0')}~
GE*1*{d.envelope.groupNumber}~
IEA*1*{d.envelope.interchangeNumber:padl(9, '0')}~
JSON data
{
"envelope": { "senderId": "FABRIKAM", "receiverId": "CONTOSORETAIL", "interchangeNumber": 104417, "groupNumber": 3218, "transactionNumber": 1, "createdAt": "2026-11-12T14:35:00-05:00" },
"shipment": { "id": "SHP104417", "shipDate": "2026-11-12", "carrierScac": "NWFX", "billOfLading": "08627140010441701" },
"shipTo": { "name": "Contoso Retail DC 6094", "dcNumber": "6094", "street": "1200 Distribution Blvd", "city": "Columbus", "state": "OH", "zip": "43217", "country": "US" },
"shipFrom": { "name": "Fabrikam Outdoor Supply", "gln": "0862714000017", "street": "4800 Cascade Commerce Way", "city": "Reno", "state": "NV", "zip": "89523", "country": "US" },
"order": { "poNumber": "4500217784", "poDate": "2026-11-02", "markFor": { "name": "Contoso Retail Easton", "storeNumber": "1187" } },
"cartons": [
{
"sscc": "008627140000045018",
"weight": 38.4,
"items": [
{ "upc": "862714001014", "vendorItem": "FB-TT2-GRN", "qty": 4, "unit": "EA" },
{ "upc": "862714002059", "vendorItem": "FB-DSB-20F", "qty": 6, "unit": "EA" }
]
},
{
"sscc": "008627140000045025",
"weight": 21.7,
"items": [
{ "upc": "862714003124", "vendorItem": "FB-CS1-BLK", "qty": 12, "unit": "EA" }
]
}
]
}
Generated 856 file
ISA*00* *00* *ZZ*FABRIKAM *ZZ*CONTOSORETAIL *261112*1435*U*00401*000104417*0*P*>~
GS*SH*FABRIKAM*CONTOSORETAIL*20261112*1435*3218*X*004010~
ST*856*0001~
BSN*00*SHP104417*20261112*1435*0001~
DTM*011*20261112~
HL*1**S~
TD1*CTN25*2****G*60.1*LB~
TD5*B*2*NWFX*M~
REF*BM*08627140010441701~
N1*ST*CONTOSO RETAIL DC 6094*92*6094~
N3*1200 DISTRIBUTION BLVD~
N4*COLUMBUS*OH*43217*US~
N1*SF*FABRIKAM OUTDOOR SUPPLY*UL*0862714000017~
N3*4800 CASCADE COMMERCE WAY~
N4*RENO*NV*89523*US~
HL*2*1*O~
PRF*4500217784***20261102~
N1*Z7*CONTOSO RETAIL EASTON*92*1187~
HL*3*2*P~
MAN*GM*00008627140000045018~
HL*4*3*I~
LIN**UP*862714001014*VN*FB-TT2-GRN~
SN1**4*EA~
HL*5*3*I~
LIN**UP*862714002059*VN*FB-DSB-20F~
SN1**6*EA~
HL*6*2*P~
MAN*GM*00008627140000045025~
HL*7*6*I~
LIN**UP*862714003124*VN*FB-CS1-BLK~
SN1**12*EA~
CTT*7~
SE*31*0001~
GE*1*3218~
IEA*1*000104417~
How to create an EDI 856 file
1. Fill the envelope
ISAhas fixed widths, so it is always 106 characters long.{d.envelope.senderId:padr(15)}adds spaces afterFABRIKAMup to 15 characters, and{d.envelope.interchangeNumber:padl(9, '0')}prints000104417. See the fixed-width formatters.- Each control number is printed again in its trailer:
000104417inISAandIEA,3218inGSandGE,0001inSTandSE.GE*1andIEA*1count one transaction set and one group. {o.timezone=America/New_York}prints the dates and times in New York time:261112*1435.PinISAmarks a production file: writeTfor a test file. Partner wants a single line? Write the template on one line.
2. Clean the names and addresses
X12 4010 has no escape character: a *, ~ or > in a name would split the segment. The alias on the first line replaces them with spaces, removes the accents and writes capital letters, the basic character set of X12:
{#x12($text) = $text:unaccent:upperCase:replace('*', ' '):replace('~', ' '):replace('>', ' ')}
{$x12(d.shipFrom.name)} prints FABRIKAM OUTDOOR SUPPLY. Learn more about parametrized aliases.
3. Number the HL hierarchy
The shipment is HL*1, the order HL*2, then each carton and its products follow. {d.cartons[i]} repeats the pack level for each carton, and {d.cartons[i].items[i]} the item level for each product, as nested loops. Carbone numbers the HL segments:
{d.cartons[].items:len:set(.itemCount)}adds the number of products to each carton, with:set.- Pack:
{d.cartons[i].itemCount:add(1):cumSum:add(2):sub(.itemCount)}.:cumSumadds up theHLsegments of the cartons so far, one pack plus its products. Plus the shipment and the order, minus the products of this carton, it gives3, then6. - Item:
{d.cartons[i].items[i].upc:cumCount:add(.i):add(3)}.:cumCountnumbers the products across the cartons, and.iis the position of the carton, from 0. The third product is in the second carton: 3 + 1 + 3 =7. - Parent of an item:
{d.cartons[i].items[i].upc:cumCount:add(.i):add(2):sub(..i)}, the number of the item minus 1, minus its position in the carton..i:HL*7*6*I.
See cumulative aggregators and the loop index.
4. Count the segments
The retailer rejects a file whose counts do not match. Carbone computes them from the cartons with aggregators:
TD1:{d.cartons:len}prints2cartons, and{d.cartons[].weight:aggSum:round(1)}the gross weight,60.1pounds.CTT: the number ofHLsegments, 2 plus one per carton and one per product.{d.cartons[].itemCount:add(1):aggSum:add(2)}prints7.SE: the number of segments fromSTtoSE. 17 fixed ones, plus 2 per carton (HL,MAN), 3 per product (HL,LIN,SN1) and 1 for the mark-for store:{d.cartons[].itemCount:mul(3):add(2):aggSum:add(17):add(c.markForCount)}prints31, and stays right for any number of cartons. When you add a segment to the template, change:add(17),:add(2)for a segment per carton, or:mul(3)for a segment per product.N1*Z7is a conditional block, from{d.order.markFor.storeNumber:ifNEM:showBegin}to:showEnd, so an order without a mark-for store has noN1*Z7. On the first line,{d.order.markFor.storeNumber:ifNEM:show(1):elseShow(0):set(c.markForCount)}stores the 1 or 0 thatSEadds.
Related Examples
Trusted by 800+ paid customers in 40+ countries














