Uploading multiple orders?

If the use case is to upload multiple orders at once, it's recommended to only upload one file with multiple orders in it.

JSON files are preferred.

Data is sent in the body as multipart/form-data


.Remember to use correct content-type and mimetype

Data should be sent as a JSON file with the following mimeType: application/json

Batch file required

A JSON file containing the payload (remember the correct mimetype) and Data is sent in the body as multipart/form-data

Table of Contents

  1. Introduction
  2. Where to find required keys
  3. Property descriptions
    3.1. origin, destination, sender, receiver
    3.2. timeWindow
    3.3. timeType
    3.4. lock
    3.5. address, zipCode & city
    3.6. ruleset
    3.7. coordinates
    3.8. cargo.services
    3.9. cargo.barcode
    3.10. pickuped
    3.11. customFields
    3.12. sendSMS & smsSettings
  4. Schema
  5. Examples

1. Introduction

This API is used to batch upload one or more orders into the Wuxus platform.

Uploads a file with multiple orders. The file must be a JSON file meeting the model or an XLSX file in accordance with the template, which can be found on the page Find Transport -> Upload file in the Wuxus platform.

JSON files are preferred. The size is smaller, the handling is faster and more robust, since it does not need converting first. If the file is a JSON the mimeType MUST be application/json. Orders will be created with the uploading company(user) as creator and with the user matching the contract key in the file as the performing hauler. If the contract key is not present or does not match, the orders will be assigned to the uploading user instead.

Data is sent in the body as form-data.

Progress monitoring

You can check the progress of the orders uploading when you upload orders. When you make a request to the batch upload and it's a success (check above for the 200 OK example), you will get a batchFileId out. You can use this, to make a request to Batch upload status to check for the progress.

2. Where to find required keys

The require keys can be found in the same place where the APIkey can be found, on the page "File upload" under "Orders".

The contractKey is used in the JSON file or the Excel file, to determined which of companies you have contracts with, should received the order.

3. Property descriptions

Some properties/keys need a more thorough description, which follows here.

3.1. origin, destination, sender, receiver

origin (required)Is where the goods will be picked up.
destination (required)Is where the goods will be delivered.
sender (optional)Is the entity that is responsible for the shipping of the goods.
receiver (optional)Is the entity that is responsible for the receiving the goods.

3.2. timeWindow

If no timeWindow object is present, timeframe will be defined as "Whenever".
timeWindow consists of the following fields: start, end, timetype & lock.

3.3. timeType

anytimeIs used to keep the timeframe as only a date - this requires start to be filled.
beforeIs used to keep the timeframe on a date, before a given time - this requires end to be filled.
afterIs used to keep the timeframe on a date, after a given time - this requires start to be filled.
betweenIs used to keep the timeframe on a date, between two given points in time - this requires both start and end to be filled.


Date time format

All the date times needs to be converted from local time, to UTC ISO-8601 format. For example:
The time in Denmark is 2022-12-24T15:30:00Z which will be 2022-12-24T14:30:00Z in UTC ISO-8601 format.

3.4. lock

lock is used to highlight the timeframe within the Wuxus platform. We recommend using this for anything out of the usual or highly important, and not on all timeframes.

3.5. address, zipCode & city

Wuxus validates and fetches GeoCode data for addresses using Google Maps APIs. Therefore an address must be of a Google Maps valid format, to be properly recognised by Google Maps.

If an address is not recognised by Google Maps, Wuxus marks the address with a geoWarn flag, which informs users that there is an issue with the address. This creates extra work for the dispatchers as they need to correct the address to get reliable delivery time estimations.

In most cases this issue is due to extra address information being added in the address field, such as 'Gate 4' or '2. floor right'. To help minimise the number of geoWarns in the system we recommend that all extra address information is added to the extraInfo field whenever possible.

3.6. ruleset


This should be ignore as standard. It's only available if you have new Route functionality enable

This is only for origin and destination
This define what ruleset that should be used for either origin or destination.
An example:

  "ruleset": {
    "rulesetId": "588ef4a2ccf9b6fd37f14561",
    "name": "Name of the ruleset

The name is the name of the ruleset that you have created in the system.

3.7. coordinates

If you have your own coordinates for an address that you want to use, you can specified them in the coordinates object. This can be added to origin, destination, sender and receiver: An example:

  "coordinates": {
    "lat": 55.736501,
    "lng": 12.398360

3.8. cargo.services

Array String

A piece of cargo can have from zero to multiple services. The choice of services are limited to the list below. Send each desired Service ID as a String in the services array.

Service TypeService ID
Carry-down 2-man588ef4a2ccf9b6fd26e38936
Return carry-down5912e2e802bdd2626ba7ebf7
Return carry-down 2-man5912e2f402bdd2626ba7ebf8
Curbstone Delivery5912e2bb02bdd2626ba7ebf5
Delivery vehicleside5912e2db02bdd2626ba7ebf6
Carry-up 2-man588ef5c7ccf9b6fd26e38939
Installation 2-man588ef5f5ccf9b6fd26e3893b
Manual service5954f19d259c6e114a8f1c33
Unknown service5912f89202bdd2626ba7ebf9

3.9. cargo.barcode

Each item can have one barcode. Any barcode can be added as a string, but we only support the following in the app:

  • UPC-A
  • UPC-E
  • Code 39
  • Code 93
  • Code 128
  • EAN-8
  • EAN-13
  • QR
  • Data Matrix

3.10. pickuped


An order is built up as both a pickup and a delivery task. In some distribution situations the users only consider deliveries as a single task, with a collection at a hub.

This property is used to adjust where the order is in the proces. It is mainly used for orders of the type "distribution". By setting this property to true, the order is "already considered picked up", meaning that only a delivery task remains.

3.11. customFields

Object String

An order can have customFields, which is key-value. key describe the information, value is the information. An example could be:

"customFields": {
	"specialTransport": "Computers"

customFields can contain following:

StringCan contain any string.
DateShould be in UTC ISO-8601 format. Will be shown as the web clients local time on the website.
NumberCan contain any number.
Checkbox (boolean)Is an boolean. The web client will see this as an checkbox

3.12. sendSMS & smsSettings

This will be set under origin and destination.

sendSMS is a flag needed to be set to true to be able to send SMS. smsSettings contains all the different types of SMS that can be send. The list is following:

driveNowThis will send a SMS when the driver is starting the trip
(can be set on both origin and destination)
taskStatusThis will send a SMS when activating task status
(can be set on both origin and destination)
deliverOrderThis will send a SMS when the order have been delivered successful
(can be set only on destination)
deliverOrderFailedThis will send a SMS when the order have not been delivered successful
(can be set only on destination)
  "sendSMS": true,
  "smsSettings": {
    "driveNow": true,
    "taskStatus": true,
    "deliverOrder": true,
    "deliverOrderFailed": true

4. Schema

This is a basic guide to indicate how to use the API.

JSON Schema

Version 1.0


Test your JSON with this schema

Input your JSON in the right side.
JSON schema list

Alternate guide


5. Examples

Minimal example


Full example


Postman examples

You need to add your API key in headers sections, and select the file you want to upload.

The export is pointed to the staging environment, but it's just changing the URL to change the environment.

Postman export

Click Try It! to start a request and see the response here!