---
source: https://carbone.io/examples/edi-856-advance-ship-notice/
title: "EDI 856 ASN Generator: X12 Ship Notices from JSON | Carbone"
description: "Generate EDI 856 advance ship notices from WMS or ERP data with the Carbone API: a TXT template writes the X12 file, HL hierarchy and segment counts included."
generated_at: "2026-11-17"
---

# EDI 856 ship notice

Cartons and products from your WMS, as an X12 file

[![EDI 856 ship notice: TXT generated from a TXT template and JSON data](/examples/edi-856-advance-ship-notice/thumb-result.webp)](/examples/edi-856-advance-ship-notice/result.txt "Download the generated document")

[Download template](/examples/edi-856-advance-ship-notice/template.txt)

[Sample data](/examples/edi-856-advance-ship-notice/data.json)

[Download the generated EDI](/examples/edi-856-advance-ship-notice/result.txt)

- **Template:** TXT
- **Export as:** TXT, PDF, DOCX, ODT, HTML
- **Carbone:** 5.4+

Features

-   [Loop](/documentation/design/repetitions/with-arrays.md)
-   [Nested array](/documentation/design/repetitions/with-arrays.md)
-   [Aggregation](/documentation/design/computation/aggregation.md)
-   [Set](/documentation/design/computation/store-and-transform.md)
-   Index
-   Padding
-   [Alias](/documentation/design/substitutions/aliases.md)
-   [Math](/documentation/design/computation/simple-mathematics.md)

## 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](https://x12.org/) 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](/examples/ucc-128-carton-label-zpl/index.md), which labels the 2 cartons of this shipment, with the same mark-for store.

## EDI 856 example

### Template

```text
{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

```json
{
  "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

```text
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](/documentation/design/template-formats/txt.md#fixed-width-files).
-   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:

```text
{#x12($text) = $text:unaccent:upperCase:replace('*', ' '):replace('~', ' '):replace('>', ' ')}
```

`{$x12(d.shipFrom.name)}` prints `FABRIKAM OUTDOOR SUPPLY`. Learn more about [parametrized aliases](/documentation/design/substitutions/aliases.md#parametrized-alias).

### 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](/documentation/design/repetitions/with-arrays.md#nested-arrays). Carbone numbers the `HL` segments:

-   `{d.cartons[].items:len:set(.itemCount)}` adds the number of products to each carton, with [`:set`](/documentation/design/computation/store-and-transform.md#modify-json-set-relativepath).
-   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](/documentation/design/computation/aggregation.md#cumsum-partitionby) and the [loop index](/documentation/design/repetitions/with-arrays.md#access-the-loop-iterator-value).

### 4\. Count the segments

The retailer rejects a file whose counts do not match. Carbone computes them from the cartons with [aggregators](/documentation/design/computation/aggregation.md):

-   `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](/documentation/design/conditions/conditional-blocks.md#showbegin-showend), 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.

## Related Examples

- [EDIFACT invoice](/examples/edifact-invoice/index.md): TXT template to EDI.
- [NACHA ACH file](/examples/nacha-ach-file/index.md): TXT template to ACH.
- [SSCC carton label](/examples/label-barcode/index.md): DOCX template to PDF.

## Related topics

- [CMR consignment note](/examples/cmr-consignment-note/index.md)
- [GS1 pallet label](/examples/gs1-pallet-label-zpl/index.md)
- [UCC-128 carton label](/examples/ucc-128-carton-label-zpl/index.md)
- [Warehouse floor plan heat map](/examples/warehouse-floor-plan-heatmap/index.md)
- [SSCC carton label](/examples/label-barcode/index.md)
- [Inventory count sheets](/examples/stock-inventory-spreadsheet/index.md)
