Order

_{Estimated reading time: 11 minutes}

Overview

The Order RestAPI allows you to manage orders within the Fleet Management system. You can create, retrieve, update, and delete order records. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently.

Order Object Fields

Field	Type	Description
`id`	Integer	Unique identifier for the order.
`customerInfo`	Object	Customer details linked to the order. Cannot be changed once saved.
`location`	Object	Location details of the order.
`alias`	String	Short name or identifier for the order.
`firstName`	String	First name of the customer.
`lastName`	String	Last name of the customer.
`address`	Object	Address details of the order.
`phoneNumber`	String	Contact number for the order.
`customData`	String	Additional order-specific data.
`type`	Integer	Order type: `0` - Pickup `1` - Delivery
`status`	Integer	Order status: `0` - Unscheduled `1` - Scheduled
`state`	Integer	Order state: `0` - None `1` - On Route `2` - Servicing `3` - Rejected `4` - Completed `5` - Failed
`priority`	Integer	Order priority: `0` - Low `1` - High
`numberOfPackages`	Integer	Number of packages in the order.
`weight`	Float	Total weight of the order.
`cube`	Float	Total volume of the order.
`timeWindow`	Object	Time window during which the order should be serviced.
`serviceTime`	Integer	Time (in seconds) required to complete the order.
`revenue`	Float	Revenue associated with the order.
`depotId`	Integer	Depot associated with the order.
`creationTimestamp`	Integer	Timestamp of when the order was created.

Endpoints

1. Create Order

Description: Adds a list of orders to the database.

Method: POST
Endpoint: /orders
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/orders
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	The order’s customer was not found/doesn’t exist. The order doesn’t have the coordinates set. The time window format is wrong. The number of packages/weight/cubic volume has a negative value or exceeds the maximum limit. The orders’ phone number has wrong format.
`401 Unauthorized`	API key is missing or invalid.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Note

If the operation is successful, the Order object will have its id field populated. If the operation fails, an error code is returned, which can be interpreted as described in the Returned error codes section.

Example:

Request Body:

[
  {
    "customerId": 1838721,
    "location": [
      48.870852,
      2.356148
    ],
    "alias": "Magic Order",
    "firstName": "Magic",
    "lastName": "Order",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "phoneNumber": "+1202555018",
    "customData": "",
    "type": 0,
    "status": 0,
    "state": 1,
    "priority": 0,
    "numberOfPackages": 3,
    "weight": 5.1,
    "cube": 2.5,
    "revenue": 12,
    "timeWindow": [
      420,
      1086
    ],
    "serviceTime": 0,
    "depotId": 0
  },
  {
    "customerId": 1838722,
    "location": [
      48.827865,
      2.379216
    ],
    "alias": "Magic Order2",
    "firstName": "Magic2",
    "lastName": "Order2",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "phoneNumber": "+1202555019",
    "customData": "",
    "type": 0,
    "status": 0,
    "state": 1,
    "priority": 0,
    "numberOfPackages": 2,
    "weight": 4.5,
    "cube": 1.1,
    "revenue": 16,
    "timeWindow": [
      420,
      1086
    ],
    "serviceTime": 0,
    "depotId": 0
  }
]

Response Body: (error code 200)

{
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1751445531350,
      "customerInfo": {
        "id": 1838721,
        "alias": "Magic Customer",
        "firstName": "Magic",
        "lastName": "Customer",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.870852,
        2.356148
      ],
      "alias": "Magic Order",
      "firstName": "Magic",
      "lastName": "Order",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555018",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "revenue": 12,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    },
    {
      "id": 879888,
      "creationTimestamp": 1751445531350,
      "customerInfo": {
        "id": 1838722,
        "alias": "Magic Customer2",
        "firstName": "Magic",
        "lastName": "Customer2",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer2@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.827865,
        2.379216
      ],
      "alias": "Magic Order2",
      "firstName": "Magic2",
      "lastName": "Order2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555019",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 2,
      "weight": 4.5,
      "cube": 1.1,
      "revenue": 16,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

2. Get All Orders

Description: Fetches a list of all orders with optional filtering.

Method: GET
Endpoint: /orders
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/orders
Query Parameters:
- search (string, optional) – General search term across orders.
- id (string, optional) – Filter by order ID (id=value:exact for exact match).
- alias (string, optional) – Filter by order alias (alias=value:exact for exact match).
- firstName (string, optional) – Filter by first name (firstName=value:exact for exact match).
- lastName (string, optional) – Filter by last name (lastName=value:exact for exact match).
- location (string, optional) – Filter by location (location=value:exact for exact match).
- country (string, optional) – Filter by country (country=value:exact for exact match).
- state (string, optional) – Filter by state (state=value:exact for exact match).
- county (string, optional) – Filter by county (county=value:exact for exact match).
- city (string, optional) – Filter by city (city=value:exact for exact match).
- postalCode (string, optional) – Filter by postal code (postalCode=value:exact for exact match).
- streetName (string, optional) – Filter by street name (streetName=value:exact for exact match).
- streetNumber (string, optional) – Filter by street number (streetNumber=value:exact for exact match).
- extra (string, optional) – Filter by extra address value (extra=value:exact for exact match).
- phoneNumber (string, optional) – Filter by phone number (phoneNumber=value:exact for exact match).
- type (string, optional) – Filter by order type.
- status (string, optional) – Filter by order status.
- orderState (string, optional) – Filter by order state.
- timeWindowStart (string, optional) – Filter by time window start (timeWindowStart=value:exact for exact match).
- timeWindowEnd (string, optional) – Filter by time window end (timeWindowEnd=value:exact for exact match).
- creationTime (string, optional) – Filter by creation time (creationTime=value:exact for exact match).
- priority (string, optional) – Filter by order priority.
- customData (string, optional) – Filter by custom data (customData=value:exact for exact match).
- customerId (string, optional) – Filter by customer ID (customerId=value:exact for exact match).
- depotId (string, optional) – Filter by depot/misc location ID (depotId=value:exact for exact match).
- sort (string, optional) – Sorting format: column1:asc/desc,column2:asc/desc
  - Available columns: id, alias, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, phoneNumber, type, timeWindowStart, timeWindowEnd, creationTime, serviceTime, priority, customData, customerId, depotId
- includeColumns (string, optional) – Specify which columns to include.
  - Available columns: id, alias, firstName, lastName, phoneNumber, type,timeWindowStart, timeWindowEnd, serviceTime, creationTime, packages, revenue, cube, weight, priority, status, orderState, customerId, depotId, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra
- page (integer, optional) – Page number for pagination.
- per_page (integer, optional) – Number of items per page.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	The values sent for page and per_page parameters are incorrect; should be greater than 0.
`401 Unauthorized`	API key is missing or invalid.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Example:

Response Body: (error code 200)

{
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1751445531350,
      "customerInfo": {
        "id": 1838721,
        "alias": "Magic Customer",
        "firstName": "Magic",
        "lastName": "Customer",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.870852,
        2.356148
      ],
      "alias": "Magic Order",
      "firstName": "Magic",
      "lastName": "Order",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555018",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "revenue": 12,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    },
    {
      "id": 879888,
      "creationTimestamp": 1751445531350,
      "customerInfo": {
        "id": 1838722,
        "alias": "Magic Customer2",
        "firstName": "Magic",
        "lastName": "Customer2",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer2@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.827865,
        2.379216
      ],
      "alias": "Magic Order2",
      "firstName": "Magic2",
      "lastName": "Order2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555019",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 2,
      "weight": 4.5,
      "cube": 1.1,
      "revenue": 16,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

3. Get an Order by ID

Description: Retrieves a specific order by ID.

Method: GET
Endpoint: /orders/{id}
Headers:
- Authorization: YOUR_API_KEY
URL: https://fleetmanagement.magiclaneapis.com/v1/orders/{id}
Path Parameter:
- id (integer, *required) - The unique order ID.
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	Invalid input or missing required fields.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	Order not found in database.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Example:

Response Body: (error code 200)

{
  "id": 879887,
  "creationTimestamp": 1751445531350,
  "customerInfo": {
    "id": 1838721,
    "alias": "Magic Customer",
    "firstName": "Magic",
    "lastName": "Customer",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "email": "magiccustomer@example.com",
    "phoneNumber": "+1202555018",
    "location": [
      48.870852,
      2.356148
    ],
    "customData": ""
  },
  "location": [
    48.870852,
    2.356148
  ],
  "alias": "Magic Order",
  "firstName": "Magic",
  "lastName": "Order",
  "address": {
    "country": "",
    "state": "",
    "county": "",
    "city": "",
    "postalCode": "",
    "streetName": "",
    "streetNumber": ""
  },
  "phoneNumber": "+1202555018",
  "customData": "",
  "type": 0,
  "status": 0,
  "state": 1,
  "priority": 0,
  "numberOfPackages": 3,
  "weight": 5.1,
  "cube": 2.5,
  "revenue": 12,
  "timeWindow": [
    420,
    1086
  ],
  "serviceTime": 0,
  "depotId": 0
}

4. Update an Order

Description: Updates an existing order record.

Method: PUT
Endpoint: /orders/{id}
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/orders/{id}
Path Parameter:
- id (integer, *required) - The unique order ID.
Query Parameter:
-autoAssignDepot(integer, optional) ( 0: (default) - No depot will be auto assigned to the current order. 1: The closest depot (depending on time) will be assigned to the current order.)
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	The order’s customer was not found/doesn’t exist. The order doesn’t have the coordinates set. The time window format is wrong. The number of packages/weight/cubic volume has a negative value or exceeds the maximum limit. The orders’ phone number has wrong format.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	Order not found in database.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Example:

Request Body:

{
  "id": 879887,
  "creationTimestamp": 1751445531350,
  "customerInfo": {
    "id": 1838721,
    "alias": "Magic Customer",
    "firstName": "Magic",
    "lastName": "Customer",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "email": "magiccustomer@example.com",
    "phoneNumber": "+1202555018",
    "location": [
      48.870852,
      2.356148
    ],
    "customData": ""
  },
  "location": [
    48.870852,
    2.356148
  ],
  "alias": "Magic Order",
  "firstName": "Magic",
  "lastName": "Order",
  "address": {
    "country": "",
    "state": "",
    "county": "",
    "city": "",
    "postalCode": "",
    "streetName": "",
    "streetNumber": ""
  },
  "phoneNumber": "+1202555018",
  "customData": "",
  "type": 0,
  "status": 0,
  "state": 1,
  "priority": 0,
  "numberOfPackages": 3,
  "weight": 5.1,
  "cube": 2.5,
  "revenue": 12,
  "timeWindow": [
    420,
    1086
  ],
  "serviceTime": 0,
  "depotId": 0
}

Response Body: (error code 200)

{
  "id": 879887,
  "creationTimestamp": 1751445531350,
  "customerInfo": {
    "id": 1838721,
    "alias": "Magic Customer",
    "firstName": "Magic",
    "lastName": "Customer",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "email": "magiccustomer@example.com",
    "phoneNumber": "+1202555018",
    "location": [
      48.870852,
      2.356148
    ],
    "customData": ""
  },
  "location": [
    48.870852,
    2.356148
  ],
  "alias": "Magic Order",
  "firstName": "Magic",
  "lastName": "Order",
  "address": {
    "country": "",
    "state": "",
    "county": "",
    "city": "",
    "postalCode": "",
    "streetName": "",
    "streetNumber": ""
  },
  "phoneNumber": "+1202555018",
  "customData": "",
  "type": 0,
  "status": 0,
  "state": 1,
  "priority": 0,
  "numberOfPackages": 3,
  "weight": 5.1,
  "cube": 2.5,
  "revenue": 12,
  "timeWindow": [
    420,
    1086
  ],
  "serviceTime": 0,
  "depotId": 0
}

5. Delete Orders

Description: Deletes orders from the system.

Method: DELETE
Endpoint: /orders
Headers:
- Authorization: YOUR_API_KEY
- Content-Type: application/json
URL: https://fleetmanagement.magiclaneapis.com/v1/orders
Returned error codes:

Error Code	Description
`200 Successful`	Successful operation.
`400 Bad Request`	Invalid input or missing required fields.
`401 Unauthorized`	API key is missing or invalid.
`404 Not Found`	Can't delete orders because at least one of them does not exist or is used in another operation.
`405 Method Not Allowed`	Incorrect method type.
`500 Internal Server Error`	Database error occurred.

Example:

Request Body:

{
  "ids": [78910, 78911]
}

Response Body: (error code 200)

{
  "message": "Operation done successfully",
}

Overview​

Order Object Fields​

Endpoints​

1. Create Order​

Example:​

2. Get All Orders​

Example:​

3. Get an Order by ID​

Example:​

4. Update an Order​

Example:​

5. Delete Orders​

Example:​

Overview

Order Object Fields

Endpoints

1. Create Order

Example:

2. Get All Orders

Example:

3. Get an Order by ID

Example:

4. Update an Order

Example:

5. Delete Orders

Example: