Skip to main content

​
What is a Vehicle Maintenance Schedule?

A vehicle maintenance schedule is a period, with a start and an end time, during which a vehicle is in the workshop. While a schedule covers the routing date, the vehicle is left out of route optimization. A vehicle can have as many schedules as needed, and each one can carry an optional note. Two schedules of the same vehicle may not overlap. Schedules are their own resource, separate from the vehicle. The vehicle endpoints don’t accept maintenance dates. Related Guide: Vehicle Maintenance

​
Key Features

Read vehicle maintenance schedules

GET /vehicle-maintenances

Save vehicle maintenance schedules

POST /vehicle-maintenances

Delete vehicle maintenance schedule by ID

DELETE /vehicle-maintenance/

​
Permissions

These endpoints use the same Bearer token as the other routing endpoints and the existing vehicle permissions. There is no separate maintenance permission. A call without the permission answers 403 with the sys-035 code. Schedules are scoped to your organization. A schedule of another organization is reported as not found.

​
Reading Schedules

GET /vehicle-maintenances needs hubId or vehicleId. Without either it answers 400 with vehic-001. startTime and endTime accept Y-m-d H:i:s, read as UTC, or ISO-8601 with an offset, such as 2026-11-01T00:00:00+07:00. With both, the list holds every schedule that overlaps the range.

​
Saving Schedules

POST /vehicle-maintenances creates, updates and deletes schedules in one request. Each entry in data needs vehicleId, startTime and endTime, and may carry notes (up to 500 characters). An entry with _id updates that schedule; one without _id creates a new schedule. deletedIds lists schedules to delete in the same request. data takes 1 to 1000 entries and deletedIds up to 1000.
  1. Nothing is saved unless everything passes. Every entry is checked before the first write, so a rejected request leaves your data as it was. Messages name the entry by its position in data, starting at 1.
  2. The end must be later than the start.
  3. No overlap. Two schedules of the same vehicle overlap when each starts before the other ends. This is checked against saved schedules and against the other entries of the same request. A schedule may start exactly when another one ends.
  4. Ended schedules are read-only. A schedule whose end time has passed can’t be changed or deleted. Sending it back unchanged is accepted and leaves it as it is.
  5. Past entries are allowed. A new entry may lie entirely in the past, to record a service that already happened.
Times are stored in UTC and returned with a +00:00 offset.

​
Effect on Route Optimization

POST /routing and POST /route-optimization accept routingDate (YYYY-MM-DD) and timezone (an IANA name such as Asia/Jakarta, the default). A vehicle with a schedule that covers the routing date is left out of the optimization, unless it is forced active with isMaintenanceIgnore: true on the vehicle.
  • The whole calendar day counts, in the request’s timezone, including the first and last day of the schedule. The hours are ignored.
  • A schedule that has already ended no longer leaves the vehicle out.
  • Without routingDate, no vehicle is left out for maintenance.
  • When every vehicle in the request is left out, the request is rejected with 400 and route-032: Every vehicle in this request is under maintenance on the routing date. Remove the schedule or force one of them active before optimizing.
  • An unknown timezone is rejected with 400 and route-008.
A routing schedule applies the same rule on the day it runs. When every vehicle of its profile is under maintenance, the run is skipped with the reason no_vehicle.

​
Vehicle Fields

The vehicle object carries three related fields: POST /vehicle, POST /vehicles/, PUT /vehicle/{vehicleId} and PATCH /vehicle/{vehicleId} reject maintenanceStartTime and maintenanceEndTime with 400 and vehic-042. Record maintenance periods with POST /vehicle-maintenances instead. Deleting a vehicle also permanently deletes its maintenance schedules.

​
Errors

  • Vehicle - The vehicles these schedules belong to
  • Vehicle Object - Vehicle data structure
  • Routing - Route optimization, which leaves out vehicles under maintenance