Order entity
The order entity can represent a Purchase or a Return, which are referred to as the Order type. Each order has several Order header attributes, which apply to the order as a whole, and Order Line items to describe the individual goods or services involved.
 |
Figure 2. Order object structure
Attribute or group | Definition |
|---|---|
Order header | The Order header must include the order ID (a unique identifier of the order) and some contact identifiers to connect the order to a contact. Other mandatory attributes are status, currency code and total price. |
Order ID | The order ID is defined by the client’s system and must be unique. The order ID is used to get, update and delete a previously registered order. |
Order type | The order type may be "purchase" or "return" but this is not specified in by the client. Instead, it is calculated based on the line item types and the following rules:
|
Order status | For Engage to understand the life cycle of the order it is required to maintain and update the status property when it changes. An order is always in one of these three predefined statuses:
Two actions are also connected to the order state, and you will see these turn up in responses. These are ConfirmOrder and ConfirmDelivery. |
External order status | The external order status is optional. It is the client’s interpretation of the order status. The external status is not restricted and completely open for the clients to define for themselves. The external status will be shown in order view and can be used in segmentation. |
Created at | This should be the date and time the order was placed in the client’s system. If omitted, it will be the registration time in Engage. |
References | Using references, you can refer to another order by its order ID. This could be used, for example, to link a return order to its original purchase order. |
Currency | Currency is mandatory and only one currency code can be given which then applies to the whole order. The currency code should be specified according to ISO 4217. |
Payments | Payments can be registered, and if used it is mandatory to define the method. See Swagger for the allowed payment methods |
Order line item | An order includes one or multiple order line items, defining the different goods or services in the order. A line item always includes item id (SKU), quantity and price and it may also include information about discount, tax and article description. The type tells you if the line item is a purchase or return (if omitted the default is "purchase"). The amount given in “line-item total” should be the total net amount with discounts and taxes included for that line, meaning that if quantity is more than one, all items are included int the total. |
Return details | Return details are optional and used to describe the return reason (free text) and return type, to distinguish between normal returns, exchanges and complaints. |
Discounts | Discounts may be registered and this may be done on both order header level and/or line-item level. The discount type is optional. See Swagger for allowed values. |
Taxes | Tax can be registered on both order header level and line-item level. See Swagger for allowed tax types. |
Fees | It is possible to register fees separate from line items, such as shipping fee and administration fee. |
Order status
Be aware that there are two types of status:
The Engage status on order level, either "in progress", "completed" or "cancelled".
The optional “external status” on order level and line-item level which the clients can use in whatever way they want. The external status in the API is named as “Status detail” in the GUI.