Real-time planning: extended stop (using patches)

This guide describes functionality that relies on the Patch feature, which is currently only available as a preview feature. If you’d like early access to this feature, please Contact us. For information about real-time planning without the Patch functionality, see Real-time planning.

There are many situations where Real-time planning with patches is necessary.

Sometimes stops take longer than expected.

Consider the following shift schedule:

Carl has four stops scheduled for the day: Stop C, Stop A, Stop D and Stop B.

However, Stop C takes much longer than expected.

As a result, Stop A, Stop D and Stop B need to be rescheduled.

This guide explains real-time planning: extended stop with the following:

1. Batch schedule: extended stop
2. Real-time planning update: extended stop

1. Batch schedule: extended stop

Learn how to configure an API Key to run the examples in this guide:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Manage tenant, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the Pick-up and Delivery Routing model.

In the examples, replace <API_KEY> with the API Key you just copied.

Carl’s original schedule was generated from the following input dataset during batch planning:

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/pickup-delivery-routing/v1/route-plans [email protected]

{
  "config": {
    "run": {
      "name": "Original shift plan: extended stop example"
    }
  },
  "modelInput": {
    "drivers": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl Mon",
            "startLocation": [33.77284, -84.42989],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T12:00:00Z"
          }
        ]
      }
    ],
    "jobs": [
      {
        "id": "job1",
        "stops": [
          {
            "id": "Stop A",
            "name": "Stop A",
            "location": [33.74648, -84.46461],
            "duration": "PT10M"
          },
          {
            "id": "Stop B",
            "name": "Stop B",
            "location": [33.65207, -84.46496],
            "duration": "PT10M"
          }
        ]
      },
      {
        "id": "job2",
        "stops": [
          {
            "id": "Stop C",
            "name": "Stop C",
            "location": [33.77911, -84.49644],
            "duration": "PT10M"
          },
          {
            "id": "Stop D",
            "name": "Stop D",
            "location": [33.65979, -84.46366],
            "duration": "PT10M"
          }
        ]
      }
    ]
  }
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/pickup-delivery-routing/v1/route-plans/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Original shift plan: extended stop example",
    "submitDateTime": "2026-04-09T16:15:34.09559+02:00",
    "startDateTime": "2026-04-09T16:15:34.15051+02:00",
    "activeDateTime": "2026-04-09T16:15:34.152865+02:00",
    "completeDateTime": "2026-04-09T16:16:04.170458+02:00",
    "shutdownDateTime": "2026-04-09T16:16:04.17046+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-2533soft",
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "drivers": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl Mon",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Stop C",
                "arrivalTime": "2027-02-01T09:07:26Z",
                "startServiceTime": "2027-02-01T09:07:26Z",
                "departureTime": "2027-02-01T09:17:26Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT7M26S",
                "travelDistanceMetersFromPreviousStandstill": 6190,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "load": [],
                "kind": "STOP"
              },
              {
                "id": "Stop A",
                "arrivalTime": "2027-02-01T09:23:02Z",
                "startServiceTime": "2027-02-01T09:23:02Z",
                "departureTime": "2027-02-01T09:33:02Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT5M36S",
                "travelDistanceMetersFromPreviousStandstill": 4671,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "load": [],
                "kind": "STOP"
              },
              {
                "id": "Stop D",
                "arrivalTime": "2027-02-01T09:44:36Z",
                "startServiceTime": "2027-02-01T09:44:36Z",
                "departureTime": "2027-02-01T09:54:36Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT11M34S",
                "travelDistanceMetersFromPreviousStandstill": 9640,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "load": [],
                "kind": "STOP"
              },
              {
                "id": "Stop B",
                "arrivalTime": "2027-02-01T09:55:38Z",
                "startServiceTime": "2027-02-01T09:55:38Z",
                "departureTime": "2027-02-01T10:05:38Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT1M2S",
                "travelDistanceMetersFromPreviousStandstill": 867,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "load": [],
                "kind": "STOP"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT42M13S",
              "travelTimeFromStartLocationToFirstStop": "PT7M26S",
              "travelTimeBetweenStops": "PT18M12S",
              "travelTimeFromLastStopToEndLocation": "PT16M35S",
              "totalTravelDistanceMeters": 35183,
              "travelDistanceFromStartLocationToFirstStopMeters": 6190,
              "travelDistanceBetweenStopsMeters": 15178,
              "travelDistanceFromLastStopToEndLocationMeters": 13815,
              "endLocationArrivalTime": "2027-02-01T10:22:13Z"
            }
          }
        ]
      }
    ],
    "unassignedJobs": []
  },
  "inputMetrics": {
    "jobs": 2,
    "stops": 4,
    "drivers": 1,
    "driverShifts": 1,
    "pinnedStops": 0
  },
  "kpis": {
    "totalTravelTime": "PT42M13S",
    "totalTravelDistanceMeters": 35183,
    "totalActivatedDrivers": 1,
    "totalUnassignedJobs": 0,
    "totalAssignedJobs": 2,
    "assignedMandatoryJobs": 2,
    "totalUnassignedStops": 0,
    "totalAssignedStops": 4,
    "assignedMandatoryStops": 4,
    "travelTimeFromStartLocationToFirstStop": "PT7M26S",
    "travelTimeBetweenStops": "PT18M12S",
    "travelTimeFromLastStopToEndLocation": "PT16M35S",
    "travelDistanceFromStartLocationToFirstStopMeters": 6190,
    "travelDistanceBetweenStopsMeters": 15178,
    "travelDistanceFromLastStopToEndLocationMeters": 13815
  }
}

modelOutput contains Carl’s shift itinerary.

2. Real-time planning update: extended stop

The plan needs to be updated to reflect the new situation.

Stop C took thirty minutes longer than expected.

Update the duration for Stop C from 10 minutes to 40 minutes.

The following shows the required input and the patch operation that will change the original input:

Input
Patch

{
  "id": "Stop C",
  "name": "Stop C",
  "location": [33.77911, -84.49644],
  "duration": "PT40M",
  "minStartTravelTime": "2027-02-01T00:00:00Z"
}

{
  "op": "replace",
  "path": "/jobs/[id=job2]/stops/[id=Stop C]/duration",
  "value": "PT40M"
}

Freeze the departure times for stops that have already occurred and that drivers have begun traveling to by adding freezeTime.

The following shows the required input and the patch operation that will change the original input:

Input
Patch

{
  "modelInput": {
    "freezeTime": "2027-02-01T09:20:00Z"
  }
}

{
  "op": "add",
  "path": "/freezeTime",
  "value": "2027-02-01T09:20:00Z"
}

Because Carl finished Stop C at 09:17 and is already traveling to Stop A at the freezeTime, this will keep Stop A scheduled after Stop C with a new arrival time.

Submit the full patch to modify the original input dataset to the following endpoint. Replace <ID> with the dataset ID:

v1/route-plans/<ID>/from-patch/

When submitted, solving is triggered to generate a new revision of the plan.

Patch
Output

Try this example in Timefold Platform by saving this JSON into a file called patch.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/pickup-delivery-routing/v1/route-plans/<ID>/from-patch [email protected]

{
  "config": {
    "run": {
      "name": "Real-time planning: extended stop example"
    }
  },
  "patch": [
    {
      "op": "add",
      "path": "/freezeTime",
      "value": "2027-02-01T09:20:00Z"
    },
    {
      "op": "replace",
      "path": "/jobs/[id=job2]/stops/[id=Stop C]/duration",
      "value": "PT40M"
    }
  ]
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/pickup-delivery-routing/v1/route-plans/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Original shift plan: extended stop example",
    "submitDateTime": "2026-04-09T16:11:41.258457+02:00",
    "startDateTime": "2026-04-09T16:11:41.465113+02:00",
    "activeDateTime": "2026-04-09T16:11:41.465887+02:00",
    "completeDateTime": "2026-04-09T16:12:11.481571+02:00",
    "shutdownDateTime": "2026-04-09T16:12:11.481574+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-2533soft",
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "drivers": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl Mon",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Stop C",
                "arrivalTime": "2027-02-01T09:07:26Z",
                "startServiceTime": "2027-02-01T09:07:26Z",
                "departureTime": "2027-02-01T09:47:26Z",
                "effectiveServiceDuration": "PT40M",
                "travelTimeFromPreviousStandstill": "PT7M26S",
                "travelDistanceMetersFromPreviousStandstill": 6190,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "load": [],
                "pinned": true,
                "kind": "STOP"
              },
              {
                "id": "Stop A",
                "arrivalTime": "2027-02-01T09:53:02Z",
                "startServiceTime": "2027-02-01T09:53:02Z",
                "departureTime": "2027-02-01T10:03:02Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT5M36S",
                "travelDistanceMetersFromPreviousStandstill": 4671,
                "minStartTravelTime": "2027-02-01T09:20:00Z",
                "load": [],
                "kind": "STOP"
              },
              {
                "id": "Stop D",
                "arrivalTime": "2027-02-01T10:14:36Z",
                "startServiceTime": "2027-02-01T10:14:36Z",
                "departureTime": "2027-02-01T10:24:36Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT11M34S",
                "travelDistanceMetersFromPreviousStandstill": 9640,
                "minStartTravelTime": "2027-02-01T09:20:00Z",
                "load": [],
                "kind": "STOP"
              },
              {
                "id": "Stop B",
                "arrivalTime": "2027-02-01T10:25:38Z",
                "startServiceTime": "2027-02-01T10:25:38Z",
                "departureTime": "2027-02-01T10:35:38Z",
                "effectiveServiceDuration": "PT10M",
                "travelTimeFromPreviousStandstill": "PT1M2S",
                "travelDistanceMetersFromPreviousStandstill": 867,
                "minStartTravelTime": "2027-02-01T09:20:00Z",
                "load": [],
                "kind": "STOP"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT42M13S",
              "travelTimeFromStartLocationToFirstStop": "PT7M26S",
              "travelTimeBetweenStops": "PT18M12S",
              "travelTimeFromLastStopToEndLocation": "PT16M35S",
              "totalTravelDistanceMeters": 35183,
              "travelDistanceFromStartLocationToFirstStopMeters": 6190,
              "travelDistanceBetweenStopsMeters": 15178,
              "travelDistanceFromLastStopToEndLocationMeters": 13815,
              "endLocationArrivalTime": "2027-02-01T10:52:13Z"
            }
          }
        ]
      }
    ],
    "unassignedJobs": []
  },
  "inputMetrics": {
    "jobs": 2,
    "stops": 4,
    "drivers": 1,
    "driverShifts": 1,
    "pinnedStops": 1
  },
  "kpis": {
    "totalTravelTime": "PT42M13S",
    "totalTravelDistanceMeters": 35183,
    "totalActivatedDrivers": 1,
    "totalUnassignedJobs": 0,
    "totalAssignedJobs": 2,
    "assignedMandatoryJobs": 2,
    "totalUnassignedStops": 0,
    "totalAssignedStops": 4,
    "assignedMandatoryStops": 4,
    "travelTimeFromStartLocationToFirstStop": "PT7M26S",
    "travelTimeBetweenStops": "PT18M12S",
    "travelTimeFromLastStopToEndLocation": "PT16M35S",
    "travelDistanceFromStartLocationToFirstStopMeters": 6190,
    "travelDistanceBetweenStopsMeters": 15178,
    "travelDistanceFromLastStopToEndLocationMeters": 13815
  }
}

modelOutput contains Carl’s updated shift itinerary.

Stop C took much longer than expected, so Stop A, Stop D and Stop B are all scheduled for later in the day.

See the full API spec or try the online API.
Learn about real-time planning.
Real-time planning with pinned stops.

Real-time planning: extended stop (using patches)

1. Batch schedule: extended stop

2. Real-time planning update: extended stop

Next