Order items are sub-components of orders, the goods that need to be specified and checked separately within an order. In other systems they can also be called "order lines", "positions", "goods" etc. Orders in MaxOptra can include one or more items that should be handed to a customer at the same time and place. For example, an order includes: 1 desk, 2 chairs and 1 armchair. All these items will share the same order reference number.
Also, order items are displayed in the driver mobile application (see Order Completion. POD Collection. Checking Order Items (Android app) and Order Completion. Collecting Signature (POD). Updating Amount. Checking Order Items (iOS) ), so that drivers can check the items' delivery, while working with orders.
Order Items Tab
If an order is large and consists of several items, each item can be specified in detail on a special Items tab of the Order form.
The Items screen consists of columns, such as:
Column | Description | Comment |
Name | Order item name as stated. For the identical goods, name can have the same values. | |
Description | Order item description, if necessary. | |
Barcode | Used to identify and confirm an order item by scanning the barcodes upon the delivery to the customer. The Barcodes scanning helps the dispatcher to monitor data on any specific order allocation or to identify the planned vehicle and its run that should deliver an order to a customer. | |
Status | Order item delivery status. For more details, see Tracking Order Items Completion. | Can be edited only by driver from Driver App |
Comment | Driver's comment about order item (if necessary). | Can be edited only by driver from Driver App |
Fail reason | Reason of non_delivery, taken from the Order Item Cancellation Reasons. | Can be edited only by driver from Driver App |
External ID | Order item's external identifier | |
Quantity | Planned order items' quantity as stated in the order form. | |
Actual quantity | Quantity that was actually delivered to the customer. | |
Price per unit | Price of each order item | |
Total price | Total amount of all order item units taken together. | This field is uneditable. It shows the product of Price per unit multiplied by Quantity |
Note At the bottom of the table you can see the planned total quantity and price. These values will not change even if the actual quantity and price of items are different from what was planned.
You can show or hide the columns you need using the
button in the right corner. The Visibility of columns dialog is opened, where you can enable/disable the parameters and change their order by dragging the bars.
You can also configure order items display in driver manifests and in PODs.
Creating Order Items
You can create order items in one of the three ways: manually, by csv-file import, or by MaxOptra REST API.
Manually
Click Add at the bottom of the Items screen. The New item form is displayed. Note that none of the parameters are mandatory.
Fill out the form and click Save to save the changes. To add more items, go through the whole procedure again.
You can also copy the newly created order items. To do it, select the item you want to copy and click the Clone button at the bottom of the screen.
A clone will be created, which you will further be able to edit.
Use the Delete button to delete the selected items.
Click Save after all the changes are made.
CSV-file Import
Information about order items in .csv import file should be provided in the orderItems column. To specify order items in the .csv-file properly, follow the rules:
The name of the item should be enclosed in square brackets – […],
The other order item information should be separated by vertical bars - |,
Different items are separated by a semicolon - ;.
The format is as follows: [Name]barcode|externalID|price per unit|planned quantity|description
For example: [Black Box]509361766273097|GD4561321|320|12|It's fragile
If you need to specify only a few parameters, but not all, leave the vertical bars without the data. For example, if I want to specify only name and quantity, the format will look like this: [Package 1]|||20| . You can omit the vertical bars coming after the last specified value, if nothing else is coming: [Package 1]|||20. Name can also be omitted: [ ]1234678||||fragile.
Note The same spelling format is used for order items in export files.
Also, see Order Import File Guide and Order Import File. Column Names and Requirements.
API Changes
In the save method, information about order items should be provided in the orderItems field of the API request. The orderItems section of the save method consists of the following fields:
Field name | Description |
name | Order item name (Should be unique per order) |
barcode | Order item barcode ((Should be unique per order)) |
externalId | Order item external identifier (if any) |
costPerUnit | Price of one unit of an item (e.g. piece, kg, box etc.) |
quantity | Planned quantity of order items within an order to be delivered. |
description | Additional information about an order item |
Notes
If an order has several items, each item should be written in a separate tag bracket.
The fields attribute Name and Barcode have to be unique identities on the order level. (per order)
None of the fields are mandatory.
<?xml version="1.0" encoding="UTF_8"?> <apiRequest> <sessionID>ccb48882378547909e3a26e75488e35c</sessionID> <orders> <order> <orderReference>Order123</orderReference> <areaOfControl>BeestonZone</areaOfControl> <date>08/05/2019</date> <client> <name>Customer1</name> <contactPerson>Gary Davis</contactPerson> <contactNumber>100000001</contactNumber> <contactEmail>[email protected]</contactEmail> </client> <location> <name>ACOMBPETS_YO26 4LT</name> <address>3 REGENT BUILDINGS,ACOMB,YORK, YO26 4LT</address> <latitude>53.9663582</latitude> <longitude>_1.1221</longitude> <isVerified>true</isVerified> </location> <dropWindows> <dropWindow> <start>08/05/2019 8:00</start> <end>08/05/2019 17:00</end> </dropWindow> </dropWindows> <priority>2</priority> <durationDrop>00:15</durationDrop> <capacity>100</capacity> <volume>200</volume> <collection>true</collection> <additionalInstructions>some additional instructions</additionalInstructions> <stopSequence>any</stopSequence> <orderItems> <orderItem> <name>Package1</name> <barcode>666666686454666</barcode> <externalId>test_1</externalId> <costPerUnit>50</costPerUnit> <quantity>10</quantity> <description>Leave in front of the door</description> </orderItem> <orderItem> <name>Package2</name> <barcode>666666686454777</barcode> <externalId>test_2</externalId> <costPerUnit>30</costPerUnit> <quantity>20</quantity> <description>Fragile</description> </orderItem> </orderItems> </order> </orders> </apiRequest>
The order items information is also provided in the API responses of the statistics gathering methods, such as: getOrderStatuses, getConsignment , getScheduleByAOCOnDate, getScheduleByVehicleOnDate , getScheduleByVehicleRun.
getOrderStatuses
The orderItems section of the getOrderStatuses method consists of the following fields:
Field name | Description |
name | Order item name |
barcode | Order item barcode (if any) |
status | Current order item status. Possible order item statuses: checked, not checked, added by driver, partially checked. |
externalId | Order item external identifier (if any) |
costPerUnit | Price of one unit of an item (e.g. piece, kg, box etc.) |
totalCost | Total price of all order item units |
quantity | Planned quantity of items within an order to be delivered. |
actualQuantity | Actual quantity of items delivered. |
description | Additional information about an order item |
failReason | Cancellation reason of an order item |
comment | Driver's comment |
Note Such fields as failReason, status and comment can only be updated by driver from Driver App.
<?xml version="1.0" encoding="UTF_8"?> <apiResponse version="2.0"> <orderStatusResponse> <orders> <order referenceNumber="1070773" status="FAILED" fullNotes="Incorrect address" /> <orderItem name="test1" barcode="CEARKF0000003001" status="NOT_CHECKED" costPerUnit="1" totalCost="10" quantity="10" actualQuantity="0" /> <orderItem name="test2" barcode="CEARKF0000003002" status="NOT_CHECKED" costPerUnit="1" totalCost="10" quantity="10" actualQuantity="0" /> </order> <order referenceNumber="1071088" status="CLOSED" /> <orderItem name="test3" barcode="CEARKF0000003003" status="CHECKED" costPerUnit="1" totalCost="10" quantity="10" actualQuantity="10"/> <orderItem name="test4" barcode="CEARKF0000003004" status="CHECKED" costPerUnit="2" totalCost="20" quantity="10" actualQuantity="20"/> </orders> </orderStatusResponse> </apiResponse>
getConsignment
The orderItems section of the getConsignment method consists of the following fields:
Field name | Description |
name | Order item name |
barcode | Order item barcode (if any) |
status | Current order item status. Possible order item statuses: checked, not checked, added by driver, partially checked. |
externalId | Order item external identifier (if any) |
costPerUnit | Price of one unit of an item (e.g. piece, kg, box etc.) |
totalCost | Total price of all order item units |
quantity | Planned quantity of items within an order to be delivered. |
actualQuantity | Actual quantity of items delivered. |
description | Additional information about an order item |
failReason | Cancellation reason of an order item |
comment | Driver's comment |
Note Such fields as failReason, status and comment can only be updated by driver from Driver App.
<?xml version='1.0' encoding='UTF_8' standalone='yes'?> <apiResponse version="1.0"> <consignmentResponse> <consignments> <consignment consignmentReference="4366700843117298688"> <orders> <order referenceNumber="mID5205913" linkType="PND" status="NEW"> <orderItem name="test1" barcode="1008105964500552" status="NOT_CHECKED" costPerUnit="0" totalCost="0" quantity="0" actualQuantity="0" /> <orderItem name="test2" barcode="2521250862053500" status="NOT_CHECKED" costPerUnit="0" totalCost="0" quantity="0" actualQuantity="0" /> </order> <order referenceNumber="mID5205917" linkType="PND" status="NEW"> <orderItem name="test3" barcode="54654532583386658" status="NOT_CHECKED" costPerUnit="0" totalCost="0" quantity="0" actualQuantity="0" /> <orderItem name="test4" barcode="54561646465455" status="NOT_CHECKED" costPerUnit="0" totalCost="0" quantity="0" actualQuantity="0" /> <orderItem name="eqw" barcode="eqweqw" status="NOT_CHECKED" costPerUnit="0" quantity="0" /> </order> </orders> </consignment> </consignments> </consignmentResponse> </apiResponse>
getSchedulesByAOCOnDate, getScheduleByVehicleOnDate and getScheduleByVehicleRun
These three methods are combined in one group, as their responses have the same structure. The orderItems section of these three methods' response structure consists of the following fields:
Field name | Description |
name | Order item name |
barcode | Order item barcode (if any) |
status | Current order item status. Possible order item statuses: checked, not checked, added by driver, partially checked. |
externalId | Order item external identifier (if any) |
costPerUnit | Price of one unit of an item (e.g. piece, kg, box etc.) |
totalCost | Total price of all order item units |
quantity | Planned quantity of items within an order to be delivered. |
actualQuantity | Actual quantity of items delivered. |
description | Additional information about an order item |
failReason | Cancellation reason of an order item |
comment | Driver's comment |
Note Such fields as failReason, status and comment can only be updated by driver from Driver App.
<?xml version='1.0' encoding='UTF_8' standalone='yes'?> <apiResponse version="1.0"> <scheduleResponse> <units timeZone="Greenwich Mean Time" timeZoneOffset="GMT+0:00" currency="GBP" distanceUnits="MILE" speedUnits="MILES_PER_HOUR" durationUnits="MINUTE" weightUnits="Kg" volumeUnits="m3"/> <vehicles> <vehicle id="30281" name="!cup" driverName="!cup" driverPhone="+201904251904" driverExternalID="!cup" externalID="!cup" costByDistance="1" vehicleActivationCost="0" costPerOrder="0" maxWeight="1" maxVolume="1" aocId="190"> <run runDay="20/05/2019" runNumber="1" planDistance="100.38" factDistance="" planDuration="454" factDuration="10" runStartTime="20/05/2019 01:00" runEndTime="20/05/2019 08:34" runLoadingEndTime="20/05/2019 01:10" availabilityStartTime="20/05/2019 01:00" availabilityEndTime="20/05/2019 22:59" planWeight="0" planVolume="0" weightUtilization="0" volumeUtilization="0" cost="100.38"> <location locationType="PICKUP" name="ChippenhamZone" address="ChippenhamZone" latitude="51.391494" longitude="_2.070923" planArrivalTime="20/05/2019 01:00" planDepartureTime="20/05/2019 01:10" factArrivalTime="" factDepartureTime=""planMileage="0" mileage="0" factMileage="" factDuration="" planDrivingTime="0" factDrivingTime="" planStopDuration="10" factStopDuration="" estimatedArrivalTime="" estimatedDepartureTime=""/> <location number="1" locationType="DROP" name="Primrose Hill 28, Bath, England, BA1 2, GB" address="Primrose Hill 28, Bath, England, BA1 2, GB" latitude="51.395717" longitude="_2.376594" planArrivalTime="20/05/2019 01:58" planDepartureTime="20/05/2019 02:11" factArrivalTime="" factDepartureTime="" planMileage="17.5" mileage="17.5" factMileage="" factDuration="" planDrivingTime="48" factDrivingTime="" planStopDuration="13" factStopDuration="" estimatedArrivalTime="" estimatedDepartureTime=""/> <location number="2" locationType="DROP" name="!cup" address="Sanham Green Farm Cottages 1, Sanham Green, RG17 0RS, United Kingdom" latitude="51.399206" longitude="_1.516113" planArrivalTime="20/05/2019 02:14" planDepartureTime="20/05/2019 03:57" factArrivalTime="" factDepartureTime="" planMileage="29.1" mileage="29.1" factMileage="" factDuration="" planDrivingTime="64" factDrivingTime="" planStopDuration="103" factStopDuration="" estimatedArrivalTime="" estimatedDepartureTime="" isVerified="false"/> <location number="3" locationType="DROP" name="Chilswell Lane, Oxford, England, OX1 5, GB" address="Chilswell Lane, Oxford, England, OX1 5, GB" latitude="51.726228" longitude="_1.286245" planArrivalTime="20/05/2019 04:45" planDepartureTime="20/05/2019 04:58" factArrivalTime="" factDepartureTime="" planMileage="50.1" mileage="50.1" factMileage="" factDuration="" planDrivingTime="215" factDrivingTime="" planStopDuration="13" factStopDuration="" estimatedArrivalTime="" estimatedDepartureTime=""> <order orderReference="mID5662073" orderId="5662073" status="ALLOCATED" task="DROP" duration="0" weight="0" volume="0"> <orderItem name="test" barcode="123456" status="NOT_CHECKED" costPerUnit="0" totalCost="0" quantity="0" actualQuantity="0"/> <aggregatedItemsStatus actualDelivery="0" scheduledDelivery="1" completionStatus="NOT_DELIVERED" /> </order> </location> </run> </vehicle> </vehicles> </scheduleResponse> </apiResponse>
Tracking Order Items Completion
To view order items on the Track&Trace screen, click the
icon in the Orders column.
The order item completion progress can be tracked using th Actual/Planned items column, which shows the actually delivered vs total planned items within an order.
Order Items Completion Statuses
Depending on the completion progress, order items can have several possible completion statuses, which can be updated by the drivers in their Driver Apps:
Received by customer – order item successfully delivered;
Not received by customer – order item not delivered;
Added by driver – new order item was added;
Partially checked – only some order items were delivered.
Order items and their completion statuses are displayed in the Order form, in the driver manifest, in POD and in the Order items delivery report. The items' statuses are also available for the mentioned API methods (see above).
Order Completion Statuses
In the situation that some order items within an order are partially delivered or not checked, the order itself is still considered completed, but it will acquire an additional completion status. This indicates to the dispatcher that not all items of this order have been delivered successfully.
Depending on the items status, an order may have one of the three completion statuses:
Not delivered;
Fully delivered;
Partially delivered.
The order completion status is displayed in a separate column on the Track&Trace screen, called Completion status.
To search orders by their completion statuses, the filter Completion status filter is available in the upper part of the T&T screen.
Note The completion status parameter is only available if you have the order items feature enabled for you. If you need to have it, contact the MaxOptra Support Team.
Cancelling Order Items
During delivery, some order items can be cancelled. To register the cancelled items, the Order item cancellation reasons are available on the Settings tab under the Account Administrator role.
For more information, see Order Item Cancellation Reasons .
Order Items Delivery Report
Order item details and completion statuses can be viewed and analysed using the Order items delivery report.
Working with Order Items on Driver Application
To enable a driver to add and edit order items in the Driver App, contact the MaxOptra Support Team.
For more details on how to work with order items on driver application, see: Order Completion. Collecting Signature (POD). Updating Amount. Checking Order Items (iOS) and Order Completion. POD Collection. Checking Order Items (Android app).