Our domain model
The Loaded API's primary purpose is to synchronise Point of Sale (POS) data with Loaded in near real-time. The data received by Loaded is used to power functionality providing our customers with insight into the profitability of their business. This means as an API client you're going to be sending data into the Loaded system as and when things occur within the POS itself.
Here's a simple overview diagram of the model that is used in the API, it shows the Order object type in the center from which other types fan out from.
Order lifecycle
The Order in Loaded represents the whole lifecycle of a customer initially requesting items (e.g. at a counter, or taken by floor staff), through any changes such as more items being requested or items being voided, and finally concluding when payment is made. Instead of having separate entities for these operations the Order uses statuses that move through toward 'final' values that represent that no further changes will occur.
The following diagram shows the statuses that Orders can transition through (blue background) and finish in (grey background).
As well as Order statuses there are separate statuses that belong to the Items that were ordered. These are used to track when things that were ordered may not have been paid for, e.g. because of a mis-order, or similar.
Within Loaded, users are able to run reports that differentiate between orders and sales. The data you send to Loaded via the API ultimately ends up presented in these reports. In simple terms an order in Loaded is something that a customer has requested, and a sale is something that was requested and eventually paid for. Everything starts out as an order, and transitions to a final state that normally has a matching payment. The statuses used on Orders and OrderItems in the API data are used to determine what should appear in these reports - i.e. the statuses are very important for accurate reporting!
Tenders, voids, and refunds
At the end of the day we're expecting customers to pay for what they have ordered! The Order model holds an array of Tenders which represent the payments that get made. In the happy path everything that is ordered is fully paid for. In the real world though mistakes are made, items may be incorrectly ordered, things may need to be refunded after payment was originally taken, etc.
The statuses on the Order and OrderItem objects managed via our API are used to track this information.
Loaded uses the tenderedAt time of the Tender as the sale time for reporting purposes.