# Update Route

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 10 minutes read

<br />

<br />

This example demonstrates how to update an existing route by making changes to its configuration, vehicle constraints, and other fields. The updated route can also be reoptimized to generate a new order of visits. If the route is not reoptimized, the changes will not affect the route's optimization. However, certain configuration changes (e.g., ignoring time windows, optimization criteria, etc.) automatically trigger reoptimization.

For updating orders, refer to the following examples:

* [Adding Orders to a Route](/docs/cloud-rest-api/guides/fleet-management/core-concepts/route.md#6-add-route-orders)
* [Updating an Order from a Optimization](/docs/cloud-rest-api/guides/fleet-management/core-concepts/optimization.md#10-update-order-from-an-optimization)
* [Deleting an Order from a Route](/docs/cloud-rest-api/guides/fleet-management/core-concepts/route.md#7-delete-an-order-from-a-route)

## How to Use the Sample[​](#how-to-use-the-sample "Direct link to How to Use the Sample")

When you run the example application:

1. The existing route is updated with new configurations, vehicle constraints, and other fields.
2. The route is reoptimized (if specified), and a new order of visits is returned.

## Step-by-Step Guide[​](#step-by-step-guide "Direct link to Step-by-Step Guide")

### Step 1: Retrieve the Existing Route[​](#step-1-retrieve-the-existing-route "Direct link to Step 1: Retrieve the Existing Route")

To update a route, you first need to retrieve the existing route using its ID.

* **Method:** `GET`

* **Endpoint:** `/routes/{id}`

* **Headers:**
  * `Authorization: YOUR_API_KEY`

* **URL:** `https://api.magiclane.net/api/v1/fleetmanagement/routes/{id}`

* **Path Parameter:**
  * `id` (integer, \**required*) - The unique route ID.

* **Query Parameter:**

  * `encodeShape` (integer, *optional*)

    <!-- -->

    * `0`: The route's shape will not be encoded.
    * `1` (default): The route's shape will be encoded.

#### Example:[​](#example "Direct link to Example:")

* **Response Body:** (error code `200`)

```json
{
  "configurationParameters": {
    "orderSequenceOptions": [],
    "distanceUnit": 0,
    "maxTimeToOptimize": 300,
    "optimizationQuality": 2,
    "routeType": 0,
    "arrangeCriterion": 0,
    "restrictions": 0,
    "maxWaitTime": 18000,
    "balancedRoutes": 0,
    "groupingOrders": false,
    "optimizationCriterion": 0,
    "allowDroppingOrders": false,
    "ignoreTimeWindow": false,
    "name": "Paris - test optimization - Part 1"
  },
  "vehicleConstraints": {
    "startDate": 1596758400000,
    "maxNumberOfPackages": 53,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 100000000,
    "maxRevenue": 85,
    "fuelPrice": 1.0700000524520874
  },
  "rideStatus": 1,
  "vehicle": {
    "length": 0,
    "weight": 0,
    "width": 0,
    "licensePlate": "",
    "consumption": 6.5,
    "fuelType": 2,
    "make": "",
    "id": 134764,
    "name": "Car vehicle",
    "model": "",
    "costPerHour": 0,
    "type": 0,
    "status": 0,
    "maxLoadWeight": 60,
    "height": 0,
    "maxLoadCube": 50,
    "idDriver": 134764,
    "endTime": 1439,
    "fixedCost": 0,
    "startTime": 420,
    "lastPosition": [
      2147483647,
      2147483647
    ]
  },
  "destination": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "arrivalTime": 1596783691000,
    "traveledDistance": 0.6638350486755371
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfpackages": 0,
    "weight": 0,
    "cube": 0,
    "departureTime": 1596783600000,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1742220618730,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "optimizationId": 137211,
  "orders": [
    {
      "orderInfo": {
        "revenue": 0,
        "serviceTime": 0,
        "timeWindow": [
          1596783600000,
          1596823600000
        ],
        "creationTimestamp": 1742220613856,
        "cube": 0,
        "numberOfPackages": 0,
        "depotId": 0,
        "customData": "",
        "weight": 0,
        "phoneNumber": "+12025550181",
        "lastName": "",
        "status": 1,
        "firstName": "",
        "alias": "",
        "state": 1,
        "type": 0,
        "priority": 0,
        "id": 876534,
        "location": [
          48.827327,
          2.342267
        ],
        "address": {
          "streetNumber": "",
          "postalCode": "",
          "streetName": "",
          "county": "",
          "state": "",
          "extra": "",
          "city": "",
          "country": ""
        },
        "customerInfo": {
          "phoneNumber": "+12025550181",
          "email": "c1@yahoo.com",
          "lastName": "",
          "firstName": "",
          "alias": "",
          "customData": "",
          "id": 1786643,
          "location": [
            48.827327,
            2.342267
          ],
          "address": {
            "streetNumber": "",
            "postalCode": "",
            "streetName": "",
            "county": "",
            "state": "",
            "extra": "",
            "city": "",
            "country": ""
          }
        }
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0,
      "traveledDistance": 0.07019499689340591,
      "distanceToNextOrder": 0.5936400294303894,
      "revenueAtArrival": 0,
      "visitTimestamp": 0
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371,
  "id": 250806
}

```

### Step 2: Update the Route[​](#step-2-update-the-route "Direct link to Step 2: Update the Route")

Once the route is retrieved, you can update its fields, such as configuration parameters, vehicle constraints, and other properties.

#### Update Configuration Parameters[​](#update-configuration-parameters "Direct link to Update Configuration Parameters")

1. Retrieve the existing configuration parameters from the route.
2. Modify the desired fields, such as the name and route type.

```json
"configurationParameters": {
		"orderSequenceOptions": [],
		"distanceUnit": 0,
		"maxTimeToOptimize": 300,
		"optimizationQuality": 2,
		"routeType": 1,
		"arrangeCriterion": 0,
		"restrictions": 0,
		"maxWaitTime": 18000,
		"balancedRoutes": 0,
		"groupingOrders": false,
		"optimizationCriterion": 0,
		"allowDroppingOrders": false,
		"ignoreTimeWindow": false,
		"name": "Paris - test optimization - Part 1 updated"
	}

```

#### Update Vehicle Constraints[​](#update-vehicle-constraints "Direct link to Update Vehicle Constraints")

1. Retrieve the existing vehicle constraints from the route.
2. Modify the desired fields, such as the maximum number of packages and maximum distance.

```json
	"vehicleConstraints": {
		"startDate": 1596758400000,
		"maxNumberOfPackages": 85,
		"minNumberOfOrders": 0,
		"maxNumberOfOrders": 99999999,
		"minDistance": 0,
		"maxDistance": 999999,
		"maxRevenue": 85,
		"fuelPrice": 1.0700000524520874
	}

```

### Step 3: Update the Route and Retrieve the New Solution[​](#step-3-update-the-route-and-retrieve-the-new-solution "Direct link to Step 3: Update the Route and Retrieve the New Solution")

Once the route is updated, you can apply the changes and retrieve the new solution.

1. Set the updated configuration parameters and vehicle constraints to the route.
2. Once the route is updated, call the `updateRoute` reuqest following the steps below.

* **Method:** `PUT`

* **Endpoint:** `/routes/{id}`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **URL:** `https://api.magiclane.net/api/v1/fleetmanagement/routes/{id}`

* **Path Parameter:**
  * `id` (integer, \**required*) - The unique route ID.

* **Query Parameter:**
  * `encodeShape` (integer, *not required*) - 0: The route's shape will not be encoded. 1:(default) - The route's shape will be encoded.

Note

Orders within a route **cannot be updated directly** using `Update Route` request. However, all other fields in the route can be modified using this method.

#### Example:[​](#example-1 "Direct link to Example:")

* **Request Body:**

```json
{
"configurationParameters": {
    "orderSequenceOptions": [],
    "distanceUnit": 0,
    "maxTimeToOptimize": 300,
    "optimizationQuality": 2,
    "routeType": 1,
    "arrangeCriterion": 0,
    "restrictions": 0,
    "maxWaitTime": 18000,
    "balancedRoutes": 0,
    "groupingOrders": false,
    "optimizationCriterion": 0,
    "allowDroppingOrders": false,
    "ignoreTimeWindow": false,
    "name": "Paris - test optimization - Part 1 updated"
  },
"vehicleConstraints": {
    "startDate": 1596758400000,
    "maxNumberOfPackages": 85,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 999999,
    "maxRevenue": 85,
    "fuelPrice": 1.0700000524520874
  },
  "rideStatus": 1,
  "vehicle": {
    "length": 0,
    "weight": 0,
    "width": 0,
    "licensePlate": "",
    "consumption": 6.5,
    "fuelType": 2,
    "make": "",
    "id": 134764,
    "name": "Car vehicle",
    "model": "",
    "costPerHour": 0,
    "type": 0,
    "status": 0,
    "maxLoadWeight": 60,
    "height": 0,
    "maxLoadCube": 50,
    "idDriver": 134764,
    "endTime": 1439,
    "fixedCost": 0,
    "startTime": 420,
    "lastPosition": [
      2147483647,
      2147483647
    ]
  },
  "destination": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "arrivalTime": 1596783691000,
    "traveledDistance": 0.6638350486755371
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfpackages": 0,
    "weight": 0,
    "cube": 0,
    "departureTime": 1596783600000,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1742220618730,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "optimizationId": 137211,
  "orders": [
    {
      "orderInfo": {
        "revenue": 0,
        "serviceTime": 0,
        "timeWindow": [
          1596783600000,
          1596823600000
        ],
        "creationTimestamp": 1742220613856,
        "cube": 0,
        "numberOfPackages": 0,
        "depotId": 0,
        "customData": "",
        "weight": 0,
        "phoneNumber": "+12025550181",
        "lastName": "",
        "status": 1,
        "firstName": "",
        "alias": "",
        "state": 1,
        "type": 0,
        "priority": 0,
        "id": 876534,
        "location": [
          48.827327,
          2.342267
        ],
        "address": {
          "streetNumber": "",
          "postalCode": "",
          "streetName": "",
          "county": "",
          "state": "",
          "extra": "",
          "city": "",
          "country": ""
        },
        "customerInfo": {
          "phoneNumber": "+12025550181",
          "email": "c1@yahoo.com",
          "lastName": "",
          "firstName": "",
          "alias": "",
          "customData": "",
          "id": 1786643,
          "location": [
            48.827327,
            2.342267
          ],
          "address": {
            "streetNumber": "",
            "postalCode": "",
            "streetName": "",
            "county": "",
            "state": "",
            "extra": "",
            "city": "",
            "country": ""
          }
        }
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0,
      "traveledDistance": 0.07019499689340591,
      "distanceToNextOrder": 0.5936400294303894,
      "revenueAtArrival": 0,
      "visitTimestamp": 0
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371,
  "id": 250806
}

```

* **Response**
* `Code 200` : Successful operation!

```json
{
  "id": 123456,
  "optimizationId": 123456,
  "routeId": 123456,
  "status": 0,
  "message": "Operation done successfully!",
  "creationTimestamp": 123456
}

```

### Step 4: Retrieve the Updated Route[​](#step-4-retrieve-the-updated-route "Direct link to Step 4: Retrieve the Updated Route")

If the route update was successful then the request will end with `code 200`. A new route will be returned: Updated route response:

#### Example:[​](#example-2 "Direct link to Example:")

* **Response Body:** (error code `200`)

```json
{
"configurationParameters": {
    "orderSequenceOptions": [],
    "distanceUnit": 0,
    "maxTimeToOptimize": 300,
    "optimizationQuality": 2,
    "routeType": 1,
    "arrangeCriterion": 0,
    "restrictions": 0,
    "maxWaitTime": 18000,
    "balancedRoutes": 0,
    "groupingOrders": false,
    "optimizationCriterion": 0,
    "allowDroppingOrders": false,
    "ignoreTimeWindow": false,
    "name": "Paris - test optimization - Part 1 updated"
  },
"vehicleConstraints": {
    "startDate": 1596758400000,
    "maxNumberOfPackages": 85,
    "minNumberOfOrders": 0,
    "maxNumberOfOrders": 99999999,
    "minDistance": 0,
    "maxDistance": 999999,
    "maxRevenue": 85,
    "fuelPrice": 1.0700000524520874
  },
  "rideStatus": 1,
  "vehicle": {
    "length": 0,
    "weight": 0,
    "width": 0,
    "licensePlate": "",
    "consumption": 6.5,
    "fuelType": 2,
    "make": "",
    "id": 134764,
    "name": "Car vehicle",
    "model": "",
    "costPerHour": 0,
    "type": 0,
    "status": 0,
    "maxLoadWeight": 60,
    "height": 0,
    "maxLoadCube": 50,
    "idDriver": 134764,
    "endTime": 1439,
    "fixedCost": 0,
    "startTime": 420,
    "lastPosition": [
      2147483647,
      2147483647
    ]
  },
  "destination": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "arrivalTime": 1596783691000,
    "traveledDistance": 0.6638350486755371
  },
  "departure": {
    "depotId": 0,
    "alias": "Departure2",
    "address": {
      "streetNumber": "34",
      "postalCode": "86000",
      "streetName": "Boulevard Chasseigne",
      "county": "Nouvelle-Aquitaine",
      "state": "",
      "extra": "",
      "city": "Poitiers",
      "country": "France"
    },
    "location": [
      48.82674,
      2.342116
    ],
    "matchedLocation": [
      48.82679375,
      2.3420853125
    ],
    "numberOfpackages": 0,
    "weight": 0,
    "cube": 0,
    "departureTime": 1596783600000,
    "timeToNext": 12,
    "distanceToNext": 0.07019499689340591
  },
  "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
  "creationTimestamp": 1742220618730,
  "neededFuel": 0.04314928129315376,
  "matrixBuildType": 1,
  "price": 0.04616973176598549,
  "totalWaitTime": 0,
  "totalServiceTime": 0,
  "optimizationId": 137211,
  "orders": [
    {
      "orderInfo": {
        "revenue": 0,
        "serviceTime": 0,
        "timeWindow": [
          1596783600000,
          1596823600000
        ],
        "creationTimestamp": 1742220613856,
        "cube": 0,
        "numberOfPackages": 0,
        "depotId": 0,
        "customData": "",
        "weight": 0,
        "phoneNumber": "+12025550181",
        "lastName": "",
        "status": 1,
        "firstName": "",
        "alias": "",
        "state": 1,
        "type": 0,
        "priority": 0,
        "id": 876534,
        "location": [
          48.827327,
          2.342267
        ],
        "address": {
          "streetNumber": "",
          "postalCode": "",
          "streetName": "",
          "county": "",
          "state": "",
          "extra": "",
          "city": "",
          "country": ""
        },
        "customerInfo": {
          "phoneNumber": "+12025550181",
          "email": "c1@yahoo.com",
          "lastName": "",
          "firstName": "",
          "alias": "",
          "customData": "",
          "id": 1786643,
          "location": [
            48.827327,
            2.342267
          ],
          "address": {
            "streetNumber": "",
            "postalCode": "",
            "streetName": "",
            "county": "",
            "state": "",
            "extra": "",
            "city": "",
            "country": ""
          }
        }
      },
      "matchedLocation": [
        48.82734625,
        2.3421875
      ],
      "actualLocation": [
        0,
        0
      ],
      "indexInRoute": 0,
      "indexInOptimization": 1,
      "arrivalTime": 1596783612000,
      "timeToNextOrder": 79,
      "waitTime": 0,
      "numberOfPackagesAtArrival": 0,
      "collectedNumberOfPackages": 0,
      "deliveredNumberOfPackages": 0,
      "weightAtArrival": 0,
      "collectedWeight": 0,
      "deliveredWeight": 0,
      "cubeAtArrival": 0,
      "collectedCube": 0,
      "deliveredCube": 0,
      "traveledDistance": 0.07019499689340591,
      "distanceToNextOrder": 0.5936400294303894,
      "revenueAtArrival": 0,
      "visitTimestamp": 0
    }
  ],
  "totalTime": 91,
  "totalDistance": 0.6638350486755371,
  "id": 250806
}

```

## Conclusion[​](#conclusion "Direct link to Conclusion")

This example demonstrates how to update an existing route by modifying its configuration, vehicle constraints, and other fields. By following the steps above, you can adapt this example to your specific use case and integrate it into your fleet management workflow.
