X12 857 shipment and billing notice: format and example

857 structure

The full X12 857 layout from its OpenEDI definition, the same model ediFabric uses to parse, validate and generate it: 16 loops and 67 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
`BHT`	Beginning of Hierarchical Transaction	Mandatory	1
HL loop	Hierarchical Level	Mandatory	>1
`HL`	Hierarchical Level	Mandatory	1
G05 loop	Total Shipment Information	Optional	1
`G05`	Total Shipment Information	Mandatory	1
`TD1`	Carrier Details (Quantity and Weight)	Optional	5
`TD3`	Carrier Details (Equipment)	Optional	5
`TD4`	Carrier Details (Special Handling, or Hazardous Materials, or Both)	Optional	5
`TD5`	Carrier Details (Routing Sequence/Transit Time)	Optional	10
`FOB`	F.O.B. Related Instructions	Optional	1
`DTM`	Date/Time Reference	Optional	5
`N9`	Reference Identification	Optional	20
`PER`	Administrative Communications Contact	Optional	5
`CUR`	Currency	Optional	1
N1 loop	Name	Optional	10
`N1`	Name	Mandatory	1
`N2`	Additional Name Information	Optional	2
`N3`	Address Information	Optional	2
`N4`	Geographic Location	Optional	1
LM loop	Code Source Information	Optional	>1
`LM`	Code Source Information	Mandatory	1
`LQ`	Industry Code	Mandatory	>1
TDS loop	Total Monetary Value Summary	Optional	1
`TDS`	Total Monetary Value Summary	Mandatory	1
`PRF`	Purchase Order Reference	Optional	1
`N9`	Reference Identification	Optional	>1
`DTM`	Date/Time Reference	Optional	10
`ITD`	Terms of Sale/Deferred Terms of Sale	Optional	5
`TXI`	Tax Information	Optional	10
`SN1`	Item Detail (Shipment)	Optional	1
`ISS`	Invoice Shipment Summary	Optional	1
SAC loop	Service, Promotion, Allowance, or Charge Information	Optional	25
`SAC`	Service, Promotion, Allowance, or Charge Information	Mandatory	1
`TXI`	Tax Information	Optional	10
N1 loop	Name	Optional	10
`N1`	Name	Mandatory	1
`N2`	Additional Name Information	Optional	2
`N3`	Address Information	Optional	2
`N4`	Geographic Location	Optional	1
FA1 loop	Type of Financial Accounting Data	Optional	>1
`FA1`	Type of Financial Accounting Data	Mandatory	1
`FA2`	Accounting Data	Mandatory	>1
PAL loop	Pallet Information	Optional	1
`PAL`	Pallet Information	Mandatory	1
`SN1`	Item Detail (Shipment)	Optional	1
`MAN`	Marks and Numbers	Optional	10
LX loop	Assigned Number	Optional	1
`LX`	Assigned Number	Mandatory	1
`N9`	Reference Identification	Optional	15
`SN1`	Item Detail (Shipment)	Optional	1
`PO4`	Item Physical Details	Optional	1
`MEA`	Measurements	Optional	10
`PKG`	Marking, Packaging, Loading	Optional	10
`MAN`	Marks and Numbers	Optional	10
IT1 loop	Baseline Item Data (Invoice)	Optional	1
`IT1`	Baseline Item Data (Invoice)	Mandatory	1
`IT3`	Additional Item Data	Optional	1
`PO4`	Item Physical Details	Optional	1
`TD4`	Carrier Details (Special Handling, or Hazardous Materials, or Both)	Optional	>1
`TC2`	Commodity	Optional	5
`TXI`	Tax Information	Optional	10
`CTP`	Pricing Information	Optional	10
`N9`	Reference Identification	Optional	10
`MEA`	Measurements	Optional	10
`DTM`	Date/Time Reference	Optional	10
`ITD`	Terms of Sale/Deferred Terms of Sale	Optional	>1
PID loop	Product/Item Description	Optional	25
`PID`	Product/Item Description	Mandatory	1
`MEA`	Measurements	Optional	10
SLN loop	Subline Item Detail	Optional	1000
`SLN`	Subline Item Detail	Mandatory	1
`PID`	Product/Item Description	Optional	25
SAC loop	Service, Promotion, Allowance, or Charge Information	Optional	25
`SAC`	Service, Promotion, Allowance, or Charge Information	Mandatory	1
`TXI`	Tax Information	Optional	10
LM loop	Code Source Information	Optional	>1
`LM`	Code Source Information	Mandatory	1
`LQ`	Industry Code	Mandatory	>1
FA1 loop	Type of Financial Accounting Data	Optional	>1
`FA1`	Type of Financial Accounting Data	Mandatory	1
`FA2`	Accounting Data	Mandatory	>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 857 file

A shipment and billing notice with its HL hierarchy. 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*857*000012103~
BHT*0001*00**980110~
HL*1**S~
G05*3*UN~
DTM*011*980110***19~
N1*SF**15*216793X~
N1*ST**15*6678157~
N1*BT**15*1135309~
N1*VN**15*2002450~
HL*2**O~
TDS*383750*383750*218736~
PRF*0123456789123**980106~
HL*3**P~
LX*1~
MAN*GM*00097800006400000012~
HL*4**I~
IT1*1*2*UN*8.4*PE*IB*0835201031~
CTP**SLP*10.5***DIS*.8~
HL*5**I~
IT1*2*1*UN*24*PE*IB*0835208338~
CTP**SLP*30***DIS*.8~
SE*21*000012103~
GE*2*000000001~
IEA*1*000000263~

The same 857 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": "857",
    "TransactionSetControlNumber_02": "000012103"
  },
  "BHT": {
    "HierarchicalStructureCode_01": "0001",
    "TransactionSetPurposeCode_02": "00",
    "Date_04": "980110"
  },
  "HLLoop": [
    {
      "HL": {
        "HierarchicalIDNumber_01": "1",
        "HierarchicalLevelCode_03": "S"
      },
      "G05Loop": {
        "G05": {
          "NumberofUnitsShipped_01": "3",
          "UnitorBasisforMeasurementCode_02": "UN"
        },
        "DTM": [
          {
            "DateTimeQualifier_01": "011",
            "Date_02": "980110",
            "DateTimePeriodFormatQualifier_05": "19"
          }
        ],
        "N1Loop": [
          {
            "N1": {
              "EntityIdentifierCode_01": "SF",
              "IdentificationCodeQualifier_03": "15",
              "IdentificationCode_04": "216793X"
            }
          },
          {
            "N1": {
              "EntityIdentifierCode_01": "ST",
              "IdentificationCodeQualifier_03": "15",
              "IdentificationCode_04": "6678157"
            }
          },
          {
            "N1": {
              "EntityIdentifierCode_01": "BT",
              "IdentificationCodeQualifier_03": "15",
              "IdentificationCode_04": "1135309"
            }
          },
          {
            "N1": {
              "EntityIdentifierCode_01": "VN",
              "IdentificationCodeQualifier_03": "15",
              "IdentificationCode_04": "2002450"
            }
          }
        ]
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "2",
        "HierarchicalLevelCode_03": "O"
      },
      "TDSLoop": {
        "TDS": {
          "Amount_01": "383750",
          "Amount_02": "383750",
          "Amount_03": "218736"
        },
        "PRF": {
          "PurchaseOrderNumber_01": "0123456789123",
          "ChangeOrderSequenceNumber_03": "980106"
        }
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "3",
        "HierarchicalLevelCode_03": "P"
      },
      "LXLoop": {
        "LX": {
          "AssignedNumber_01": "1"
        },
        "MAN": [
          {
            "MarksandNumbersQualifier_01": "GM",
            "MarksandNumbers_02": "00097800006400000012"
          }
        ]
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "4",
        "HierarchicalLevelCode_03": "I"
      },
      "IT1Loop": {
        "IT1": {
          "AssignedIdentification_01": "1",
          "QuantityInvoiced_02": "2",
          "UnitorBasisforMeasurementCode_03": "UN",
          "UnitPrice_04": "8.4",
          "BasisofUnitPriceCode_05": "PE",
          "ProductServiceIDQualifier_06": "IB",
          "ProductServiceID_07": "0835201031"
        },
        "CTP": [
          {
            "PriceIdentifierCode_02": "SLP",
            "UnitPrice_03": "10.5",
            "PriceMultiplierQualifier_06": "DIS",
            "Multiplier_07": ".8"
          }
        ]
      }
    },
    {
      "HL": {
        "HierarchicalIDNumber_01": "5",
        "HierarchicalLevelCode_03": "I"
      },
      "IT1Loop": {
        "IT1": {
          "AssignedIdentification_01": "2",
          "QuantityInvoiced_02": "1",
          "UnitorBasisforMeasurementCode_03": "UN",
          "UnitPrice_04": "24",
          "BasisofUnitPriceCode_05": "PE",
          "ProductServiceIDQualifier_06": "IB",
          "ProductServiceID_07": "0835208338"
        },
        "CTP": [
          {
            "PriceIdentifierCode_02": "SLP",
            "UnitPrice_03": "30",
            "PriceMultiplierQualifier_06": "DIS",
            "Multiplier_07": ".8"
          }
        ]
      }
    }
  ],
  "SE": {
    "NumberofIncludedSegments_01": "21",
    "TransactionSetControlNumber_02": "000012103"
  }
}

Parse and validate an 857 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\ShipBillNotice.txt"))
using (var reader = new X12Reader(stream, "EdiFabric.Templates.X12"))
{
    var items = await reader.ReadToEndAsync();
    foreach (var transaction in items.OfType<TS857>())
    {
        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 857 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("ShipBillNotice.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("ShipBillNotice.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("ShipBillNotice.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 '@ShipBillNotice.txt' TranslateValidateediFabric Cloud

Generate an 857 file

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

.NET
Python
Java
C
Cloud

using EdiFabric.Templates.X12004010;

License.SetSerial("YOUR_SERIAL_KEY");

var transaction = new TS857();

//  Transaction 857 
//  Set control number 12103
transaction.ST = new ST();
transaction.ST.TransactionSetIdentifierCode_01 = "857";
transaction.ST.TransactionSetControlNumber_02 = "0001";

//  Hierarchical structure code 0001 
//  Original transaction set
//  Ship date of 01 / 10 / 98
transaction.BHT = new BHT();
transaction.BHT.HierarchicalStructureCode_01 = "0001";
transaction.BHT.TransactionSetPurposeCode_02 = "00";
transaction.BHT.Date_04 = "980110";

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

//  Begin HL Loop 1
var hlLoop1 = new Loop_HL_857();

// ... 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 857 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("ShipBillNotice.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("ShipBillNotice.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("ShipBillNotice.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 '@ShipBillNotice.json' \
-o 'ShipBillNotice.txt' How-tosediFabric Cloud

857 questions

When is an 857 used instead of an 856 and 810?

When both partners agree to settle on shipment, for example in evaluated receipt or consignment arrangements, so one transaction replaces two.

Is the 857 widely supported?

Less than the 856 and 810. Check the trading partner's implementation guide before choosing it.

How is the hierarchy organized?

Like the 856, with HL loops for the shipment, the order and the items, plus billing amounts.

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

In .NET, install EdiFabric and EdiFabric.Templates.X12, read the file with X12Reader into TS857 objects and write them back with X12Writer. From Python, Java or C, use ediFabric Native, which converts 857 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 856 - Ship Notice/Manifest (ASN)
X12 810 - Invoice
All EDI transactions →

X12 857 Shipment and Billing Notice

At a glance