# Migrate to 1.1.3

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 5 minutes read

<br />

<br />

This guide outlines the changes introduced in REST API version 1.1.3. Required updates may vary depending on your use case.

Version 1.1.3 introduces significant changes to the response formats and adds new capabilities.

## Breaking Changes[​](#breaking-changes "Direct link to Breaking Changes")

1. `/optimize` endpoint - asynchronous execution:

   * **Major Change**: `/optimize` now returns a request object instead of immediate results
   * **New Workflow**: Submit request → Get requestId → Poll for completion → Retrieve solution
   * **New Endpoint**: `/optimize/solution` endpoint added for retrieving solutions

2. `/optimize` endpoint schema changes:

   * Added support for **user-defined matrices** when `matrixBuildType = 0`
   * Added **orders sequences** option for specifying delivery order constraints

3. `/optimizations/solution` and `/optimizations/{id}/solution` endpoints:

   * Output format changed: added `droppedOrders` field

## Changes to `/optimize` endpoint schema[​](#changes-to-optimize-endpoint-schema "Direct link to changes-to-optimize-endpoint-schema")

### Input Schema Changes[​](#input-schema-changes "Direct link to Input Schema Changes")

* Added `user-defined matrices` only when `matrixBuildType = 0` (matrices are set by user)
* Added `orderSequenceOptions` option for making association between orders that should be visited in a certain order.

#### Previous version of input:[​](#previous-version-of-input "Direct link to Previous version of input:")

```json
{
  "configurationParameters": {
    "name": "string",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 0,
    "maxTimeToOptimize": 0,
    "maxWaitTime": 0,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0
  },
  "orders": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "licensePlate": "string",
      "consumption": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ]
}

```

#### Updated version of input:[​](#updated-version-of-input "Direct link to Updated version of input:")

```json
{
  "configurationParameters": {
    "name": "string",
    "ignoreTimeWindow": false,
    "allowDroppingOrders": false,
    "groupingOrders": false,
    "balancedRoutes": 0,
    "optimizationCriterion": 0,
    "arrangeCriterion": 0,
    "optimizationQuality": 0,
    "maxTimeToOptimize": 0,
    "maxWaitTime": 0,
    "routeType": 0,
    "restrictions": 0,
    "distanceUnit": 0,
    "orderSequenceOptions": [[1, 4], [3, 7]]
  },
  "matrixBuildType": 0,
  "matrices": [
     {
       "vehicleType": 0,
       "distMatrix": [
         [0, 612.4, 389.7],
         [612.4, 0, 467.2],
         [389.7, 467.2, 0]
       ],
       "timeMatrix": [
         [0, 205, 128],
         [205, 0, 150],
         [128, 150, 0]
       ]
     }
   ],
  "orders": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "departures": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "destinations": [
    {
      "alias": "string",
      "location": [
        0.0,
        0.0
      ]
    }
  ],
  "vehicles": [
    {
      "name": "string",
      "type": 0,
      "maxLoadWeight": 0,
      "maxLoadCube": 0,
      "startTime": 0,
      "endTime": 1439,
      "licensePlate": "string",
      "consumption": 0
    }
  ],
  "vehiclesConstraints": [
    {
      "startDate": 0,
      "maxNumberOfPackages": 0,
      "minNumberOfOrders": 0,
      "maxNumberOfOrders": 0,
      "minDistance": 0,
      "maxDistance": 0,
      "maxRevenue": 0
    }
  ]
}

```

### Output Schema Changes[​](#output-schema-changes "Direct link to Output Schema Changes")

:::info Note Solving an `/optimize` request returns a `request` object that allows you to track the optimization process status. Once the request status is completed, retrieve the solution using the new [`/optimize/{id}/solution`](/docs/cloud-rest-api/guides/fleet-management/core-concepts/landmark.md#3-get-solution) endpoint.

The solution contains one or more routes, where each route represents a vehicle's trip to visit assigned orders. The maximum number of routes returned equals the number of vehicles provided in the request. :::

#### Previous version of output:[​](#previous-version-of-output "Direct link to Previous version of output:")

```json
{
  "droppedOrders": [
    {
      "alias": "string",
      "location": [
        0,
        0
      ],
      "type": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "revenue": 0,
      "priority": 0,
      "customData": "string"
    }
  ],
  "routes": [
    {
      "orders": [
        {
          "alias": "string",
          "location": [
            0,
            0
          ],
          "matchedLocation": [
            0,
            0
          ],
          "type": 0,
          "priority": 0,
          "customData": "string",
          "numberOfPackages": 0,
          "weight": 0,
          "cube": 0,
          "revenue": 0,
          "serviceTime": 0,
          "timeWindow": [
            0,
            0
          ],
          "indexInRoute": 0,
          "indexInOptimization": 0,
          "arrivalTime": 0,
          "waitTime": 0,
          "numberOfPackagesAtArrival": 0,
          "weightAtArrival": 0,
          "cubeAtArrival": 0,
          "traveledDistance": 0,
          "revenueAtArrival": 0,
          "deliveredNumberOfPackages": 0,
          "deliveredWeight": 0,
          "deliveredCube": 0,
          "distanceToNextOrder": 0,
          "timeToNextOrder": 0
        }
      ],
      "departure": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "departureTime": 0,
        "timeToNext": 0,
        "distanceToNext": 0
      },
      "destination": {
        "alias": "string",
        "location": [
          0,
          0
        ],
        "matchedLocation": [
          0,
          0
        ],
        "arrivalTime": 0
      },
      "vehicle": {
        "name": "string",
        "type": 0,
        "maxLoadWeight": 0,
        "maxLoadCube": 0,
        "startTime": 0,
        "endTime": 1439,
        "licensePlate": "string",
        "consumption": 0
      },
      "vehicleConstraints": {
        "startDate": 0,
        "maxNumberOfPackages": 0,
        "minNumberOfOrders": 0,
        "maxNumberOfOrders": 0,
        "minDistance": 0,
        "maxDistance": 0,
        "maxRevenue": 0
      },
      "totalDistance": 0,
      "totalTime": 0,
      "totalServiceTime": 0,
      "totalWaitTime": 0,
      "creationTimestamp": 0,
      "neededFuel": 0
    }
  ]
}

```

#### Updated version of output:[​](#updated-version-of-output "Direct link to Updated version of output:")

* Use new `/optimize/solution?requestId={id}` endpoint to retrieve results

```json
{
  "id": 23567,
  "solutionId": 46587,
  "status": 0,
  "message": "Operation running...please wait",
  "creationTimestamp": 1747786578
}

```

## New `/optimize/{id}/solution` Endpoint[​](#new-optimizeidsolution-endpoint "Direct link to new-optimizeidsolution-endpoint")

Version 1.1.3 introduces a new endpoint specifically for retrieving optimization solutions:

**Endpoint**: `GET /optimize/{id}/solution`

**Purpose**: Retrieve the solution for a previously submitted `/optimize` request.

## Migration Summary[​](#migration-summary "Direct link to Migration Summary")

### Breaking Changes - Immediate Action Required[​](#breaking-changes---immediate-action-required "Direct link to Breaking Changes - Immediate Action Required")

* [ ] **Update `/optimize` integration** to handle asynchronous request/response pattern
* [ ] **Implement polling mechanism** using new `/optimize/{id}/solution` endpoint
* [ ] **Handle request tracking object** instead of direct solution response

### Optional Enhancements[​](#optional-enhancements "Direct link to Optional Enhancements")

* [ ] **Use user-defined matrices** by setting `matrixBuildType = 0` and providing `matrices`
* [ ] **Implement order sequences** using `orderSequenceOptions` in configuration parameters

:::warning Critical Update The asynchronous execution change for `/optimize` is a **breaking change**. Applications will fail without updating the integration workflow. :::
