Cost management

Managing costs is an important factor in employee shift scheduling.

Costs include the wages paid to employees who are assigned to work the shifts and the operating cost of the shift, for instance, if a locations is hired or supplies are needed for the shift.

Different employees have different salaries, and different shifts have different operating costs.

With Timefold you can define employee cost groups and shift cost groups to help keep shift assignments on budget.

This guide explains how to manage costs with the following examples:

1. Managing shift costs
2. Maximum shift cost
3. Preferred shift cost
4. Minimizing overall cost
5. Defining the cost of time worked

1. Managing shift costs

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

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

Cost rules are defined as global rules:

{
  "globalRules": {
    "costsRules": [
      {
        "id": "max1k",
        "period": "SCHEDULE",
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 500
          }
        ],
        "totalCostsMax": 1000,
        "satisfiability": "REQUIRED"
      }
    ]
  }
}

costRules 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.

Learn about counting days in period rules:

By default, period rules count shifts within the defined period if the shift starts within the defined period. For instance, if you define a rule that an employee can only work 1 shift a day, a night shift that started on the previous day but ends the following morning will not be counted and another shift might be assigned on the same day as the night shift ended.

To change this behavior change the field periodShiftOverlapKind from START_ONLY to START_AND_END.

{
  "periodRules": [
    {
      "id": "Max8HoursPerDayFullTime",
      "period": "DAY",
      "minutesWorkedLimit": {
        "minutesWorkedMax": 480
      },
      "satisfiability": "REQUIRED",
      "periodShiftOverlapKind": "START_AND_END"
    }
  ]
}

employeeShiftCostDetails includes the employeeCostGroup, shiftCostGroup, and cost.

employeeCostGroup: the employee costGroup that is included in this grouping.
shiftCostGroup: the shift costGroup that is included in this grouping.
cost: the cost of assigning a shift in this pairing of employee costGroup and shift costGroup. Cost does not specify a specific currency.

employeeShiftCostDetails can include multiple groups:

{
  "globalRules": {
    "costsRules": [
      {
        "id": "max1k",
        "period": "SCHEDULE",
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 500
          },
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_B",
            "shiftCostGroup": "SHIFT_COST_GROUP_B",
            "cost": 400
          }
        ],
        "totalCostsMax": 1000,
        "satisfiability": "REQUIRED"
      }
    ]
  }
}

totalCostsMax is the maximum cost of assigning shifts to employees in the solution.

Employees must include which costgroup they belong to:

{
  "id": "Ann",
  "costGroup": "EMPLOYEE_COST_GROUP_A"
}

Shifts must include which costgroup they belong to:

{
  "id": "Mon 1",
  "start": "2027-02-01T09:00:00Z",
  "end": "2027-02-01T17:00:00Z",
  "costGroup": "SHIFT_COST_GROUP_A"
}

1.1. Filter shifts with tags

costRules can include or exclude shifts based on shift tags.

{
  "globalRules": {
    "costsRules": [
      {
        "id": "max1k",
        "period": "SCHEDULE",
        "includeShiftTags": ["Part-time"],
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 500
          }
        ],
        "totalCostsMax": 1000,
        "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.

1.2. Filter employees with tags

costRules can include or exclude employees based on tags.

{
  "globalRules": {
    "costsRules": [
      {
        "id": "max1k",
        "period": "SCHEDULE",
        "includeEmployeeTags": ["Relief"],
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 500
          }
        ],
        "totalCostsMax": 1000,
        "satisfiability": "REQUIRED"
      }
    ]
  }
}

Further information about including or excluding employees with employee tags:

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

{
  "employees": [
    {
      "id": "Ann",
      "tags": "Part-time"
    }
}

Use includeEmployeeTags to include employees with specific tags or excludeEmployeeTags to exclude employees with specific tags.

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

The rule can define either includeEmployeeTags or excludeEmployeeTags, but not both.

{
  "includeemployeeTags": ["Part-time", "Relief"],
  "employeeTagMatches": "ALL"
}

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

{
  "excludeEmployeeTags": ["Part-time", "Weekend"],
  "employeeTagMatches": "ALL"
}

With employeeTagMatches set to ALL, all tags defined by the rule’s excludeEmployeeTags attribute cannot be present in the employee. This is useful when you want to exclude things in combination with each other. For instance, excluding the employee tags Part-time and Relief with employeeTagMatches set to All, would exclude employees that include the tags Part-time and Relief from the rule. Employees tagged only Part-time or only Relief will not be excluded.

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

1.3. Rule satisfiability

The satisfiability can be REQUIRED or PREFERRED.

2. Maximum shift cost

When the satisfiability of the rule is REQUIRED, the Costs per period not in required range hard constraint is invoked, which makes sure the cost of assigning shifts does not exceed the limit specified in totalCostsMax.

Shifts will be left unassigned if assigning them would break the Costs per period not in required range constraint.

In the following example, the costsRules sets a max limit of 1000. There are 3 employees and 3 shifts, assigning 1 employee to 1 shift has a cost of 500. 2 shifts are assigned and 1 is left unassigned.

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 -d@sample.json

{
  "config": {
    "run": {
      "name": "Cost management - required"
    }
  },
  "modelInput": {
    "globalRules": {
      "costsRules": [
        {
          "id": "max1k",
          "period": "SCHEDULE",
          "employeeShiftCostDetails": [
            {
              "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
              "shiftCostGroup": "SHIFT_COST_GROUP_A",
              "cost": 500
            }
          ],
          "totalCostsMax": 1000,
          "satisfiability": "REQUIRED"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      },
      {
        "id": "Beth",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      },
      {
        "id": "Carl",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      }
    ],
    "shifts": [
      {
        "id": "Mon 1",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      },
      {
        "id": "Mon 2",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      },
      {
        "id": "Mon 3",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      }
    ]
  }
}

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>

{
  "metadata": {
    "id": "ID",
    "name": "Cost management - required",
    "submitDateTime": "2025-05-02T05:25:28.786489636Z",
    "startDateTime": "2025-05-02T05:25:45.683503799Z",
    "activeDateTime": "2025-05-02T05:25:45.872076311Z",
    "completeDateTime": null,
    "shutdownDateTime": null,
    "solverStatus": "SOLVING_ACTIVE",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon 1",
        "employee": "Ann"
      },
      {
        "id": "Mon 2",
        "employee": "Beth"
      },
      {
        "id": "Mon 3",
        "employee": null
      }
    ]
  },
  "inputMetrics": {
    "employees": 3,
    "shifts": 3,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 2,
    "unassignedShifts": 1,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 2,
    "assignedOptionalShifts": 0,
    "assignedShiftGroups": null,
    "unassignedShiftGroups": null,
    "travelDistance": 0
  }
}

modelOutput contains the schedule which has shifts assigned and keeps the cost under the totalCostsMax.

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

KPIs provides the KPIs for the output including:

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

3. Preferred shift cost

With a PREFERRED satisfiability, a totalCostsMin can be included to set the preferred minimum cost of assigning the shifts.

When the satisfiability of the rule is PREFERRED, the Costs per period not in preferred range soft constraint is invoked, which adds a soft penalty to the dataset score when the cost of the schedule is below the limit set in totalCostsMin or exceeds the limit set in totalCostsMax.

Timefold is incentivized to use solutions with the best score.

Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints.

Learn about constraint weights.

Shifts will still be assigned even if the cost is not within the specified range.

REQUIRED satisfiability is not supported with `totalCostsMin'.

{
  "globalRules": {
    "costsRules": [
      {
        "id": "max1k",
        "period": "SCHEDULE",
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 500
          }
        ],
        "totalCostsMin": 500,
        "totalCostsMax": 1000,
        "satisfiability": "PREFERRED"
      }
    ]
  }
}

In the following example, the costsRules sets a preferred max limit of 1000. There are 3 employees and 3 shifts, assigning 1 employee to 1 shift has a cost of 500. All 3 shifts are assigned and a soft penalty is applied to the dataset 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 -d@sample.json

{
  "config": {
    "run": {
      "name": "Cost management - preferred"
    }
  },
  "modelInput": {
    "globalRules": {
      "costsRules": [
        {
          "id": "max1k",
          "period": "SCHEDULE",
          "employeeShiftCostDetails": [
            {
              "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
              "shiftCostGroup": "SHIFT_COST_GROUP_A",
              "cost": 500
            }
          ],
          "totalCostsMin": 500,
          "totalCostsMax": 1000,
          "satisfiability": "PREFERRED"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      },
      {
        "id": "Beth",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      },
      {
        "id": "Carl",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      }
    ],
    "shifts": [
      {
        "id": "Mon 1",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      },
      {
        "id": "Mon 2",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      },
      {
        "id": "Mon 3",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      }
    ]
  }
}

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>

{
  "metadata": {
    "id": "ID",
    "name": "Cost management - preferred",
    "submitDateTime": "2025-05-02T08:20:48.926748573Z",
    "startDateTime": "2025-05-02T08:21:00.990412532Z",
    "activeDateTime": "2025-05-02T08:21:01.153267224Z",
    "completeDateTime": null,
    "shutdownDateTime": null,
    "solverStatus": "SOLVING_ACTIVE",
    "score": "0hard/0medium/-500soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon 1",
        "employee": "Ann"
      },
      {
        "id": "Mon 2",
        "employee": "Beth"
      },
      {
        "id": "Mon 3",
        "employee": "Carl"
      }
    ]
  },
  "inputMetrics": {
    "employees": 3,
    "shifts": 3,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 3,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
    "activatedEmployees": 3,
    "assignedMandatoryShifts": 3,
    "assignedOptionalShifts": 0,
    "assignedShiftGroups": null,
    "unassignedShiftGroups": null,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with all 3 shifts assigned.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 3,
  "activatedEmployees": 3,
  "assignedMandatoryShifts": 3
}

4. Minimizing overall cost

In some use cases, the goal is to minimize the overall cost of the schedule rather than staying within a specific budget range. This can be accomplished by defining a preferred cost rule with a totalCostsMax of 0.

With this configuration, every assignment is penalized by its cost and the model is incentivized to find assignments leading to lower costs.

{
  "globalRules": {
    "costsRules": [
      {
        "id": "minimizeCost",
        "period": "SCHEDULE",
        "employeeShiftCostDetails": [
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 100
          },
          {
            "employeeCostGroup": "EMPLOYEE_COST_GROUP_B",
            "shiftCostGroup": "SHIFT_COST_GROUP_A",
            "cost": 200
          }
        ],
        "totalCostsMax": 0,
        "satisfiability": "PREFERRED"
      }
    ]
  }
}

In the following example, there are 2 employees: Ann belongs to EMPLOYEE_COST_GROUP_A with a cost of 100, and Beth belongs to EMPLOYEE_COST_GROUP_B with a cost of 200. There are 2 shifts on consecutive days. The model assigns both shifts to Ann because her cost is lower, resulting in a total cost of 200 instead of 400 if Beth were assigned both shifts.

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 -d@sample.json

{
  "config": {
    "run": {
      "name": "Cost management - minimize overall cost"
    }
  },
  "modelInput": {
    "globalRules": {
      "costsRules": [
        {
          "id": "minimizeCost",
          "period": "SCHEDULE",
          "employeeShiftCostDetails": [
            {
              "employeeCostGroup": "EMPLOYEE_COST_GROUP_A",
              "shiftCostGroup": "SHIFT_COST_GROUP_A",
              "cost": 100
            },
            {
              "employeeCostGroup": "EMPLOYEE_COST_GROUP_B",
              "shiftCostGroup": "SHIFT_COST_GROUP_A",
              "cost": 200
            }
          ],
          "totalCostsMax": 0,
          "satisfiability": "PREFERRED"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann",
        "costGroup": "EMPLOYEE_COST_GROUP_A"
      },
      {
        "id": "Beth",
        "costGroup": "EMPLOYEE_COST_GROUP_B"
      }
    ],
    "shifts": [
      {
        "id": "Mon 1",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      },
      {
        "id": "Tue 1",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z",
        "costGroup": "SHIFT_COST_GROUP_A"
      }
    ]
  }
}

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>

{
  "metadata": {
    "id": "afa6b504-1109-4534-ad91-77aef27c99ca",
    "originId": "afa6b504-1109-4534-ad91-77aef27c99ca",
    "name": "Minimize cost",
    "submitDateTime": "2026-01-29T08:26:52.608661243Z",
    "startDateTime": "2026-01-29T08:29:29.673980507Z",
    "activeDateTime": "2026-01-29T08:29:29.776723573Z",
    "completeDateTime": "2026-01-29T08:30:00.190013582Z",
    "shutdownDateTime": "2026-01-29T08:30:00.190017302Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-200soft"
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon 1",
        "employee": "Ann"
      },
      {
        "id": "Tue 1",
        "employee": "Ann"
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "metrics": {
          "assignedShifts": 2,
          "durationWorked": "PT16H"
        }
      },
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 0,
          "durationWorked": "PT0S"
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 2,
    "shifts": 2,
    "pinnedShifts": 0,
    "mandatoryShifts": 2,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 2,
    "unassignedShifts": 0,
    "disruptionPercentage": 0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 2
  }
}

modelOutput contains the schedule with both shifts assigned to Ann, the lower-cost employee.

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

KPIs provides the KPIs for the output including:

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

5. Defining the cost of time worked

Cost can also be defined for time worked by an employee during a certain period. The example below defines a cost definition as a part of a period rule on a contract. The period rule has a mandatory PREFERRED satisfiability and a configurable period DAY.

{
  "contracts": [
    {
      "id": "employeeOvertimeActivationCost",
      "periodRules": [
        {
          "id": "dailyWork",
          "period": "DAY",
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 20,
            "overtimeCostDetails": [
              {
                "overtimeMinutesLimit": 120,
                "overtimeHourlyCost": 30
              },
              {
                "overtimeHourlyCost": 40
              }
            ]
          }
        }
      ]
    }
  ]
}

costDefinition includes baseMinutesLimit, baseHourlyCost and overtimeCostDetails.

baseMinutesLimit specifies how long the baseHourlyCost applies, for instance, 480 minutes (or 8 hours). If this field is empty, then no overtimeCostDetails are allowed and the baseHourlyCost will be applied to all of the time worked within the period.

baseHourlyCost sets the hourly cost of the employee, for instance, $20 an hour.

overtimeCostDetails includes overtimeMinutesLimit and overtimeHourlyCost.

overtimeMinutesLimit specifies how long the overtimeHourlyCost applies, for instance, 120 minutes (or 2 hours). The overtimeMinutesLimit can be omitted on the last overtimeCostDetail object. This will apply the overtimeHourlyCost to all the remaining time worked in the period.

overtimeHourlyCost sets the hourly overtime cost, for instance, $30 an hour.

If the minutes worked for an employee surpass the 10 hours of work (baseMinutesLimit + first overtimeMinutesLimit), the second overtime cost detail will define how the cost is calculated. In this case that would be $40.

You can add multiple overtimeCostDetails to cover different overtime periods. The order in which you provide these details matters. The first overtimeCostDetail provided, will be the first that will be processed.

In this example the minutes worked for an employee surpass the 10 hours of work (baseMinutesLimit + first overtimeMinutesLimit), the second overtime cost detail will define how the cost is calculated. In this case, that would be $40. The second overtime cost definition doesn’t have an overtimeMinutesLimit, so the overtimeHourlyCost will apply to all minutes worked till the period’s end.

whenever an employee starts an hour, the cost of a full hour will be counted. So if, for example, an employee works 65min, then the cost of 2 hours will be counted towards their total.

5.1. Filter shifts with tags

periodRules can include or exclude shifts based on shift tags.

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"
}

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

5.2. Rule Validity Date Time Span

To define a time span when the rule is applied, add ruleValidityDateTimeSpan with start and end times.

If not provided, the rule is always valid in the period configured.

{
  "ruleValidityDateTimeSpan": {
    "start": "2027-02-01T00:00:00Z",
    "end": "2027-02-08T00:00:00Z"
  }
}

5.3. Overtime activation cost

The following example demonstrates how to include an activation cost that must be applied when the employee starts working overtime. Here the employee must work 8 hours a day at the base rate $20/h. After 8 hours of work they start working overtime. This overtime costs $30/h, but also has an activation cost of $50. That is why there are two overtimeCostDetails. The former defines a overtimeHourlyCost of $80 ($30 + $50) and spans over the first hour. Every subsequent hour costs $30 as per the latter overtime cost detail.

{
  "contracts": [
    {
      "id": "employeeOvertimeActivationCost",
      "periodRules": [
        {
          "id": "dailyWork",
          "period": "DAY",
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 20,
            "overtimeCostDetails": [
              {
                "overtimeMinutesLimit": 60,
                "overtimeHourlyCost": 80
              },
              {
                "overtimeHourlyCost": 30
              }
            ]
          }
        }
      ]
    }
  ]
}

5.4. Mixed recurrent costs

The following example demonstrates how to deal with complex cost situations, like combining the cost of working on weekdays, weekend days or holidays.

Here the employee must work 8 hours a day at the base cost and costs double during overtime.

On weekdays the base cost is $15 and the overtime cost is $30.
During the weekend the base cost is $20 and the overtime cost is $40.
During holidays the base cost is $30 and the overtime cost is $60.

{
  "contracts": [
    {
      "id": "employeeMixedRecurrentCosts",
      "periodRules": [
        {
          "id": "weekdayCost",
          "period": "DAY",
          "includeShiftTags": ["WEEKDAY"],
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 15,
            "overtimeCostDetails": [
              {
                "overtimeMinutesLimit": 960,
                "overtimeHourlyCost": 30
              }
            ]
          }
        },
        {
          "id": "weekendCost",
          "period": "DAY",
          "includeShiftTags": ["WEEKEND"],
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 20,
            "overtimeCostDetails": [
              {
                "overtimeMinutesLimit": 960,
                "overtimeHourlyCost": 40
              }
            ]
          }
        },
        {
          "id": "holidayCost",
          "period": "DAY",
          "includeShiftTags": ["HOLIDAY"],
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 30,
            "overtimeCostDetails": [
              {
                "overtimeMinutesLimit": 960,
                "overtimeHourlyCost": 40
              }
            ]
          }
        }
      ]
    }
  ]
}

Alternatively you can configure an hourly cost per day and configure other period rules to add to this hourly cost. The example below has 3 cost definitions that work together to achieve a correct overall cost. Firstly, a general cost, that is the cost that is applicable to every day. Secondly it defines a Sunday cost, that is only applied on Sundays. The general cost and the Sunday cost will be added together to get the real cost of time worked on a Sunday. Thirdly a cost is defined for holidays, which in this case is a bonus of $10.

With this configuration employees will be paid $20/h on weekdays, with a +50% increase on holidays. On Sundays they will also be paid +50%. But if a holiday coincides with a Sunday, then they will be paid +100%.

{
  "contracts": [
    {
      "id": "employeeMixedRecurrentCosts",
      "periodRules": [
        {
          "id": "generalCost",
          "period": "DAY",
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 20
          }
        },
        {
          "id": "sundayCost",
          "period": "SUNDAY",
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 10
          }
        },
        {
          "id": "holidayCost",
          "period": "DAY",
          "includeShiftTags": ["HOLIDAY"],
          "satisfiability": "PREFERRED",
          "costDefinition": {
            "baseMinutesLimit": 480,
            "baseHourlyCost": 10
          }
        }
      ]
    }
  ]
}

5.5. Minimize cost per period constraint

When cost definitions are defined, the Minimize cost per period soft constraint is invoked, which adds a soft penalty to the dataset score based on the cost of the shift.

Timefold is incentivized to use solutions with the best score.

Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints.

Learn about constraint weights.

In the following example, there are 3 shift and 3 employees with different contracts that specify different hourly rates. The cheapest employee is assigned to 2 of the shifts and the second cheapest employee is assigned to the remaining shift. If the cheapest employee were assigned to the remaining shift, it would cost more than if the second cheapest employee were assigned, due to overtime.

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 -d@sample.json

{
  "config": {
    "run": {
      "name": "Cost definition example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "cheap employee",
        "periodRules": [
          {
            "id": "cheap employee - cost definition",
            "period": "DAY",
            "satisfiability": "PREFERRED",
            "costDefinition": {
              "baseMinutesLimit": 480,
              "baseHourlyCost": 20,
              "overtimeCostDetails": [
                {
                  "overtimeMinutesLimit": 1200,
                  "overtimeHourlyCost": 40
                }
              ]
            }
          }
        ]
      },
      {
        "id": "cheap employee, expensive overtime",
        "periodRules": [
          {
            "id": "cheap employee, expensive overtime - cost definition",
            "period": "DAY",
            "satisfiability": "PREFERRED",
            "costDefinition": {
              "baseMinutesLimit": 480,
              "baseHourlyCost": 20,
              "overtimeCostDetails": [
                {
                  "overtimeMinutesLimit": 1200,
                  "overtimeHourlyCost": 100
                }
              ]
            }
          }
        ]
      },
      {
        "id": "expensive employee",
        "periodRules": [
          {
            "id": "expensive employee - cost definition",
            "period": "DAY",
            "satisfiability": "PREFERRED",
            "costDefinition": {
              "baseMinutesLimit": 480,
              "baseHourlyCost": 200,
              "overtimeCostDetails": [
                {
                  "overtimeMinutesLimit": 1200,
                  "overtimeHourlyCost": 1000
                }
              ]
            }
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "cheap employee"
        ]
      },
      {
        "id": "Beth",
        "contracts": [
          "cheap employee, expensive overtime"
        ]
      },
      {
        "id": "Carl",
        "contracts": [
          "expensive employee"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon 1",
        "start": "2027-02-01T01:00:00Z",
        "end": "2027-02-01T09:00:00Z"
      },
      {
        "id": "Mon 2",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "Mon 3",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17: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>

{
  "metadata": {
    "id": "ID",
    "name": "Cost definition example",
    "submitDateTime": "2025-12-24T16:19:01.021361+01:00",
    "startDateTime": "2025-12-24T16:19:01.033067+01:00",
    "activeDateTime": "2025-12-24T16:19:01.033696+01:00",
    "completeDateTime": "2025-12-24T16:19:23.286797+01:00",
    "shutdownDateTime": "2025-12-24T16:19:23.286799+01:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1280soft",
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon 1",
        "employee": "Ann"
      },
      {
        "id": "Mon 2",
        "employee": "Beth"
      },
      {
        "id": "Mon 3",
        "employee": "Ann"
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "metrics": {
          "assignedShifts": 2,
          "durationWorked": "PT16H",
          "costDefinitionTotalCost": 480,
          "costDefinitionOvertime": 480
        }
      },
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 1,
          "durationWorked": "PT8H",
          "costDefinitionTotalCost": 160,
          "costDefinitionOvertime": 0
        }
      },
      {
        "id": "Carl",
        "metrics": {
          "assignedShifts": 0,
          "durationWorked": "PT0S",
          "costDefinitionTotalCost": 0,
          "costDefinitionOvertime": 0
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 3,
    "shifts": 3,
    "pinnedShifts": 0,
    "mandatoryShifts": 3,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 3,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 3
  }
}

modelOutput contains the schedule with all 3 shifts assigned. Ann was assigned 2 shifts, Beth 1 shift and Carl 0 shifts, because assigning Carl would’ve been the more expensive option even though Ann has to do overtime.

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

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.

Cost management

1. Managing shift costs

1.1. Filter shifts with tags

1.2. Filter employees with tags

1.3. Rule satisfiability

2. Maximum shift cost

3. Preferred shift cost

4. Minimizing overall cost

5. Defining the cost of time worked

5.1. Filter shifts with tags

5.2. Rule Validity Date Time Span

5.3. Overtime activation cost

5.4. Mixed recurrent costs

5.5. Minimize cost per period constraint

Next