Shift start times differences

The time employees start shifts will vary depending on various factors, but it is possible to limit the difference between shift start times so that your employees have less disruption and more predictability in their schedules.

Prerequisites

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 Tenant Settings, 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 Employee Shift Scheduling model.

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

1. Define shift start time differences

To prevent employees from having shift start times that vary too much, shiftStartTimeDifferenceInMinutesMax sets on a limit how much difference there can be between shift start times.

shiftStartTimeDifferenceInMinutesMax is defined in period rules:

{
  "periodRules": [
    {
      "id": "shiftsNotCloseTogether",
      "period": "WEEK",
      "shiftStartTimeDifferenceInMinutesMax": 45,
      "satisfiability": "REQUIRED"
    }
  ]
}

PeriodRules must include an ID.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way:

{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

shiftStartTimeDifferenceInMinutesMax defines the maximum allowed difference between shift start times in minutes.

periodRules can include or exclude shifts based on shift tags.

{
  "periodRules": [
    {
      "id": "shiftsNotCloseTogether",
      "period": "WEEK",
      "shiftStartTimeDifferenceInMinutesMax": 45,
      "includeShiftTags": ["Part-time"],
      "shiftTagMatches": "ALL",
      "satisfiability": "REQUIRED"
    }
  ]
}

Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

The satisfiability of the rule can be REQUIRED or PREFERRED. If omitted, REQUIRED is the default.

2. Required shift start time difference

When the satisfiability of the rule is REQUIRED, the Shift start time difference in minutes per period not in required range for employee hard constraint is invoked, which makes sure the start times of shifts in the period do not vary more than the limit specified in shiftStartTimeDifferenceInMinutesMax.

Shifts will be left unassigned if assigning them would break the Shift start time difference in minutes per period not in required range for employee constraint.

In the following example, there are 5 shifts and 1 employee.

The shifts have the following start times:

Monday: 0900
Tuesday: 1000
Wednesday: 0930
Thursday: 0930
Friday: 0900

4 shifts are assigned. The shift on Tuesday is not assigned because the difference between its start time and the earliest start time of the other shifts is 60 minutes.

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/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Required shift start times differences example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "shiftsNotCloseTogether",
            "period": "WEEK",
            "shiftStartTimeDifferenceInMinutesMax": 45,
            "satisfiability": "REQUIRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "Tue",
        "start": "2027-02-02T10:00:00Z",
        "end": "2027-02-02T18:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:30:00Z",
        "end": "2027-02-03T17:30:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:30:00Z",
        "end": "2027-02-04T17:30:00Z"
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z"
      }
    ]
  }
}

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/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Required shift start times differences example",
    "submitDateTime": "2025-05-15T07:09:39.245875276Z",
    "startDateTime": "2025-05-15T07:09:51.402495633Z",
    "activeDateTime": "2025-05-15T07:09:51.592766191Z",
    "completeDateTime": "2025-05-15T07:10:22.491774661Z",
    "shutdownDateTime": "2025-05-15T07:10:22.707922044Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": null
      },
      {
        "id": "Wed",
        "employee": "Ann"
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 1,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "assignedShiftGroups": null,
    "unassignedShiftGroups": null,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with 1 shift not assigned to avoid breaking a hard constraint.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 4,
  "unassignedShifts": 1,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 4
}

3. Preferred shift start time difference

When the satisfiability of the rule is PREFERRED, the Shift start time difference in minutes per period not in preferred range for employee soft constraint is invoked.

{
  "periodRules": [
    {
      "id": "shiftsNotCloseTogether",
      "period": "WEEK",
      "shiftStartTimeDifferenceInMinutesMax": 45,
      "satisfiability": "PREFERRED"
    }
  ]
}

Shifts will still be assigned to employees even if assigning the shifts breaks the Shift start time difference in minutes per period not in preferred range for employee soft constraint and shift start times vary by more than the limit set in shiftStartTimeDifferenceInMinutesMax. This constraint adds a soft penalty to the run score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

This rule is more likely to be satisfied for employees with a higher employee priority.

In the following example, there are 5 shifts and 1 employee.

The shifts have the following start times:

Monday: 0900
Tuesday: 1000
Wednesday: 0930
Thursday: 0930
Friday: 0900

All 5 shifts are assigned. The shift on Tuesday has a start time that is more than the 45 minutes difference limit that set in shiftStartTimeDifferenceInMinutesMax and a soft penalty is added to the run score.

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/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Preferred shift start times differences examples"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "shiftsNotCloseTogether",
            "period": "WEEK",
            "shiftStartTimeDifferenceInMinutesMax": 45,
            "satisfiability": "PREFERRED"
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "Tue",
        "start": "2027-02-02T10:00:00Z",
        "end": "2027-02-02T18:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:30:00Z",
        "end": "2027-02-03T17:30:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:30:00Z",
        "end": "2027-02-04T17:30:00Z"
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z"
      }
    ]
  }
}

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/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Preferred shift start times differences examples",
    "submitDateTime": "2025-05-15T09:14:08.34754595Z",
    "startDateTime": "2025-05-15T09:14:29.808163485Z",
    "activeDateTime": "2025-05-15T09:14:30.054858995Z",
    "completeDateTime": "2025-05-15T09:15:01.19306088Z",
    "shutdownDateTime": "2025-05-15T09:15:01.518181802Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-30soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Ann"
      },
      {
        "id": "Tue",
        "employee": "Ann"
      },
      {
        "id": "Wed",
        "employee": "Ann"
      },
      {
        "id": "Thu",
        "employee": "Ann"
      },
      {
        "id": "Fri",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "assignedShiftGroups": null,
    "unassignedShiftGroups": null,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with all shifts assigned.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 5,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 5
}

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
See other options for Shift rotations and patterns.

Shift start times differences

Prerequisites

1. Define shift start time differences

2. Required shift start time difference

3. Preferred shift start time difference

Next