The line-state service is a data model that stores line data from documents sent and received on Tradeshift, including data on how the document lines relate to each other. The line and line-relation data is currently stored for the following document types:

  • purchase orders (POs)
  • order changes
  • goods receipts (GRs – known as "ReceiptAdvice" in UBL)
  • invoices (INVs)
  • credit notes (CNs).

The service uses this stored data to determine what document lines relate to each other, so that matching (including either automatic approval or task creation) can be carried out by the decision service. An established relation between different document lines – e.g. between an invoice line and its corresponding PO line – can be referred to as a transaction, and these transactions can have various states, such as Ordered or Billed.

The overall principle is that the state of a given transaction is represented by a particular document type. Currently, the following states – and their corresponding document types – are supported:

  • the Ordered state – represented by purchase orders and order changes
  • the Received state – represented by goods receipts ("ReceiptAdvice" in UBL)
  • the Billed state – represented by invoices and credit notes.

In the Tradeshift UI, these states (if applicable) are visible to both sender and recipient for each document line in the apps for invoices, orders and order changes:

The above is a simple case of an order with three lines against which an invoice with three corresponding lines is sent – no goods receipts are involved here, and hence no Received state. This can be visualised as follows:

This visualisation consists of three simple graphs, one for each order line. A graph is a visual representation of a network of related document lines, and the order lines at the bottom – on which each graph is based – are often referred to as the graph roots. So the case illustrated above involves two different documents (order 340 and invoice 565), two document types (order and invoice, colour-coded accordingly), two states (Billed and Ordered), six different document lines (each represented by a circle – three for each document, i.e. three matching line pairs), and three separate graphs outlining how these six document lines relate to each other.

The three graphs above are very simple, but seeing that any document can refer to multiple other documents at the same time, much more complex scenarios are possible. Below is an example of a scenario that includes multiple documents of different types:

This scenario involves eight different documents (order 340, order 800, invoice 90, goods receipt 49, goods receipt 234, goods receipt 400, order change 800, and credit note 12), five different document types (orders, order changes, invoices, goods receipts and credit notes, all colour-coded accordingly), three states (Billed, Received and Ordered), 18 different document lines (each represented by a circle), and five graphs outlining how these 18 document lines are related.

While this may appear complex – and to some extent actually is – the Tradeshift UI provides an intuitive in-app overview that makes it easy for users to navigate and collaborate on resolving disputes. If necessary, the graphs can also be extracted via API, either for any single document line or for all lines in a document. It is even possible to extract the graphs with a different base than the root (i.e. the order line) – all graphs can be extracted with any involved document (e.g. an invoice) as a base.

The overall flow

When a document of the supported type is sent to or received in a Tradeshift account, the document lines are extracted and inserted into the line-state-service database. The data captured and stored for each line includes line details such as item descriptions, quantities, amounts, units, tax arrays and prices, including base quantities, as well as information on how the document lines were allocated to the order line root (see more below). Header data is also replicated for each line, such as document profile, issue date and UUIDs for document, sender and recipient. Finally, metadata is captured as well, including information on when the document line was added to the service, and when the line graph was last updated.

Some invoice lines include order references, which makes the allocation of invoice lines to order roots straightforward. For example, this is the case when POs are flipped into invoices in the UI. Such PO references are not always available in the invoices though – and if not, the invoice lines must be assigned to order lines instead. This is done automatically using artificial intelligence – a process known as automapping.

AI automapping

Whenever an invoice is received, Tradeshift determines if all order and order-line references are present in the invoice UBL. If so, no AI automapping is needed, and the invoice will go straight through to the actual matching and approval flows.

However, as mentioned above, when PO references are missing in the invoice, the invoice lines have to be automatically assigned – or mapped – to order lines using AI. This is often the case with, for example, CloudScan VAN invoices and invoices that originated as paper invoices. For such invoices, Tradeshift will use any PO references at header or line level to identify and produce a list of orders in which the AI algorithm should look for likely order lines to pair with. The flow is illustrated in the diagram below:

The algorithm returns the most likely pairing of lines, taking into account various fields such as SellersItemIdentificationDescription and Unit price, along with a probability score indicating the likelihood of the pairing's correctness (either "Low" or "High"). Any order line references suggested by the algorithm will be used to build line graph relations and then stored in the line-state data model for future processing. The references are NOT added to the UBL of the legal document.

If the algorithm does not succeed in finding any PO references at all, the invoice will be regarded as a non-PO invoice and sent through the non-PO flow, which includes coding of the invoice.

Important note: Automatic invoice-line-to-order mapping is carried out independently on the buyer and the seller side, so there is a very small probability that the respective mappings could differ. However, it is assumed that sellers who do not provide line-level references rarely use the UI anyway, as they are most likely CloudScan, VAN or integrated sellers.