Freight Invoice - JSON Specification

Summary

Use this format to send invoices for freight and other logistics related services.

Objects

Name	Description
Root	The top level document
ServiceInvoice	An invoice for supply chain related services (not a commercial invoice)
ServiceInvoiceLine	A line on an invoice
Shipment	A shipment of products.
Locode	A UN/LOCODE
Address	A physical location.
Container	A container used to ship goods
PurchaseOrder	An order for a physical product from a supplier to a customer.
NativeReferenceNumber	A raw reference number value received from a source system. This document is meant to relay a platform's native reference number values in as close to the native format as possible and should not be utilized for any business logic purposes. If a reference number is required for any business logic aside from passing through reference number values, it should be added as an actual property to a canonical document.

Root top

Name	Data Type	Description
`doc_type`	String	Always `freight_invoice_json`
`invoices`	Array<ServiceInvoice>	Array of invoices
`version`	String	The version of the specification being used.

ServiceInvoice top

Name	Data Type	Description
`attachments`	Array<Attachment>	Attachments related to this invoice.
`bill_to_address_1`	String	First address line of the bill to party
`bill_to_address_2`	String	Second addresss line of the bill to party
`bill_to_city`	String	City of the bill to party
`bill_to_contact_email`	String	Contact's email address at the bill to party
`bill_to_contact_name`	String	Contact's name at the bill to party
`bill_to_contact_phone`	String	Contact's phone number at the bill to party
`bill_to_country`	String	2 character ISO country code of the bill to party
`bill_to_id`	String	Identifying code for the bill to party used by the invoicing party
`bill_to_name`	String	Name of the bill to party
`bill_to_postal_code`	String	Postal Code of the bill to party
`bill_to_state`	String	State of the bill to party
`branch_code`	String	The invoicing company's branch, office, or location responsible for issuing this invoice line.
`cancel_reason_code`	String	A reason code for when the invoice is cancelled.
`cancel_reason_code_description`	String	A reason code description for when the invoice is cancelled.
`cancelled`	Boolean	If True, this invoice data represents a cancelled invoice.
`converted_currency`	String	A second currency for the converted_* fields
`converted_total_due`	Decimal	The total_due converted to another currency
`currency`	String	3 letter currency code
`department_code`	String	The invoicing company's department that is responsible for issuing this invoice.
`due_date`	DateTime	The date that payment is due.
`invoice_description`	String	A description of the services rendered and covered by the invoice.
`invoice_lines`	Array<ServiceInvoiceLine>	The invoice's lines
`invoice_number`	String	The invoice number issued by the invoicing party
`invoice_type`	String	The invoice type determined by the invoicing party.
`issued_date`	DateTime	The time the issue was issued by the invoicing party
`outstanding_amount`	Decimal	The remaining amount of money owed on an invoice.
`paid_date`	DateTime	The date the invoice was paid in full.
`payment_term_days`	Integer	Number of days until payment is due from the `issued_date`
`payment_terms`	String	Payment terms (like COD or NET30)
`post_date`	DateTime	The date the invoice was posted to the accounting ledger.
`purchase_orders`	Array<PurchaseOrder>	An order for a physical product from a supplier to a customer.
`remit_to_address_1`	String	First address line of the remit to party
`remit_to_address_2`	String	Second addresss line of the remit to party
`remit_to_city`	String	City of the remit to party
`remit_to_contact_email`	String	Contact's email address at the remit to party
`remit_to_contact_name`	String	Contact's name at the remit to party
`remit_to_contact_phone`	String	Contact's phone number at the remit to party
`remit_to_country`	String	2 character ISO country code of the remit to party
`remit_to_id`	String	Identifying code for the remit to party used by the invoicing party
`remit_to_name`	String	Name of the remit to party
`remit_to_postal_code`	String	Postal Code of the remit to party
`remit_to_state`	String	State of the remit to party
`service_invoice_uid`	String	A `database level` unique ID for the invoice. For the invoice number normally printed on the invoice, use `invoice_number`
`shipments`	Array<Shipment>	Shipments related to this invoice. If one shipment is provided, then assume all lines on the shipment are related to that shipment. If multiple shipments are provided, then link the shipment to the appropriate ServiceInvoiceLine by matching the shipment's `source_system_uid` to the line's `shipment_uid`.
`total_due`	Decimal	Total amount due

ServiceInvoiceLine top

Name	Data Type	Description
`branch_code`	String	Code for the branch that should be associated with the revenue (use on the lines associated with `revenue_invoices`)
`charge_code`	String	Charge code assigned by the invoicing party
`converted_currency`	String	A second currency for the converted_* fields
`converted_total_cost`	Decimal	The total_cost for the invoice line after converting to the converted_currency.
`currency`	String	3 character currency code. (If populated, overrides the currency code at the Invoice header)
`department_code`	String	The invoicing company's department responsible for issuing this invoice line.
`description`	String	Description of the invoice being charged
`line_number`	String	Unique identifier within the invoice for the line. (Usually a sequental number)
`quantity`	Decimal	The number of items being invoiced.
`shipment_uid`	String	Foreign key link to the Shipment `source_system_uid`. Only required if multiple shipments are attached to the invoice.
`tax_rate_code`	String	The code representing tax calculation used for the invoice line
`total_cost`	Decimal	The cost of all items being invoiced on the line
`total_tax`	Number	The total amount of tax added to invoice line. Use line level tax amounts when different tax rates are applied to individual lines.
`unit_price`	Decimal	The cost of one item

Shipment top

Name	Data Type	Description
`agent_reference`	String	Reference number provided by the agent
`arrival_port`	Locode	The port of arrival in the final destination country
`arrival_port_actual`	DateTime	Actual date the shipment arrived at the final air or ocean port (not including final inland transportation)
`arrival_port_estimated`	DateTime	Estimated date the shipment will arrive at the final air or ocean port (not including final inland transportation)
`bill_of_lading_type`	String	Type of bill of lading like `Straight`
`booking_reference`	String	Booking reference number provided by the party making the booking
`booking_submitted_actual`	DateTime	The date the booking was submitted by the shipper
`cargo_ready_actual`	DateTime	Actual date and time the cargo was be available
`cargo_ready_estimated`	DateTime	Estimated date and time the cargo will be available
`carrier_instructions`	String	Instructions to the carrier.
`carrier_scac`	String	Carrier's Standard Carrier Alpha Code (SCAC)
`chargeable_weight_kgs`	Decimal	The shipment's weight used for billing in KGs. Generally the greater of the gross or dimensional weight
`consignee`	Address	The party to whom the goods are consigned
`consignor`	Address	The party who is consigning the goods
`containerization_type`	String	How the shipment will be containerized (FCL, LCL, Loose, FTL, LTL)
`containers`	Array<Container>	Containers on the shipment
`created_by`	User	Deprecated - Please see version > 1.92 and use the `operator` property or `trigger_event.triggered_by` instead. User who created the shipment.
`created_on`	DateTime	Time this record was created in the source system.
`cutoff_time_bol`	DateTime	The final cutoff date and time for submitting the final bill of lading instructions
`cutoff_time_physical`	DateTime	The final cutoff date and time for the physical delivery of the freight
`cutoff_time_vgm`	DateTime	The final cutoff date and time for submitting the verified gross mass (VGM) information
`delivery_actual`	DateTime	The time when the shipment was delivered to its final location.
`departure_actual`	DateTime	Actual date and time the cargo departed from its origin point
`departure_estimated`	DateTime	Estimated date and time the cargo will depart from it's origin point
`description_of_goods`	String	Description of goods in the shipment
`final_destination_port`	Locode	The final port including any inland transportation.
`forwarder_controlling_branch_code`	String	The forwarder's main branch responsible for the shipment
`forwarder_origin_branch`	String	The branch of freight forwarder responsible for shipment.
`forwarder_origin_department`	String	The department of freight forwarder responsible for shipment.
`forwarder_reference`	String	Shipment reference number assigned by the freight forwarder
`forwarder_scac`	String	SCAC or other assigned code for the freight forwarder
`freight_payment_terms`	String	The terms by which the freight will be paid, like `Prepaid` or `Collect`
`gross_weight_kgs`	Decimal	Gross weight of the shipment in kilograms
`house_bill`	String	House bill of lading number
`import_port`	Locode	The port where the shipment will be declared to the import customs authority, generally provided on an international shipment
`inco_term`	String	The INCOTerm under which the product is moving like `FOB`, `DDP`, etc.
`lading_port`	Locode	The port of lading
`loading_actual`	DateTime	Actual date the shipment was loaded onto the vessel
`loading_estimated`	DateTime	Estimated date the shipment will be loaded onto the vessel
`master_bill`	String	Master bill of lading number
`native_reference_numbers`	Array<NativeReferenceNumber>	Raw reference numbers from source systems
`notify_party`	Address	The notify party on the bill of lading
`number_of_packages`	Decimal	Number of packages in the shipment
`sent_date`	DateTime	Time the record was sent by the source system.
`service_level`	String	Service level to be used (like EXP or STD). These will vary per service provider
`ship_from`	Address	The starting point of the shipment
`ship_to`	Address	The ending point of the shipment
`shipper`	Address	The party that is responsible for causing the the goods to be shipped. Often the Beneficial Cargo Owner (BCO).
`shipper_reference`	String	Reference number provided by the shipper
`transmission_uid`	String	A one-time unique identifying code for this transmission of the shipment in question. Used for tracing and logging purposes.
`transport_mode`	String	Mode of transportation (AIR, ROAD, SEA, RAIL)
`vessel_name`	String	Name of vessel (for multi-leg shipments, use the primary leg information)
`volume_cbms`	Decimal	Volume of the shipment in cubic meters
`volume_cf`	Decimal	Volume of the shipment in cubic feet.
`voyage_number`	String	Voyage or flight number (for multi-leg shipments, use the primary leg information)

Locode top

Name	Data Type	Description	Required
`description`	String	A description of the port (like Long Beach)
`unlocode`	String	A valid UN/LOCODE (like USLGB)

Address top

Name	Data Type	Description
`address_1`	String	The first line of the address.
`address_2`	String	The second line of the address.
`address_type`	String	The type of address represented by this element. Specific types may be defined on a per specification basis
`city`	String	The city.
`country`	String	The 2-Digit ISO 3166 Alpha-2 Country Code. Like 'US'
`country_name`	String	The full name of the country like “United States”
`name`	String	The name associated with the address.
`phone_number`	String	The contact phone number
`postal_code`	String	The postal or ZIP code.
`state`	String	The state, province, or administrative division code
`state_name`	String	The full name of the state, province, or administrative division.
`unlocode`	String	The UN/LOCODE associated with the address. Like 'USCHI'

Container top

Name	Data Type	Description	Required
`container_number`	String	Identifying container number (including SCAC prefix)

PurchaseOrder top

Name	Data Type	Description	Required
`customer_order_number`	String	The purchasing party's order number for the purchase order.	YES

NativeReferenceNumber top

Name	Data Type	Description
`code`	String	A code identifying the type of reference number (ex. EDIREF, PO2, ).
`description`	String	A plain-text description of the reference number code. (ex. "EDI Reference Number", "Secondard PO Number").
`value`	String	The reference number value.

Standard Specifications

Freight Invoice - JSON Specification

Summary

Objects

Root top

ServiceInvoice top

ServiceInvoiceLine top

Shipment top

Locode top

Address top

Container top

PurchaseOrder top

NativeReferenceNumber top

Example

Standard Specifications

Freight Invoice - JSON Specification

Summary

Objects

Example

View as Plain TextCopy