EDI 856 ship notice

Cartons and products from your WMS, as an X12 file

Download template

Sample data

Template
TXT
Export as
TXT, PDF, DOCX, ODT, HTML
Carbone
5.4+
Features

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

  • ISA has fixed widths, so it is always 106 characters long. {d.envelope.senderId:padr(15)} adds spaces after FABRIKAM up to 15 characters, and {d.envelope.interchangeNumber:padl(9, '0')} prints 000104417. See the fixed-width formatters.
  • Each control number is printed again in its trailer: 000104417 in ISA and IEA, 3218 in GS and GE, 0001 in ST and SE. GE*1 and IEA*1 count one transaction set and one group.
  • {o.timezone=America/New_York} prints the dates and times in New York time: 261112*1435.
  • P in ISA marks a production file: write T for 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)}. :cumSum adds up the HL segments of the cartons so far, one pack plus its products. Plus the shipment and the order, minus the products of this carton, it gives 3, then 6.
  • Item: {d.cartons[i].items[i].upc:cumCount:add(.i):add(3)}. :cumCount numbers the products across the cartons, and .i is 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} prints 2 cartons, and {d.cartons[].weight:aggSum:round(1)} the gross weight, 60.1 pounds.
  • CTT: the number of HL segments, 2 plus one per carton and one per product. {d.cartons[].itemCount:add(1):aggSum:add(2)} prints 7.
  • SE: the number of segments from ST to SE. 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)} prints 31, 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*Z7 is a conditional block, from {d.order.markFor.storeNumber:ifNEM:showBegin} to :showEnd, so an order without a mark-for store has no N1*Z7. On the first line, {d.order.markFor.storeNumber:ifNEM:show(1):elseShow(0):set(c.markForCount)} stores the 1 or 0 that SE adds.

Trusted by 800+ paid customers in 40+ countries

Finance
Healthcare
Insurance
Legal
Public
Retail
Energy
Software
Telecom
Dior
Thales
Younited
Danfoss
CMA CGM
Illumina
KparK
Scalingo
French Ministry of the Armed Forces
BMW
Telus
Bestseller
Flagship Biosciences
Insly
Ninox
Sodexo