Freight Invoice EDI - JSON Specification

Summary

The EDI-flavored JSON for freight-invoice EDI, used as the Chain.io file type "chainioInvoiceEDI". A single "freight_invoice" object drives EDI 110 (Air Freight Details & Invoice), EDI 210 (Motor Carrier Freight Invoice), and EDI 310 (Freight Receipt & Invoice, ocean); the "invoice_category" field selects the transaction set. All values are emitted as strings and are pre-coded to X12 code lists (N1 entity codes, DTM date qualifiers, weight and payment qualifiers); a downstream EDI translation engine performs the X12 serialization, so any segment references are logical correspondence. This is a flattened, single-invoice, EDI-oriented projection and is distinct from the canonical Freight Invoice ("chainioInvoiceJSON"). The tables below list every field the adapter emits; most fields are omitted when the source data has no value.

Objects

Name	Description
Root	The top level document.
FreightInvoice	A single freight invoice. All values are strings. Fields listed as required make the adapter fail the invoice (no file is produced) when the source value is missing; several of them can be relaxed or tightened through the adapter configuration, as noted per field.
EntityName	A party keyed by X12 N1 entity code.
Port	A port reference (X12 DTM date qualifiers).
ShipmentLeg	A transport leg.
LegCarrier	The carrier of a shipment leg.
ContainerGroup	The count of containers of one size.
PurchaseOrder	A purchase order linked to the service invoice.
AssignedGroup	A container grouping.
Container	A container on the shipment.
PackageDetail	A package group's dimensions and weight.
ContainerInvoiceLine	A charge line (X12 L1).
DateCollection	Shipment milestone datetimes (ISO 8601). A milestone the shipment has no value for is null or absent.
UnlocodeCollection	Flattened port UN/LOCODEs and descriptions. A key is present only when the shipment has that value.
PackedItem	A package group (used by "packed_items" and by "commodity_pack").
PackageContainer	A container a package group is packed in.
ContainerCharge	An invoice line apportioned to one container.
CommodityGroup	Package groups that share a commodity type.
ReferenceNumber	A coded reference number (X12 REF style).
CommercialInvoice	A commercial invoice.
CommercialInvoiceLine	A commercial invoice line.
Manufacturer	A manufacturer party.
BillOfLading	A bill of lading.
CustomsDeclaration	A customs declaration. Dates are YYYYMMDD.

Root top

Name	Data Type	Description	Required
`freight_invoice`	FreightInvoice	The single freight invoice object.	YES

FreightInvoice top

Name	Data Type	Description	Required
`all_charge_codes_from_source`	String	Every charge code on the source service invoice, pipe-delimited with a leading and trailing pipe (e.g. "\|FRT\|FSC\|"), including lines the configuration omits.
`asap_number`	String	When the shipment purchase order numbers contain "ASAP#", the text after it. Optional unless configured as required.
`assigned_group`	AssignedGroup	Container grouping with per-container detail.
`bill_to_organization`	String	The bill-to organization id from the service invoice. Required unless the adapter is configured to make it optional.
`bills_of_lading`	Array<BillOfLading>	The shipment bills of lading. Empty when the shipment has none.
`booking_reference`	String	The shipment booking reference.
`carrier_scac`	String	Carrier SCAC. Optional unless configured as required.
`comma_split_shipper_reference`	Array<String>	"shipper_reference" split on commas and trimmed.
`commercial_invoices`	Array<CommercialInvoice>	Commercial invoice loop with commercial invoice lines.
`commodity_groups`	Array<CommodityGroup>	Package groups grouped by commodity type.
`company_code`	String	The forwarder controlling company code.
`concatenated_order_numbers`	String	The shipment purchase order numbers joined with ", "; present only when the shipment has purchase orders.
`consolidation_details`	Object	Every property of the canonical consolidation the shipment belongs to, copied as-is (for example "shipper_reference"). Empty when there is no consolidation.
`container_count`	String	The number of containers on the shipment. Always present ("0" when there are none).
`container_details`	Array<ContainerGroup>	Containers grouped by size code.
`container_invoice_lines`	Array<ContainerInvoiceLine>	Charge lines (X12 L1), grouped by mapped charge code unless configured otherwise.
`containerization_type`	String	LSE / FCL / LCL. Required unless the adapter is configured to make it optional.
`converted_invoice_currency`	String	The currency of "converted_net_amount_due".
`converted_net_amount_due`	String	The total due converted to another currency.
`customer_reference`	String	The service invoice customer reference.
`customs_declarations`	Array<CustomsDeclaration>	Customs declaration loop.
`date_collection`	DateCollection	Shipment milestone datetimes.
`delivery_detention_billable_days`	String	The number of billable delivery detention days.
`delivery_distance`	String	The delivery distance, converted from kilometers to the unit in "delivery_distance_original_uom" when one is set.
`delivery_distance_original_uom`	String	The source unit of the delivery distance.
`delivery_mode`	String	The delivery mode (e.g. CY/CY).
`description_of_goods`	String	The shipment goods description.
`entity_names`	Array<EntityName>	Party loop keyed by X12 N1 entity code.
`flow_execution_uuid`	String	The Chain.io flow execution id that produced the file.
`forwarder_controlling_department_code`	String	The forwarder controlling department code.
`forwarder_controlling_department_description`	String	The forwarder controlling department description.
`freight_payment_terms`	String	Freight terms (e.g. PPD = prepaid, CC = collect). Optional unless configured as required.
`gross_weight_original_uom`	String	The source unit of the shipment gross weight.
`hmf`	String	Harbor Maintenance Fee: the amount of the customs declaration fee with code 501.
`house_bill`	String	House bill of lading. See "master_bill".
`imo_number`	String	The vessel Lloyds / IMO number.
`inco_terms`	String	Incoterms (e.g. DAT, DAP). Required unless the adapter is configured to make it optional.
`invoice_category`	String	Selects the EDI transaction set: 110, 210 or 310.
`invoice_charges_type`	String	How the charge lines compare to their linked cost lines: passthrough (lines are billed at cost and none above it), profit (lines are billed above cost and none at it) or mixed (both, or neither).
`invoice_currency`	String	The invoice currency.
`invoice_date`	String	The invoice issued date in YYYYMMDD. Required.	YES
`invoice_line_sum_amount`	String	The sum of the invoice line amounts, rounded to 2 decimal places.
`invoice_number`	String	The service invoice number. Required. When the adapter is configured to strip the invoice number suffix, anything from the first "/" onward is removed.	YES
`invoice_payment_term_days`	String	The service invoice payment terms in days.
`invoice_payment_terms`	String	The service invoice payment terms code.
`master_bill`	String	Master bill of lading. At least one of "master_bill" or "house_bill" is required unless the adapter is configured to make both optional; either can also be configured as individually required.
`method_of_payment`	String	The payment method code set in the adapter configuration; the same value on every invoice.
`mode`	String	The transport mode (AIR, SEA, etc.). Descriptive only: the transaction set is chosen by "invoice_category", not by "mode", so a mode may accompany any category — the example pairs "AIR" with the ocean 310 category.
`mpf`	String	Merchandise Processing Fee: the amount of the customs declaration fee with code 499.
`native_references`	Array<ReferenceNumber>	Coded references (X12 REF style). Only references with a value and a code or description are included.
`net_amount_due`	String	The service invoice total due. Required.	YES
`number_of_billable_storage_days`	String	The number of billable storage days.
`number_of_outer_packs`	String	The number of outer packs.
`number_of_packages`	String	Total package count. Required unless the adapter is configured to make it optional.
`outer_pack_package_type_code`	String	The outer pack package type code.
`package_details`	Array<PackageDetail>	Package group dimensions and weights.
`package_type_code`	String	Package type code.
`packages_chargeable_weight`	String	The chargeable weight in its source unit. Optional unless the adapter is configured to require chargeable weight.
`packages_chargeable_weight_kgs`	String	The chargeable weight in kilograms. Optional unless the adapter is configured to require chargeable weight.
`packages_chargeable_weight_uom`	String	The source unit of the chargeable weight.
`packages_gross_weight_kgs`	String	The shipment gross weight. Required. Despite the name, the value is converted from kilograms to the unit in "gross_weight_original_uom" when one is set.	YES
`packed_items`	Array<PackedItem>	One entry per package group, with the containers it is packed in.
`pickup_actual`	String	The actual pickup date in YYYYMMDD. Optional unless the adapter is configured to require it.
`pickup_distance`	String	The pickup distance, converted from kilometers to the unit in "pickup_distance_original_uom" when one is set.
`pickup_distance_original_uom`	String	The source unit of the pickup distance.
`ports`	Array<Port>	Port loop: origin, destination, final port and receipt, in that order.
`project_reference`	String	The shipment project reference.
`purchase_orders`	Array<PurchaseOrder>	The purchase orders linked to the service invoice.
`reference_number`	String	The forwarder reference.
`release_type`	String	The bill of lading release type. Optional unless configured as required.
`service_level`	String	The shipment service level, translated through the configured service level mappings when any are set.
`shipment_legs`	Array<ShipmentLeg>	The shipment transport legs. Empty when the shipment has none.
`shipment_po_number`	String	The shipment PO number.
`shipper_reference`	String	Shipper reference. Optional unless configured as required.
`storage_rate_original_uom`	String	The unit of the storage rate.
`storage_rate_per_day`	String	The storage rate per day.
`total_packages_quantities`	String	The sum of the package group quantities; present only when greater than zero.
`total_storage_charges`	String	"storage_rate_per_day" multiplied by "number_of_billable_storage_days"; present only when both are set.
`unlocode_collection`	UnlocodeCollection	Flattened UN/LOCODEs and descriptions for the import, lading, arrival and final ports.
`vessel_name`	String	Vessel name. Optional unless configured as required.
`volume`	String	The shipment volume, converted from cubic meters to the unit in "volume_unit" when one is set. Required unless the adapter is configured to make it optional.
`volume_unit`	String	The source volume unit. Always present; an empty string when the shipment has none.
`voyage_number`	String	Voyage number. Optional unless configured as required.
`weight_unit_code`	String	Weight unit qualifier. Always K (kilograms).

EntityName top

Name	Data Type	Description
`address_1`	String	Address line 1. Required for SH, CN, CON, CUS, BT and BF unless the adapter is configured to make the shipper or ship-to address optional.
`address_2`	String	Address line 2.
`city`	String	City.
`code`	String	The N1 entity code. SH = shipper (from the consignor, or the shipment ship-from fields), CN = ship-to (from the shipment ship-to fields, or the consignee), CON = consignee organization (always from the consignee location), CUS = forwarder customer, BT = bill-to, BF = bill-from (the seller on an "Invoice", the customer on a "Bill"). Additional parties use the codes configured in the adapter's additional party mapping (by default pickup, consignor, consignee, delivery and customer).
`country`	String	Country code.
`government_assigned_id`	String	A government-assigned party id.
`government_assigned_id_type`	String	The type of "government_assigned_id".
`identifier`	String	The party identifier (owners id).
`location_identifier`	String	The location identifier (location owners id).
`location_name`	String	Location name. Additional parties only.
`name`	String	Party name. Required for SH, CN, CON, CUS, BT and BF unless the adapter is configured to make the shipper or ship-to name optional.
`postal_code`	String	Postal / ZIP code.
`state`	String	State / province. Omitted unless it is exactly 2 characters (additional parties excepted).
`unlocode`	String	UN/LOCODE.
`unlocode_description`	String	UN/LOCODE description.

Port top

Name	Data Type	Description
`city`	String	City.
`code`	String	The port role. O = origin / lading, M = destination / discharge, FP = final port, R = receipt / import.
`code_qualifier`	String	Code qualifier. Always UN.
`country`	String	Country code.
`date_qualifier`	String	The DTM date qualifier: 369 (departure) on O, 371 (arrival) on M. Not present on FP or R.
`date_time`	DateTime	The datetime (ISO 8601): estimated departure on O, estimated arrival on M, actual arrival on FP. Not present on R.
`description`	String	A description of the port.
`unlocode`	String	UN/LOCODE. On FP this is the ship-to UN/LOCODE, optional unless the adapter is configured to require it.

ShipmentLeg top

Name	Data Type	Description
`carrier`	LegCarrier	The leg carrier.
`carrier_scac`	String	The leg carrier SCAC.
`leg_sequence_number`	String	The leg order.
`leg_type`	String	The leg type (e.g. MAIN).
`mode`	String	Transport mode.
`vessel_name`	String	Vessel name.
`voyage_number`	String	Voyage number.

LegCarrier top

Name	Data Type	Description
`address_1`	String	Address line 1.
`address_2`	String	Address line 2.
`city`	String	City.
`country`	String	Country code.
`name`	String	Carrier name.
`postal_code`	String	Postal / ZIP code.
`state`	String	State / province.

ContainerGroup top

Name	Data Type	Description	Required
`equipment_size`	String	The container size code.
`number_of_containers`	String	The number of containers with this size code.

PurchaseOrder top

Name	Data Type	Description	Required
`customer_order_number`	String	The purchase order number.

AssignedGroup top

Name	Data Type	Description	Required
`assigned_number`	String	The assigned group number. Always 1.
`containers`	Array<Container>	One entry per container on the shipment.

Container top

Name	Data Type	Description
`arrival_demurrage_free_days`	String	Free demurrage days at arrival.
`arrival_detention_free_days`	String	Free detention days at arrival.
`container_dimensions_uom`	String	The unit of the container dimensions: the source dimension unit, or FT when none is set. Always present.
`container_height`	String	Container height, converted from feet to "container_dimensions_uom".
`container_length`	String	Container length, converted from feet to "container_dimensions_uom".
`container_width`	String	Container width, converted from feet to "container_dimensions_uom".
`containerization_type`	String	The container containerization type.
`equipment_number`	String	The container serial number (container number after the first 4 characters). Required.
`equipment_scac`	String	The container number owner prefix (first 4 characters).
`equipment_size`	String	The container size code. Required unless the adapter is configured to make it optional.
`equipment_size_mapped`	String	The size code after the configured size code mappings.
`gross_weight`	String	Container gross weight. Converted from kilograms to the source unit in "gross_weight_original_uom" when one is set.
`gross_weight_original_uom`	String	The source unit of the gross weight.
`iso_code`	String	The container ISO type code.
`origin_gate_in_actual`	DateTime	The actual origin gate-in datetime (ISO 8601).
`seal_1`	String	Seal number.
`seal_2`	String	Second seal number.
`seal_3`	String	Third seal number.
`tare_weight`	String	Container tare weight, converted from kilograms to the unit in "tare_weight_original_uom" when one is set.
`tare_weight_original_uom`	String	The source unit of the tare weight.
`weight_code`	String	Always K.
`weight_qualifier`	String	Always G (gross).

PackageDetail top

Name	Data Type	Description
`gross_weight`	String	Package gross weight. Converted from kilograms to the source unit in "gross_weight_original_uom" when one is set.
`gross_weight_original_uom`	String	The source unit of the gross weight.
`height`	String	Package height, converted from centimeters to "package_dimensions_uom" when one is set.
`length`	String	Package length, converted from centimeters to "package_dimensions_uom" when one is set.
`package_dimensions_uom`	String	The source unit of the package dimensions.
`quantity`	String	The package quantity.
`width`	String	Package width, converted from centimeters to "package_dimensions_uom" when one is set.

ContainerInvoiceLine top

Name	Data Type	Description
`allowance_code`	String	The charge code after the configured charge code mappings.
`amount`	String	The charge amount, to 3 decimal places. Summed per mapped charge code when lines are grouped.
`charge_code_description`	String	The source charge code description.
`converted_amount`	String	The amount in the converted currency, to 3 decimal places.
`description`	String	The charge description.
`item_number`	String	The line item number.
`quantity`	String	The quantity.

DateCollection top

Name	Data Type	Description
`arrival_port_actual`	DateTime	Actual port arrival.
`arrival_port_estimated`	DateTime	Estimated port arrival.
`delivery_actual`	DateTime	Actual delivery.
`delivery_estimated`	DateTime	Estimated delivery.
`departure_actual`	DateTime	Actual departure.
`departure_estimated`	DateTime	Estimated departure.
`loading_actual`	DateTime	Actual loading.
`loading_estimated`	DateTime	Estimated loading.
`pickup_actual`	DateTime	Actual pickup.
`pickup_estimated`	DateTime	Estimated pickup.

UnlocodeCollection top

Name	Data Type	Description
`arrival_description`	String	The arrival port description.
`arrival_unlocode`	String	The arrival port UN/LOCODE.
`final_port_description`	String	The final port description.
`final_port_unlocode`	String	The final port UN/LOCODE.
`import_description`	String	The import port description.
`import_unlocode`	String	The import port UN/LOCODE.
`lading_description`	String	The port of lading description.
`lading_unlocode`	String	The port of lading UN/LOCODE.

PackedItem top

Name	Data Type	Description
`commodity_description`	String	The commodity description.
`commodity_type`	String	The commodity type code.
`description_of_goods`	String	The goods description.
`height`	String	Package height, converted from centimeters to "package_dimensions_uom" when one is set.
`length`	String	Package length, converted from centimeters to "package_dimensions_uom" when one is set.
`marks_and_numbers`	String	Marks and numbers.
`package_containers`	Array<PackageContainer>	The containers this package group is packed in.
`package_dimensions_uom`	String	The source unit of the package dimensions.
`package_number`	String	The 1-based position of the package group (within the commodity group, for "commodity_pack").
`quantity`	String	The package quantity.
`received_by`	String	The name of the party that received the package. "packed_items" only.
`type_code`	String	The package type code.
`type_description`	String	The package type description.
`volume`	String	Package volume, converted from cubic meters to "volume_unit".
`volume_unit`	String	The source volume unit, or M3 when none is set. Always present.
`weight`	String	Package gross weight, converted from kilograms to the unit in "weight_converted_uom" when one is set.
`weight_converted_uom`	String	The unit "weight" was converted to (the source gross weight unit).
`width`	String	Package width, converted from centimeters to "package_dimensions_uom" when one is set.

PackageContainer top

Name	Data Type	Description
`container_dimensions_uom`	String	The unit of the container dimensions: the source dimension unit, or FT when none is set. Always present.
`container_height`	String	Container height, converted from feet to "container_dimensions_uom".
`container_length`	String	Container length, converted from feet to "container_dimensions_uom".
`container_related_charges`	Array<ContainerCharge>	The invoice lines split evenly across the containers. Present only when the adapter is configured to split charges by container, and only under "packed_items".
`container_width`	String	Container width, converted from feet to "container_dimensions_uom".
`equipment_number`	String	The container serial number (container number after the first 4 characters).
`equipment_scac`	String	The container number owner prefix (first 4 characters).
`equipment_size`	String	The container size code.
`equipment_size_mapped`	String	The size code after the configured size code mappings.
`equipment_type`	String	The container ISO type code.
`gross_weight`	String	Container gross weight. Converted from kilograms to the source unit in "gross_weight_original_uom" when one is set.
`gross_weight_original_uom`	String	The source unit of the gross weight.
`origin_gate_in_actual`	DateTime	The actual origin gate-in datetime (ISO 8601).
`packed_item_in_container_weight`	String	The package group gross weight in kilograms.
`seal_1`	String	Seal number.
`tare_weight`	String	Container tare weight, converted from kilograms to the unit in "tare_weight_original_uom" when one is set.
`tare_weight_original_uom`	String	The source unit of the tare weight.
`weight_code`	String	Always K.
`weight_qualifier`	String	Always G (gross).

ContainerCharge top

Name	Data Type	Description
`allowance_code`	String	The charge code after the configured charge code mappings.
`amount`	String	The line amount divided by the container count, to 3 decimal places. The last charge of the last container absorbs any rounding difference.
`description`	String	The charge description.
`item_number`	String	The line item number.
`quantity`	String	The quantity.

CommodityGroup top

Name	Data Type	Description
`commodity_description`	String	The commodity description of the first package group in the group.
`commodity_number`	String	The 1-based commodity group number.
`commodity_pack`	Array<PackedItem>	The package groups in this commodity group (without "received_by" or "container_related_charges").
`commodity_type`	String	The shared commodity type code.
`description_of_goods`	String	The goods description of the first package group in the group.

ReferenceNumber top

Name	Data Type	Description
`code`	String	The reference qualifier / code.
`description`	String	A description of the reference.
`value`	String	The reference value.

CommercialInvoice top

Name	Data Type	Description
`commercial_invoice_lines`	Array<CommercialInvoiceLine>	The commercial invoice lines.
`currency`	String	The currency.
`gross_weight_kgs`	String	Gross weight in kilograms.
`inco_terms`	String	Incoterms.
`invoice_number`	String	The commercial invoice number.
`manufacturer`	Manufacturer	The commercial invoice manufacturer.
`total_due`	String	The total due.
`total_other_charges`	String	Total other charges.
`total_tax`	String	Total tax.

CommercialInvoiceLine top

Name	Data Type	Description
`country_of_origin`	String	Country of origin.
`customs_quantity`	String	The customs quantity.
`customs_quantity_2`	String	The second customs quantity.
`customs_quantity_uom`	String	The customs quantity unit.
`description`	String	The line description.
`duty_rate`	String	The first duty rate, to 3 decimal places; present only when it is numeric.
`entered_value`	String	The customs entered value.
`extended_price`	String	The extended price.
`line_id`	String	The line id.
`manufacturer`	Manufacturer	The line manufacturer.
`part_number`	String	The part number.
`quantity`	String	The quantity.
`tariff_number`	String	The tariff (HTS) number.
`total_customs_duty`	String	The sum of the line duty amounts. Always present.
`total_customs_fees`	String	The sum of the line fee amounts. Always present.
`unit_of_measure`	String	The unit of measure.
`unit_of_measure_description`	String	The unit of measure description.
`unit_price`	String	The unit price.
`us_mid_code`	String	The US manufacturer id (MID) code.

Manufacturer top

Name	Data Type	Description
`address_1`	String	Address line 1.
`address_2`	String	Address line 2.
`city`	String	City.
`country`	String	Country code.
`government_assigned_id`	String	A government-assigned party id.
`government_assigned_id_type`	String	The type of "government_assigned_id".
`identifier`	String	The party identifier (owners id).
`location_identifier`	String	The location identifier (location owners id).
`name`	String	Manufacturer name.
`postal_code`	String	Postal / ZIP code.
`state`	String	State / province.

BillOfLading top

Name	Data Type	Description
`code`	String	MB = master bill, HB = house bill, SB = sub-house bill (the first of these the bill carries).
`house_bill`	String	The house bill number (when "code" is HB).
`issuer_scac`	String	The issuer SCAC.
`it_number`	String	The in-bond (IT) number.
`manifest_quantity`	String	The manifest quantity.
`manifest_quantity_uom`	String	The manifest quantity unit.
`master_bill`	String	The master bill number (when "code" is MB).
`subhouse_bill`	String	The sub-house bill number (when "code" is SB).

CustomsDeclaration top

Name	Data Type	Description
`broker_filer_code`	String	The broker filer code.
`broker_reference`	String	The broker reference.
`consignee_code`	String	The consignee code.
`customs_mode`	String	The customs mode.
`customs_type`	String	The customs type.
`declaration_number`	String	The declaration number.
`entered_value`	String	The entered value.
`entry_date`	String	The entry date.
`entry_type`	String	The entry type.
`export_country_code`	String	The export country code.
`export_date`	String	The export date.
`import_country_code`	String	The import country code.
`import_date`	String	The import date.
`importer_code`	String	The importer code.
`importer_reference`	String	The importer reference.
`manifest_quantity`	String	The manifest quantity.
`manifest_quantity_uom`	String	The manifest quantity unit.
`port_of_arrival_code`	String	The port of arrival code.
`port_of_entry_code`	String	The port of entry code.
`port_of_entry_description`	String	The port of entry description.
`port_of_loading_code`	String	The port of loading code.
`release_date`	String	The release date.
`statement_date`	String	The statement date.
`submitted_date`	String	The submitted date.
`total_duty`	String	Total duty.
`total_fees`	String	Total fees.

EDI Formats

Freight Invoice EDI - JSON Specification

Summary

Objects

Root top

FreightInvoice top

EntityName top

Port top

ShipmentLeg top

LegCarrier top

ContainerGroup top

PurchaseOrder top

AssignedGroup top

Container top

PackageDetail top

ContainerInvoiceLine top

DateCollection top

UnlocodeCollection top

PackedItem top

PackageContainer top

ContainerCharge top

CommodityGroup top

ReferenceNumber top

CommercialInvoice top

CommercialInvoiceLine top

Manufacturer top

BillOfLading top

CustomsDeclaration top

Example

EDI Formats

Freight Invoice EDI - JSON Specification

Summary

Objects

Example

View as Plain TextCopy