X12 810 invoice: format and example

810 structure

The full X12 810 layout from its OpenEDI definition, the same model ediFabric uses to parse, validate and generate it: 15 loops and 90 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
`BIG`	Beginning Segment for Invoice	Mandatory	1
`NTE`	Note/Special Instruction	Optional	100
`CUR`	Currency	Optional	1
`REF`	Reference Identification	Optional	12
`YNQ`	Yes/No Question	Optional	10
`PER`	Administrative Communications Contact	Optional	3
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
`DMG`	Demographic Information	Optional	1
`ITD`	Terms of Sale/Deferred Terms of Sale	Optional	>1
`DTM`	Date/Time Reference	Optional	10
`FOB`	F.O.B. Related Instructions	Optional	1
`PID`	Product/Item Description	Optional	200
`MEA`	Measurements	Optional	40
`PWK`	Paperwork	Optional	25
`PKG`	Marking, Packaging, Loading	Optional	25
`L7`	Tariff Reference	Optional	1
`BAL`	Balance Detail	Optional	>1
`INC`	Installment Information	Optional	1
`PAM`	Period Amount	Optional	>1
LM loop	Code Source Information	Optional	10
`LM`	Code Source Information	Mandatory	1
`LQ`	Industry Code	Mandatory	100
N9 loop	Reference Identification	Optional	1
`N9`	Reference Identification	Mandatory	1
`MSG`	Message Text	Mandatory	10
V1 loop	Vessel Identification	Optional	>1
`V1`	Vessel Identification	Mandatory	1
`R4`	Port or Terminal	Optional	>1
`DTM`	Date/Time Reference	Optional	>1
FA1 loop	Type of Financial Accounting Data	Optional	>1
`FA1`	Type of Financial Accounting Data	Mandatory	1
`FA2`	Accounting Data	Mandatory	>1
IT1 loop	Baseline Item Data (Invoice)	Optional	200000
`IT1`	Baseline Item Data (Invoice)	Mandatory	1
`CRC`	Conditions Indicator	Optional	1
`QTY`	Quantity	Optional	5
`CUR`	Currency	Optional	1
`IT3`	Additional Item Data	Optional	5
`TXI`	Tax Information	Optional	10
`CTP`	Pricing Information	Optional	25
`PAM`	Period Amount	Optional	10
`MEA`	Measurements	Optional	40
PID loop	Product/Item Description	Optional	1000
`PID`	Product/Item Description	Mandatory	1
`MEA`	Measurements	Optional	10
`PWK`	Paperwork	Optional	25
`PKG`	Marking, Packaging, Loading	Optional	25
`PO4`	Item Physical Details	Optional	1
`ITD`	Terms of Sale/Deferred Terms of Sale	Optional	2
`REF`	Reference Identification	Optional	>1
`YNQ`	Yes/No Question	Optional	10
`PER`	Administrative Communications Contact	Optional	5
`SDQ`	Destination Quantity	Optional	500
`DTM`	Date/Time Reference	Optional	10
`CAD`	Carrier Detail	Optional	>1
`L7`	Tariff Reference	Optional	>1
`SR`	Requested Service Schedule	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
SLN loop	Subline Item Detail	Optional	1000
`SLN`	Subline Item Detail	Mandatory	1
`DTM`	Date/Time Reference	Optional	1
`REF`	Reference Identification	Optional	>1
`PID`	Product/Item Description	Optional	1000
`SAC`	Service, Promotion, Allowance, or Charge Information	Optional	25
`TC2`	Commodity	Optional	2
`TXI`	Tax Information	Optional	10
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
`DMG`	Demographic Information	Optional	1
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
FA1 loop	Type of Financial Accounting Data	Optional	>1
`FA1`	Type of Financial Accounting Data	Mandatory	1
`FA2`	Accounting Data	Mandatory	>1
`TDS`	Total Monetary Value Summary	Mandatory	1
`TXI`	Tax Information	Optional	10
`CAD`	Carrier Detail	Optional	1
`AMT`	Monetary Amount	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
ISS loop	Invoice Shipment Summary	Optional	>1
`ISS`	Invoice Shipment Summary	Mandatory	1
`PID`	Product/Item Description	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 810 file

An invoice for one line item. Paste it into EdiNation to see every element named and validated.

ISA*00*          *00*          *16*SENDER1        *1B*RECEIVER1      *071216*1406*U*00204*000000263*1*T*>~
GS*IN*SENDER1*RECEIVER1*20071216*1406*000000001*X*004010~
ST*810*0001~
BIG*20000513*SG427254*20000506*508517*1001~
N1*ST*ABC AEROSPACE CORPORATION*9*123456789-0101~
N3*1000 BOARDWALK DRIVE~
N4*SOMEWHERE*CA*98898~
ITD*05*3*****30*******E~
IT1*1*48*EA*3**MG*R5656-2~
TDS*14400~
CTT*1~
SE*10*0001~
GE*1*000000001~
IEA*1*000000263~

The same 810 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": "810",
    "TransactionSetControlNumber_02": "0001"
  },
  "BIG": {
    "Date_01": "20000513",
    "InvoiceNumber_02": "SG427254",
    "Date_03": "20000506",
    "PurchaseOrderNumber_04": "508517",
    "ReleaseNumber_05": "1001"
  },
  "N1Loop": [
    {
      "N1": {
        "EntityIdentifierCode_01": "ST",
        "Name_02": "ABC AEROSPACE CORPORATION",
        "IdentificationCodeQualifier_03": "9",
        "IdentificationCode_04": "123456789-0101"
      },
      "N3": [
        {
          "AddressInformation_01": "1000 BOARDWALK DRIVE"
        }
      ],
      "N4": {
        "CityName_01": "SOMEWHERE",
        "StateorProvinceCode_02": "CA",
        "PostalCode_03": "98898"
      }
    }
  ],
  "ITD": [
    {
      "TermsTypeCode_01": "05",
      "TermsBasisDateCode_02": "3",
      "TermsNetDays_07": "30",
      "PaymentMethodCode_14": "E"
    }
  ],
  "IT1Loop": [
    {
      "IT1": {
        "AssignedIdentification_01": "1",
        "QuantityInvoiced_02": "48",
        "UnitorBasisforMeasurementCode_03": "EA",
        "UnitPrice_04": "3",
        "ProductServiceIDQualifier_06": "MG",
        "ProductServiceID_07": "R5656-2"
      }
    }
  ],
  "TDS": {
    "Amount_01": "14400"
  },
  "CTT": {
    "NumberofLineItems_01": "1"
  },
  "SE": {
    "NumberofIncludedSegments_01": "10",
    "TransactionSetControlNumber_02": "0001"
  }
}

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

Generate an 810 file

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

.NET
Python
Java
C
Cloud

using EdiFabric.Templates.X12004010;

License.SetSerial("YOUR_SERIAL_KEY");

var transaction = new TS810();

//  Indicates the start of an invoice transaction set and assigns a control number.
transaction.ST = new ST();
transaction.ST.TransactionSetIdentifierCode_01 = "810";
transaction.ST.TransactionSetControlNumber_02 = "0001";

//  Indicates the invoice was created on May 13, 2000 and assigned invoice number SG427254. 
//  The invoice is in response to a purchase order sent on May 6, 2000 with purchase order number 508517 and release number 1001.
transaction.BIG = new BIG();
transaction.BIG.Date_01 = "20000513";
transaction.BIG.InvoiceNumber_02 = "SG427254";
transaction.BIG.Date_03 = "20000506";
transaction.BIG.PurchaseOrderNumber_04 = "508517";
transaction.BIG.ReleaseNumber_05 = "1001";

//  Repeating N1 Loops
transaction.N1Loop = new List<Loop_N1_810>();

//  Begin N1 Loop
var n1Loop = new Loop_N1_810();

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

810 questions

Why is the TDS amount missing a decimal point?

TDS01 is an N2 field with two implied decimals. TDS*90000 means 900.00.

How is an 810 matched to the order?

BIG04 carries the buyer's purchase order number. Line items repeat the product identifiers from the 850, and the 856 ship notice can be referenced too.

What happens when the buyer rejects an invoice?

The buyer can send an 824 application advice with the errors. Accepted invoices are paid, sometimes with an 820 remittance advice.

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

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

X12 810 Invoice

At a glance