Send and receive freight / services invoices.
| Name | Description |
|---|---|
| Root | Chain.io schema for a freight / services invoice. |
| Party | Represents a named party on an invoice. |
| PartyIdentifier | A code and context that can be used to uniquely identify a party. |
| PhoneNumber | A phone number and type object. |
| EmailAddress | An email address and type object. |
| InvoiceAmount | An monetary amount that appears on the invoice in the billing currency. |
| ChargeAmount | An monetary amount on the invoice line representing an alternate amount that is not the issuer's amount or the invoice amount. Typically, this will represent charges carried through from another company or division and may represent a currency different than the invoice's currency or the issuer's accounting currency. This data is present primarily for informational or auditing purposes, such as when the charge represents an amount quoted at origin in a different currency and then must be presented in the invoicing currency. |
| AccountingAmount | A monetary amount that is associated with the invoice amount in an alternate currency. |
| CustomProperties | An object an input converter can utilize to pass any custom data back into a flow that can potentially be utilized by an output converter. |
| InvoiceLine | An itemized breakdown of all the charges on the invoice. |
| Location | A unique location. |
| UnLocode | A location representing a UN location code. |
| AirPort | A location representing an airport. |
| Address | A location representing a street address. |
| Weight | |
| Volume | |
| MasterBillJob | A job data set representing cargo moved under a master bill of lading. |
| HouseBillJob | A job data set representing cargo moved under a house bill of lading. |
| Document | A document / file that is associated with the invoice. |
| Root_payment_terms | The agreed upon conditions for when the invoice is due and any discounts that may be provided for early repayment. |
| Party_contact | A point of contact at the party. |
| MasterBillJob_containers | |
| HouseBillJob_containers | |
| HouseBillJob_commercial_invoices | |
| HouseBillJob_purchase_orders |
| Name | Data Type | Description | Required |
|---|---|---|---|
accounting_system_identifier | String | The 'primary key' uniquely identifying the invoice in the issuer's accounting system. For some systems, this may be the same as the invoice_number. | YES |
transaction_type | String | Identifies the type of accounting transaction the invoice represents. This property is determined from the point of view of what party's accounting system the accounting_system_identifier property relates to. If the identifier points to an accounts_receivable in that system, then this transaction_type should reflect that. Allowed values: accounts_receivable, accounts_payable. | YES |
credit_memo | Boolean | If true, then the invoice represents a credit memo. Amounts on a credit memo should always be negative. Amounts on a standard invoice, regardless of the transaction_type, should always be positive. | |
invoice_number | String | An external identifier for the invoice. Typically, the invoice number is either unique accross the entire accounting system or unique per debtor. | YES |
status | String | Indicates the current status of the invoice. Allowed values: draft, open, paid, voided. | |
invoice_date | String | The date that is the basis for all invoice aging purposes such as the due date and any terms based discounts. | |
issued_date | String | The date the invoice was presented to the receiving party. | |
due_date | String | The date the debtor must pay the creditor in full. | |
posted_date | String | The date the invoice was posted to the accounting system's ledger. | |
payment_terms | Root_payment_terms | The agreed upon conditions for when the invoice is due and any discounts that may be provided for early repayment. | |
issued_by | Party | The party that issued the invoice. | |
creditor | Party | The party that has provided goods or services and is owed money by the debtor. | |
debtor | Party | The party that incurs the liability for invoice payment. | |
debtor_reference | String | A reference number that is used by the debtor to identify the invoice. This may be a PO number or some other number the debtor relays to the issuer to include on the invoice. | |
creditor_reference | String | An additional reference number that is used by the debtor. This may sometimes be the job number, masterbill, or an alternate accounting reference. | |
invoice_description | String | A description of the services rendered and covered by the invoice. | |
memo | String | An additional text area used for conveying notes about the invoice. This may include text about late payment penalties, contact information, plain text terms or any other information. | |
tax_rate | Decimal | The decimal percentage tax rate that applies to the invoice. 0.2 = 2% | |
tax_rate_code | String | The accounting system's native code for identifying the applicable tax rate. | |
invoice_amount | InvoiceAmount | YES | |
accounting_system_amount | AccountingAmount | ||
criticality | String | A code identifying the payment criticality associated with the invoice. | |
company_code | String | The accounting system's native code for identifying which internal company issued the invoice. | |
department_code | String | The accounting system's native code for identifying which internal department / division issued the invoice. | |
branch_code | String | The accounting system's native code for identifying which internal branch issued the invoice. | |
job_identifier | String | Invoices that are issued for a single job (shipment, customs declaration, linehaul, etc) can be linked to that job data inside this document through this property. Invoices that are associated with multiple jobs should utilize the job_identifier property on the invoice lines. For invoices that do not span multiple jobs, the line's job_identifier can be left blank and the invoice's job_identifier can be utilized as the sole source of job links. | |
custom_properties | CustomProperties | ||
lines | Array<InvoiceLine> | An itemized breakdown of all the charges on the invoice. | |
jobs | Array<MasterBillJob | HouseBillJob> | Any job that is linked in some manner to the invoice. The actual linkages from invoices or lines are represented via the job_identifier properties on the Invoice and InvoiceLine schemas. | |
documents | Array<Document> | Any invoice documents / files associated with the invoice. | |
created_at | DateTime | The date this record was created. | |
updated_at | DateTime | The date this record was updated. |
| Name | Data Type | Description | Required |
|---|---|---|---|
identifiers | Array<PartyIdentifier> | An array of all applicable identifiers that can be used to identify the party. | |
name | String | The entity's name. | |
address_1 | String | The address' street number and name. | |
address_2 | String | The address' secondary address information. | |
city | String | The address' city component. | |
country_subdivision | String | The country specific subdivision code. This could represent a county, province, state, etc. In order to maximize interoperability, you should utilize the ISO 3166-2 country subdivision identifiers when providing this data. | |
country | String | The address' 2 character ISO-3166-2 country Code. | |
postal_code | String | The unique postal code identifier for the address. | |
contact | Party_contact | A point of contact at the party. | |
custom_properties | CustomProperties |
| Name | Data Type | Description | Required |
|---|---|---|---|
code | String | The identifier code | YES |
code_type | String | The type of data that the identifier code represents. Allowed values: accounting_system_external_identifier, tax_id, iata, scac, legal_entity_id, duns. | YES |
code_country | String | The 2 character ISO-3166-2 country code that the id code was issued in / by. |
| Name | Data Type | Description | Required |
|---|---|---|---|
phone_type | String | The type of phone number. Allowed values: main, mobile, work, home, fax, other. | YES |
phone_number | String | The actual phone number. When at all possible, to increase interoperability, phone numbers should be formatted according to RFC3966. Also see libphonenumber when parsing phone numbers. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
email_type | String | The type of email address. Allowed values: main, work, personal, other. | YES |
email_address | String | The email address | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
total | Decimal | The total amount including taxes/vat. | YES |
currency | String | The ISO 4217 currency code indicating the currency the amount is billed in. | YES |
subtotal | Decimal | The invoice amount without tax/vat. | |
total_tax | Decimal | The tax/vat amount associated with the invoice amount. |
| Name | Data Type | Description | Required |
|---|---|---|---|
total | Decimal | The total amount for the charge. | YES |
currency | String | The ISO 4217 currency code indicating the currency the charge represents. | YES |
subtotal | Decimal | The invoice amount without tax/vat. | |
total_tax | Decimal | The tax/vat amount associated with the invoice amount. | |
exchange_rate | Decimal | The exchange rate representing the conversion of this object's total to the invoice amount's total. The rate is represented as a decimal percentage (.ie 100% = 1.0). The conversion formula is simply this object's total * exchange_rate = invoice_amount.total. |
| Name | Data Type | Description | Required |
|---|---|---|---|
total | Decimal | The total amount including taxes/vat. | YES |
currency | String | The ISO 4217 currency code indicating the currency the amount is billed in. | YES |
subtotal | Decimal | The invoice amount without tax/vat. | |
total_tax | Decimal | The tax/vat amount associated with the invoice amount. | |
exchange_rate | Decimal | The exchange rate representing the conversion of this object's total to the invoice amount's total. The rate is represented as a decimal percentage (.ie 100% = 1.0). The conversion formula is simply this object's total * exchange_rate = invoice_amount.total. | YES |
| Name | Data Type | Description | Required |
|---|
| Name | Data Type | Description | Required |
|---|---|---|---|
line_identifier | String | A value that uniquely identifies the invoice line. This may be used to convey a primary key for some systems while for others it can also just be a numeric counter. | |
line_number | Decimal | A line number that can be used to sort the invoice lines in the correct presentation order. The number must be greater than 0. | |
charge_code | String | A code used by the issuer's accounting system to identify the goods or service associated with the charge. | YES |
charge_classification | String | A code used by the issuer's accounting system that classifies the type of charge. | |
description | String | A description of the goods or services associated with the line. | |
quantity | Decimal | The number of units being billed on the line. This may represent the number of containers, house bills, documents. It may also represent weights or distances. | |
unit_of_measure | String | A code used by the issuer's accounting system identifying the singular unit associated with the line. This would typically be something like 'container', 'house bill', 'kilogram', 'mile', 'pieces', etc | |
units_per_unit_of_measure | Decimal | The number of unit_of_measure units that comprise a single billing unit. For example, given a charge description of "$100 per 1000 kilograms". The units_per_unit_of_measure value would be 1000. | |
unit_price | Decimal | The per unit cost, in the invoice_amount.currency, of a single billing unit. For flat rate charges, unit_price * quantity = amount. For per unit charges, the calculation is roughly (quantity / units_per_unit_of_measure) * unit_price. | |
tax_rate | Decimal | The decimal percentage tax rate that applies to the invoice line. 0.2 = 2% | |
tax_rate_code | String | The accounting system's native code for identifying the applicable tax rate. | |
invoice_amount | InvoiceAmount | YES | |
accounting_system_amount | AccountingAmount | ||
charge_amount | ChargeAmount | ||
department_code | String | The accounting system's native code for identifying which internal department / division issued the charge. This may differ from the overall invoice's department code in cases when a customer is issued a single invoice that consitutues charges spanning multiple departments, like freight, customs clearance and local pickup / delivery charges. | |
branch_code | String | The accounting system's native code for identifying which internal branch issued the charge. This may differ from the overall invoice's department code in cases when a customer is issued a single invoice that consitutues charges spanning multiple departments, like freight, customs clearance and local pickup / delivery charges. | |
job_identifier | String | The job this invoice line is linked with. For invoices that do not span multiple jobs, the line's job_identifier can be left blank and the invoice's job_identifier can be utilized as the sole source of job links. | |
custom_properties | CustomProperties |
| Name | Data Type | Description | Required |
|---|---|---|---|
type | String | A location type identifier Allowed values: unlocode. | YES |
unlocode | String | The UN/Locode identifier for the sea port. | YES |
unlocode_description | String | A free text description of the UN/Locode. |
| Name | Data Type | Description | Required |
|---|---|---|---|
type | String | A location type identifier Allowed values: airport. | YES |
iata_code | String | The IATA airport location identifier. | YES |
iata_code_description | String | A free text description of the IATA Code. | |
unlocode | String | The UN/Locode identifier correlated with the IATA code. |
| Name | Data Type | Description | Required |
|---|---|---|---|
type | String | A location type identifier. Allowed values: address. | YES |
name | String | A name for the address. Typically the name of the business located at the address. | |
address_1 | String | The address' street number and name. | YES |
address_2 | String | The address' secondary address information. | |
city | String | The address' city component. | YES |
country_subdivision | String | The country specific subdivision code. This could represent a county, province, state, etc. In order to maximize interoperability, you should utilize the ISO 3166-2 country subdivision identifiers when providing this data. | |
country | String | The address' 2 character ISO-3166-2 country Code. | YES |
postal_code | String | The unique postal code identifier for the address. | |
unlocode | String | A UN/Locode identifier correlated with the address. |
| Name | Data Type | Description | Required |
|---|---|---|---|
amount | Decimal | The numeric weight amount | YES |
unit | String | The unit of measure associated with the amount property. tonne = Metric Tonne (1,000 kilograms), ton = Imperial Tonne (1,000 pounds) Allowed values: kilogram, tonne, pound, ton. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
amount | Decimal | The numeric volume amount | YES |
unit | String | The unit of measure associated with the amount property. gallon - US liquid gallon (3.785411784 litres), imperial_gallon = UK gallon (4.54609 litres) Allowed values: cubic_meter, cubic_foot, liter, gallon, imperial_gallon. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
job_type | String | An indicator of the type of job being represented. Allowed values: master_bill_of_lading. | YES |
job_identifier | String | The 'primary key' uniquely identifying the job in the issuer's accounting / tms system. For some systems, this may be the same as the job_reference. | YES |
job_reference | String | A 'natural key' identifying the job in the issuer's accounting / tms system. This will typically be a more user friendly variant of the job_identifier. While a job_identifier can potentially be an unrelated id like a guid or numeric database id, the job_reference will typically represent a value that is presented to users to identify the job. | YES |
transport_mode | String | The primary means of transport of the goods on their journey. Allowed values: sea, air, road, rail, sea_air, air_sea, inland_waterway, courier, rail_sea, rail_air, rail_road. | |
master_bill_of_lading | String | The master bill of lading number the carrier has assigned to this shipment. | |
vessel_name | String | The name of the vessel associated with the job. | |
imo_number | String | The International Maritime Organization (IMO) number of the ocean vessel. This should be the 7 digit number only. | |
voyage_number | String | The voyage number associated with the job. This can represent an ocean vessel's voyage number, a flight number or any other number that identifies the voyage routing. | |
carrier | Party | The party responsible for physically transporting the goods on the job. | |
origin_agent | Party | The freight forwarder facilitating the export process. | |
destination_agent | Party | The freight forwarder facilitating the import process. | |
consignor | Party | The party sending a shipment. May also be referred to as the sender, shipper or exporter. This represents the actual shipper party named on the master bill. | |
consignee | Party | The party financially responsible for receipt of a shipment. Typically, but not always, the consignee is the receiver of the shipment as well as the importer of record. This represents the actual consignee party named on the master bill. | |
customer | Party | The customer that is contracting the forwarder to move the goods. | |
pickup | Address | The physical original point of the shipment where the goods are retrieved from. | |
place_of_receipt | UnLocode | AirPort | The location where goods are handed over to the carrier by the consignor or their agent. | |
port_of_loading | UnLocode | AirPort | The port where goods are loaded by the carrier on to the vessel. | |
port_of_discharge | UnLocode | AirPort | The port where goods are offloaded from the vessel by the carrier. | |
place_of_delivery | UnLocode | AirPort | The location where goods are handed over from the carrier to the consignee or their agent. | |
delivery | Address | The physical destination point of the shipment where the goods are sent to. | |
gross_weight | Weight | The gross weight of goods on the job. | |
chargeable_weight | Weight | The chargeable weight of goods on the job. | |
volume | Volume | The total volume of the goods on the job. | |
estimated_pickup_date | DateTime | The estimated date the goods will be picked up from the origin point. | |
pickup_date | DateTime | The actual date the goods were picked up from the origin point. | |
estimated_departure_date | DateTime | The estimated date the goods will depart from the port of loading. | |
departure_date | DateTime | The actual date the goods departed from the port of loading. | |
estimated_arrival_date | DateTime | The estimated date the goods will arrive at the port of discharge. | |
arrival_date | DateTime | The actual date the goods arrived at the port of discharge. | |
estimated_delivery_date | DateTime | The estimated date the goods will be delivered. | |
delivery_date | DateTime | The actual date the goods were delivered. | |
freight_payment_terms | String | The freight terms of payment indicating the party responsible for freight charges. Allowed values: collect, prepaid, third_party. | |
containerization_type | String | The container load type used for the job. Allowed values: fcl, lcl, ftl, ltl. | |
containers | Array<MasterBillJob_containers> | All containers associated with the job. | |
house_bills_of_lading | Array<HouseBillJob> | All house bill jobs moving under the same master bill. | |
custom_properties | CustomProperties |
| Name | Data Type | Description | Required |
|---|---|---|---|
job_type | String | An indicator of the type of job being represented. Allowed values: house_bill_of_lading. | YES |
job_identifier | String | The 'primary key' uniquely identifying the job in the issuer's accounting / tms system. For some systems, this may be the same as the job_reference. | YES |
job_reference | String | A 'natural key' identifying the job in the issuer's accounting / tms system. This will typically be a more user friendly variant of the job_identifier. While a job_identifier can potentially be an unrelated id like a guid or numeric database id, the job_reference will typically represent a value that is presented to users to identify the job. | YES |
direction | String | The directionality of the job that is being billed. foreign_to_foreign is also known as triangle, third-party or cross-trade shipments. Allowed values: import, export, domestic, foreign_to_foreign. | |
transport_mode | String | The primary means of transport of the goods on their journey. Allowed values: sea, air, road, rail, sea_air, air_sea, inland_waterway, courier, rail_sea, rail_air, rail_road. | |
master_bill_of_lading | String | The master bill of lading number the carrier has assigned to this shipment. | |
house_bill_of_lading | String | The house bill of lading number the forwarder has assigned to this shipment. | |
vessel_name | String | The name of the vessel associated with the job. | |
imo_number | String | The International Maritime Organization (IMO) number of the ocean vessel. This should be the 7 digit number only. | |
voyage_number | String | The voyage number associated with the job. This can represent an ocean vessel's voyage number, a flight number or any other number that identifies the voyage routing. | |
carrier | Party | The party responsible for physically transporting the goods on the job. | |
consignor | Party | The party sending a shipment. May also be referred to as the sender, shipper or exporter. This represents the actual shipper party named on the master bill. | |
consignee | Party | The party financially responsible for receipt of a shipment. Typically, but not always, the consignee is the receiver of the shipment as well as the importer of record. This represents the actual consignee party named on the master bill. | |
customer | Party | The customer that is contracting the forwarder to move the goods. | |
pickup | Address | The physical original point of the shipment where the goods are retrieved from. | |
port_of_loading | UnLocode | AirPort | The port where goods are loaded by the carrier on to the vessel. | |
port_of_discharge | UnLocode | AirPort | The port where goods are offloaded from the vessel by the carrier. | |
delivery | Address | The physical destination point of the shipment where the goods are sent to. | |
gross_weight | Weight | The gross weight of goods on the job. | |
chargeable_weight | Weight | The chargeable weight of goods on the job. | |
volume | Volume | The total volume of the goods on the job. | |
estimated_pickup_date | DateTime | The estimated date the goods will be picked up from the origin point. | |
pickup_date | DateTime | The actual date the goods were picked up from the origin point. | |
estimated_departure_date | DateTime | The estimated date the goods will depart from the port of loading. | |
departure_date | DateTime | The actual date the goods departed from the port of loading. | |
estimated_arrival_date | DateTime | The estimated date the goods will arrive at the port of discharge. | |
arrival_date | DateTime | The actual date the goods arrived at the port of discharge. | |
estimated_delivery_date | DateTime | The estimated date the goods will be delivered. | |
delivery_date | DateTime | The actual date the goods were delivered. | |
description_of_goods | String | A generalized description of the type of goods moving on the job. | |
freight_payment_terms | String | The freight terms of payment indicating the party responsible for freight charges. Allowed values: collect, prepaid, third_party. | |
inco_terms | String | The terms of sale defining the responsibilities of the consignor/seller and consignee/buyer. Expired terms dat, daf, des, deq, ddu are included for backwards compatibility sake, though it is very highly recommended to no longer utilize them. Allowed values: exw, fca, fas, fob, cfr, cif, cpt, cip, dap, dpu, ddp, dat, daf, des, deq, ddu. | |
inco_terms_location | String | The named place or port in the inco terms defining the location the terms are applicable for. Using terms of "FOB CNYTN" the location would be CNYTN | |
containerization_type | String | The container load type used for the job. Allowed values: fcl, lcl, ftl, ltl. | |
containers | Array<HouseBillJob_containers> | All containers associated with the job. | |
commercial_invoices | Array<HouseBillJob_commercial_invoices> | All commercial invoices associated with the job. | |
purchase_orders | Array<HouseBillJob_purchase_orders> | All purchase orders associated with the job. | |
custom_properties | CustomProperties |
| Name | Data Type | Description | Required |
|---|---|---|---|
document_identifier | String | The 'primary key' uniquely identifying the document in the issuer's accounting system. | YES |
file_name | String | The file name of the document. | YES |
document_classification | String | A shared code identifying the type of document sent with the invoice. Allowed values: bill_of_lading, invoice, email, customs_declaration, proof_of_delivery, commercial_invoice, purchase_order. | |
document_code | String | The accounting system's native code for identifying the type of document being sent. This will typically be a code that might indicate an 'invoice', 'bill of lading', 'commercial invoice', 'customs release' or any other documents the issuer deems relevant to the transaction. | YES |
document_description | String | A free-text description of the document. Typically, this will be a full description of the document_code value. | |
media_type | String | The identifier indicating the data format of the document. Also known as mime type. | YES |
body | String | The base4 encoded binary contents of the document. | YES |
creation_date | DateTime | ||
custom_properties | CustomProperties |
| Name | Data Type | Description | Required |
|---|---|---|---|
terms | String | The terms code identifying the type of payment terms in effect. net = NET, pia = Payment In Advance, cia = Cash In Advance, cod = Cash on Delivery, pod = Payment on Delivery, mfi = Month Following Invoice, eom = End of Month Allowed values: net, pia, cia, cod, pod, mfi, eom. | YES |
terms_number | Decimal | The value used to indicate the numeric portion of the terms code. Given the terms "NET 10", this value would be 10. Given the terms "15 MFI", this value would be 15. | |
discount_number | Decimal | The value used to indicate the time period portion of a discount. Typically, this is given in the number of days. | |
discount_percentage | Decimal | The value used to indicate the overall percentage discount that will be provided for early payment. If an creditor is giving a 2.5% discount, this value should be sent as 2.5 |
| Name | Data Type | Description | Required |
|---|---|---|---|
name | String | The name of the contact | |
phone_numbers | Array<PhoneNumber> | ||
email_addresses | Array<EmailAddress> |
| Name | Data Type | Description | Required |
|---|---|---|---|
container_number | String | The ISO 6346 11 digit unique container identifier. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
container_number | String | The ISO 6346 11 digit unique container identifier. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
invoice_number | String | The unique tracking number assigned to the commercial invoice by the seller. | YES |
| Name | Data Type | Description | Required |
|---|---|---|---|
order_number | String | The unique tracking number assigned to the purchase order by the seller. | YES |