Payment/Invoice info - Githubissues

jellevanleeuwen commented 3 years ago

Type of request

[ ] I'd like to add something to the OTM 5 spec

Is your feature request related to a problem? If so, please describe the problem. For example: with the current specification I cannot model the payment and invoice information needed to cross borders.

Describe the solution you'd like I would like to specify the finance/invoice aspects that has to do with my shipment and transport orders.

Describe alternatives you've considered Currently, I am using an external attribuut on goods, in which i specify the price of the goods, based on this i can create invoicelines.

Additional context Add any other context or screenshots about the feature request here.

bmeesters commented 3 years ago

Hello again Jelle, thanks again for your contribution. Could you give an example in how you would like the OTM to look like? Is it only the price that you are missing?

I think adding this type of information would be a valuable addition to OTM.

jellevanleeuwen commented 3 years ago

For the client i am working for, it will be sufficient to add price information to goods like we do with weight and grossweight, so we can fill in an amount and a currency and maybe also the unit the amount accounts for.

Further, you maybe want to make a difference between grossprice and net price, and maybe also want to add taxrate

So something like: "price": { "unit": "KG", "grossvalue": 15.00, "taxrate": 21.00 "Net Value": 18.15 "Currency": "Euro" },

bmeesters commented 3 years ago

Thanks, that seems like a valuable addition. I'll be sure to discuss it and get back on a more concrete proposal.

thomaskolmans commented 3 years ago

In that proposal, please do not use doubles for amounts but an integer as in "cents". This will simplify conversion and ensure that values can't be interpreted in a faulty manner. At least, as much as possible as money values are generally quite important that they are standardised and communicated properly.

bmeesters commented 3 years ago

I think that is a valid take on how to deal with currency. However I am not sure whether companies ever need to split cents? Because that use case becomes impossible then.

We can also say that that is such an exception that it should not 'pollute' the standard.

BobZuidhoek commented 3 years ago

Jelle, can you further specify what you are doing in your use case? I'd like to understand this from the use cases I have going within our own companies (we are shippers of goods).

If this is for export purposes? If so, things become more difficult because you have to declare the value of goods, which could be something different than stating the commercial sales price. The commercial sales price can include transport cost or not (depending in IncoTerm agreed with your client). The goods value should be agnostic to these things. In some cases, goods value and commercial sales value are the same, but that is not necessarily the case.

So can you clarify how you are using this? And from what role (shipper, carrier)?

It could be that all this will already be covered in this issue "Add node to Goods for Goods code classification structure #26".

bmeesters commented 2 years ago

Reviving this after question of @rvanweegberg, who proposed:

"TotalInvoiceAmount": {
  "gross price": 605.00,
  "VAT rate": 21.00,
  "net price": 500.00,
  "currency": "EUR"
},

BobZuidhoek commented 2 years ago

It's still a bit unclear to me what the OP is trying to do. As bmeesters is asking for input, I'll just put an info-dump here to pick from for yourselves.

First, note the complexity of how a client may get invoiced commercially vs how delivery (consignments) takes place...

The simplest example is where a consignment is equal to a commercial invoice (i.e. everything of an invoice gets delivered in that consignment). In such a case, each consignment goods line can be strongly connected to a commercial invoice line. If it's very very very straighforward, then 1 consignment goods line = 1 commercial invoice goods line.
You can already start to make this example more complex as following: you could have the situation that 1 consignment goods-line relates to 1 or more commercial invoice lines. For example, a consigmnent goods line is 5 boxes of "exclusive chocolotates". On the commercial invoice, these could actually be 25 invoice lines stating the different types of exclusive chocolates (and their prices and their quantity) that in total make up the contents of the 5 boxes,

A different view in complexity is when a consignment and invoice become more loosely connected. For example, a client orders 50 pallets of bananas in 1 purchase order. You pack 2 deliveries (consignments) of 25 pallets each. Invoicing-wise, you mostly see either of these situations:

The client is invoiced for each delivery. Hence, the client gets 2 invoices, which he reconciles with his total order.
The client is invoiced for the total delivery of the order. Hence, the client gets 1 invoice.

Another complexity: a consignment may contain several orders and therefore several underlying (partial or not) commercial invoices. Even more complex: many orders may be combined into several consignments (by which every consignment ships a portion of an order).

What I'm trying to say is: it is very common that a consignment is not straightforwardly connected to only 1 commercial invoice.

Now onto some other things:

True digital invoices (such as UBL XML) have a layered approach: invoice header 1:n invoice main-lines 1:n invoice specification-lines.

You could think about adding invoice line quantity and invoice line price (and then net amount as a result of that).

In many high volume / small margin industries, prices and line amounts are specified more granularly then cents.

It could also be that the consignment goods line product description (=usually more generic) is different from the the invoice line goods description (=usually very specific).

Invoices have dates that may be relevant to add or not (e.g. issue date, due date, etc).

Invoices have types of parties (supplier, buyer, payee, etc). These could be identified using a GLN-number.

Invoices have an invoice number. Preferably, invoice lines are uniquely numbered as well.

Regarding VAT:

It is usually good practice to state the invoice line tax base amount, the applicable VAT-% and the calculated VAT amount.
Watch out with scenario's where there is no VAT. There are technical differences between VAT 0% and reverse charged VAT ("verlegde BTW").

Invoice lines can have references to other documents, the most important one being a purchase order (line)

Delivery conditions (Incoterms code, place, Incoterms version reference) are usually part of the invoice header for invoice with physical goods (i.e. not services).

So depending on what you're trying to achieve, some of the above may be relevant or not.

bmeesters commented 2 years ago

I want to revive this discussion again since invoices are an important part of logistics. The reason this has lingered for a while is that the subject is incredibly complex and with all the variants it could become a standard on its own. So my recommendation is that we either include a known standard and support that, or start simple and incrementally extend if the need is big enough. My guess is that offering something is already value to just (ab)using external attributes. I am not aware of a good standard, so I'll start with a proposal for option 2.

Some principles that I try to incorporate:

prices comes in value-with-units to be consistent with the complete OTM5 spec. Since even cents are split I don't think we can rely on integers for numbers (@thomaskolmans, unless you have any suggestions how to deal with this?)
We need some layering to model some of the situations @BobZuidhoek is describing). So I think we can add something like a invoice entity, that again has invoiceSpecificationLines.
The invoice has not much more than a description and a list of specification lines. You would want actors I suppose, but to avoid getting the same problem as consignments vs transportOrders on where to put the actors I propose that we can only add them to the lines (tradeoff repetition vs consisteny).
The lines each also have a remark, description and actors that belong to that line. And some complex type price, that has a type (rate vs absolute), value (value-with-unit) and grossValue (to mimic weights).

The end result could then look something like:

{
  "entityType": "financialValue", // for example for goods value and not just invoices
  "id": "<some uuid>",
  "externalAttributes": {
    "orderId": "1234
  },
  "creationDate": "23-02-2022T10:00Z",
  "description": "this is the invoice for the goods you just ordered",
  "remark": "please in time",
  "classificationLines": [
    {
       "description": "transportCosts",
       "price": {
          "type": "absolute",
          "netValue": {
              "value": 500.00,
              "unit": "EUR" // ISO code list
           }   
          "grossValue": {
              "value": 605.00,
              "unit": "EUR" // ISO code list
           }
       }
    },
    {
       "description": "extra costs",
       "price": {
          "type": "rate",
          "rate": {
              "value": 100.0,
              "unit": "perHour"
          }
       }
    }
  ] 
}

Any thoughts? Would (something like) this be sufficient? I can imagine we might want to associations to goods themselves? Or is better to come with a very elaborate proposal (at the risk of delaying it even more)?

rvanweegberg commented 2 years ago

I think it is a good idea to start simple. For me it is OK for now if we start with an invoiceentity which is available for consigments. I will discuss internally if mentioned result is OK for us.

woutvandenheuvel commented 2 years ago

I suggest to use the term tariff instead of invoice. The entity 'tariff' can be linked to consigments or trips or even actions. The description could be: 'the agreed tariff' This will be a lumpsum amount. As start I suggest to use two types of tariffs: 1) tariff for transportation costs and 2) tariff for additional costs such as surcharges, documenatation, extra stops etc

robindirksen1 commented 2 years ago

@woutvandenheuvel for our use case (outsourcing of orders in the recycling industry using containers - so an entity under the TransportOrder) we would like to send the price (in this case: predetermined price agreements) using OTM.

"price": {
   "type": "absolute",
   "netValue": {
       "value": 500.00,
       "unit": "EUR"
   },
   "grossValue": {
       "value": 605.00,
       "unit": "EUR"
   }
}

bmeesters commented 2 years ago

@woutvandenheuvel any idea on how to proceed with this ticket as it has been open for a while?

bmeesters commented 2 years ago

We have been discussing this topic for a while and ultimately come to the conclusion that invoice information is definitely related to logistics, but is not part of the logistical operation. There are many variations and various parties would likely have their own invoice system. Sharing invoices could be its standard on its own. There is always to the option to use the external attributes if necessary.

However, we recognize that the value of the goods to be transported are part of the logistic operation in the same way that the dimensions and the classification lines are. So we want to enable to provide a price like type to goods and/or consignments.

@rvanweegberg & @thomaskolmans would this work for you as well?

thomaskolmans commented 2 years ago

Yes I 100% agree with this thought and approach.

rvanweegberg commented 2 years ago

Yes, for me that is sufficient.

thomaskolmans commented 2 years ago

I seem to have changed my mind slightly this evening. I still think the approach is good but what about cost elements? Think: fuel cost in a trip? Toll cost in a trip/consignment/etc? Isn't that also directly related to transport?

bmeesters commented 1 year ago

Sorry for responding late @thomaskolmans. I think this will remain a gray area. Toll and fuel costs might be closer to the operation than driver costs, but I would also say they are less relevant for customs than the actual goods properties. So, I think it might be better to simply omit them unless there are very clear use cases. Since OTM5 does allow for custom extensions you can always add it if necessary.

{
  "entityType" "trip",
  "id": "<some UUID",
  "externalAttributes": {
    "tollCost": {
      "value": 10,
      "unit": "euros"
    }
  }
}

Ultimately the domain of traffic and logistics is huge and we need to find some balance in enabling standardization but also keeping the specification manageable. I would say that toll, driver and other costs are mostly important for the invoice, and therefore not part of OTM, which is more concerned with the operation itself. Though again, I think this is a gray line that can be argued both ways.

I think the best course of action is to close this ticket, since we are not going to add invoice information. And add a new one for just the goods costs.

bmeesters commented 1 year ago

I created this ticket to replace the current scope: https://github.com/opentripmodel/otm5-change-requests/issues/68

Naturally, we can always reopen this ticket if we change our minds

thomaskolmans commented 1 year ago

I agree but I at least wanted to introduce the thought.

opentripmodel / otm5-change-requests

Payment/Invoice info #21