Order data

In this tutorial we will retrieve an order via REST. Based on this order you will learn how the order data that you retrieve is structured. We will first show you an example of a full response that you receive when retrieving an order. After this example response we will explain the fields and relations included in the response. The REST order documentation can be found here.

This call will get the order that has the ID 630. The complete response for this call is shown below. You can expand the box to see all data.

An order is divided into data that concerns the order as a whole and data that concerns only the items included in the order. The data that concerns the order as a whole is referred to as order data. The data that concerns the items included is referred to as order item data. The most common order item is an actual product. However, order items do not have to be products. An order item can e.g. also be an additional charge. The order data is subdivided into the following sections:

• order fields,
• amounts,
• properties,
• dates,
• address relations and
• references

The order item data is subdiveded into the following sections:

• order item fields,
• amounts,
• properties,
• dates and
• references

There are numerous order fields. You can find the complete list of all order fields in the order model documentation. 3 of the order fields are here explained in detail:

• typeId,
• locationId and
• lockStatus

The typeId describes the type of the order. The different order types represent different business cases. The most common type is the sales order. A sales order has the typeId = 1. All types available are:

• Sales order = 1
• Delivery = 2
• Returns = 3
• Credit note = 4
• Warranty = 5
• Repair = 6
• Offer = 7
• Advance order = 8
• Multi-order = 9
• Multi credit note = 10
• Multi delivery = 11
• Reorder = 12
• Partial delivery = 13

The locationId gives you the ID of the accounting location that is used for the order. Use this route the list the accounting locations of a client.

The lockStatus tells you whether an order is completely editable or not. If an order is locked, many fields can not be updated anymore. The following statuses are available:

• unlocked: The order is not locked and is completely editable.
• permanentlyLocked: The order is permanently locked (e.g. an order created by POS).
• reversibleLocked: The order is locked but can be unlocked again by certain actions. An order will be e.g. locked reversibly if an invoice document is generated. By creating a reversal document the order can be unlocked again.

The amounts relation provides information about the sums of an order as well as vat information for an order. The information is not provided by the user that creates an order. The amounts are rather calculated by using the amounts of the order items. The amounts relation always has an entry for the system currency. Additionally, an entry in a currency other than the system currency can be present. The amounts of an order are available in another currency, if the order items have entries in a currency other than the system currency. The order items have this other currency if the customer purchased in a currency that is not the system currency.

The vat information is provided in the vats entry. Within the vats entry the most important entries are countryVatId and vatField. Each combination of a countryVatId and vatField that is applied to one or more items in the order is listed once here.
The countryVatId shows you the id of a vat configuration. Each vat configuration applies to a certain country and that is why it is called countryVatId. Every vat configuration contains 4 vat fields and the vatField tells you which one of the four is valid. The vatRate shows you the actual percentage that is saved for the vat field. The value tells you the actual amount of money that was added from all order items that this combination of countryVatId and vatField was applied to.
The sum of all vat values for an order is saved in vatTotal.

The properties relation holds various order information. It has a simple key/value structure. The typeId is the key. This key is an integer and the value a string. Use this route to get all types. The shipping profile e.g. is stored in a order property (typeId = 2).

The dates relation works similarly to the properties relation, but stores dates instead of strings. Use this route to get all types.

The addressRelations relation stores the IDs of the addresses used for the order. There are always two addresses in an order, the billing address and the delivery address. The ID of the billing address is saved with typeId = 1 and the delivery address with typeId = 2.

There are two relations. These relations are sender and receiver. They show whether something is the source or the target. The combination of the referenceType, the referenceId and the relations will tell you exactly who send something and who received something. Let's take a normal sales order as example. In most cases the sender will be a warehouse and the receiver will be a contact. The referenceId will then tell you the exact warehouse and the exact contact. If we take a return as example then most likely both, the sender and the receiver, will have contact as referenceType. In the response example above we see a sales order. The sender is a warehouse and has the id 1. The receiver is a contact and has the id 104.

The orderReferences relation shows if an order is referencing another order. Currently the only referenceType is "parent". The parent order is the order that the actual order was derived from. E.g. a return is usually created from a sales order that contains the returned product. Therefore the return references the sales order. An example of such a reference relation is show directly below. The return in our example has the ID 101 and the sales order the ID 102:

"orderReferences": [{
    "id": 51,
    "orderId": 101,
    "originOrderId": 102,
    "referenceOrderId": 102,
    "referenceType": "parent",
    "createdAt": "2017-12-13T16:32:53+01:00",
    "updatedAt": "2017-12-13T16:32:53+01:00"
}]

The originOrderId specifies the first order in a chain of orders that were created one from another. Let's take a credit note as example. The credit note (ID 203) is referencing a return (ID 202) and this return is referencing a sales order (ID 201). This means that the origin of our credit note is the sales order, but the sales order is not the parent. The parent is the return.

"orderReferences": [{
    "id": 52,
    "orderId": 203,
    "originOrderId": 201,
    "referenceOrderId": 202,
    "referenceType": "parent",
    "createdAt": "2017-12-13T16:38:17+01:00",
    "updatedAt": "2017-12-13T16:38:17+01:00"
}]

The typeId specifies the type of the order item. The most common type is a variation. The ID an order item of the type variation is 1. Shipping costs are saved as an order item with typeId = 6. All types available are:

• Variation = 1
• Bundle = 2
• Bundle component = 3
• Promotional coupon = 4
• Gift card = 5
• Shipping costs = 6
• Payment surcharge = 7
• Gift wrap = 8
• Unassigned variation = 9
• Deposit = 10
• Order = 11

The referrerId describes where an order item comes from. Use this route the get a list of the referrers available in the system.

In attributeValues a string of the attribute value names is saved. A T-Shirt has the attribute values "size: xl" and "color: green". In this case the string is "xl, green".

The tax information is stored in the values countryVatId, vatField and vatRate. The countryVatId is the ID of a vat configuration in the system. Use these routes to get vat configurations. Each vat configuration has 4 vat fields. The vatField specifies one of the 4 vat fields of that configuration. Thus values from 0 to 3 are possible. vatRate is the concrete vat rate in percent.

The amounts relation provides information about the price of an order item. The amounts relation contains at least an entry for the system currency and can additionally have an entry in a currency other than the system currency. The price and the original price are both given in gross and net. The original price is the price without surcharges and discounts. The discounts can be given in percent or as an absolute values. Whether it is a percent value or an absolute value is indicated by isPercentage. The following formulas show the correlation between the price and the original price:

If isPercentage = false the price is calculated like this: priceGross = priceOriginalGross + surcharge - discount. The net price is calculated accordingly.

If isPercentage = true the price is calculated like this: priceGross = (priceOriginalGross + surcharge) * ((100 - discount) / 100). The net price is calculated accordingly.

The order item properties and dates relations work the same way the the order properties and dates do. The same types as for order properties and dates are used here.

The order item references relation is similar to orderReferences relation. Order items can reference other order items. Let's take a bundle as example. A bundle has components and these bundle component items reference the bundle item. The references relation of a component item is shown below. The bundle component item has the id 501. The bundle that the component is part of has the id 500.

"references": [{
    "id": 200,
    "orderItemId": 501,
    "referenceOrderItemId": 500,
    "referenceType": "bundle",
    "createdAt": "2017-12-13T16:32:53+01:00",
    "updatedAt": "2017-12-13T16:32:53+01:00"
}]