BAbamboohr
Scheduling
Public API

Update Shift

Changed on

Updates a shift by its UUID. Fields not provided will retain their existing values. For published shifts, changes are not applied directly — they are stored as pending (unpublishedChanges) and take effect when the shift is published. recurrenceEditOption is required when the shift already has recurrence settings; ALL and FUTURE edits propagate to published sibling occurrences the same way, staging changes rather than applying them immediately. Sibling shifts may be permanently removed if they no longer conform to changed recurrence fields. If updatedAt is provided and no longer matches the stored value, the update is rejected with 409.

OAuth Scopes: scheduling:shifts.write, time_tracking.write

patch/api/v1/scheduling/shifts/{id}

Request

Path parameters

idstring uuid required

The shift uuid

Request body

namestring nullable

The name of the shift

colorstring

6 character color hex code.

capacityinteger nullable

The expected headcount for the shift. If null, has no restrictions.

claimableboolean

Whether employees can claim this shift. A claimable shift must have a capacity: a request that would leave the shift claimable with a null capacity is rejected with a 422. Not gated by any release toggle.

claimsRequireApprovalboolean

Whether a claim on this shift requires manager approval.

startstring date-time

UTC timestamp of the start of the shift.

endstring date-time

UTC timestamp of the end of the shift.

timezonestring

The timezone for the shift.

recurrenceRulestring nullable

The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.

recurrenceEditOption'instance' | 'future' | 'all'

How should recurrence edits be effective? Edits will not affect any realized shifts regardless of option.

recurrenceDtstartstring date-time nullable

The UTC start time for a recurring shift and the anchor point for the recurrence rule.

recurrenceDtendstring date-time nullable

The UTC end time for a recurring shift.

recurrenceUntilstring date-time nullable

The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE).

employeeIdsinteger[]

What employees are assigned to this shift?

unpublishedChangesunknown
updatedAtstring date-time

The updatedAt value last read for this shift. When provided, the update is rejected with a 409 if the shift has since changed. Omit to skip this check.

Example request

{
  "name": "Front Desk - Morning",
  "color": "00FFAA",
  "capacity": 3,
  "claimable": true,
  "claimsRequireApproval": true,
  "start": "2026-01-14T16:00:00Z",
  "end": "2026-01-14T20:00:00Z",
  "timezone": "America/Denver",
  "recurrenceRule": "FREQ=WEEKLY;BYDAY=MO,WE;INTERVAL=1",
  "recurrenceEditOption": "future",
  "recurrenceDtstart": "2026-01-14T09:00:00Z",
  "recurrenceDtend": "2026-01-14T17:00:00Z",
  "recurrenceUntil": "2026-03-31T17:00:00Z",
  "updatedAt": "2026-01-14T00:00:00Z"
}

Response

Successfully updated a shift

idstring required

The ID of the shift. This can be the UUIDv7 of the shift instance, or a composite ID (<recurringShiftDefinitionId>_<recurrenceId>) for uninstantiated recurring shifts.

scheduleIdstring uuid required

The ID of the schedule the shift belongs to.

namestring nullable

The name of the shift.

status'planned' | 'published' | 'cancelled' | 'deleted' required

The status of the shift.

colorstring required

6 character color hex code.

capacityinteger nullable

The expected headcount for the shift. Null when capacity is not tracked for this shift.

claimableboolean required

Whether employees can claim this shift.

claimsRequireApprovalboolean required

Whether a claim on this shift requires manager approval before it takes effect.

startstring date-time nullable required

UTC timestamp of the start of the shift.

endstring date-time nullable required

UTC timestamp of the end of the shift.

timezonestring required

The timezone for the shift.

recurrenceRulestring nullable

The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.

recurrenceIdstring nullable

The stable identifier for a recurrence, which is the original start of shift according to recurrence rules. Null for non-recurring shifts.

recurrenceDtstartstring nullable

The UTC start time for a recurring shift and the anchor point for the recurrence rule. Null for non-recurring shifts.

recurrenceDtendstring nullable

The UTC end time for a recurring shift. Null for non-recurring shifts.

recurrenceUntilstring nullable

The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE). Null for non-recurring shifts.

employeeIdsinteger[]

The list of employee IDs currently assigned.

unpublishedChangesobject nullable

The pending changes that have not been published.

createdAtstring date-time

UTC timestamp when the shift was created

updatedAtstring date-time nullable

UTC timestamp when the shift was last updated

deletedAtstring date-time nullable

UTC timestamp when the shift was deleted

Example response

{
  "id": "019aa09f-0712-74cb-9186-8ad0eb6038dc_20240101T093000",
  "scheduleId": "0199de9b-6bcb-77e7-941d-3caf74b9a372",
  "name": "Morning Shift",
  "color": "00FFAA",
  "capacity": 1,
  "claimsRequireApproval": true,
  "start": "2025-01-01T06:00:00Z",
  "end": "2025-01-01T14:00:00Z",
  "timezone": "America/Denver",
  "recurrenceRule": "FREQ=WEEKLY;INTERVAL=1",
  "recurrenceId": "20240101T090000",
  "recurrenceDtstart": "2024-01-01T09:00:00Z",
  "recurrenceDtend": "2024-12-31T23:59:59Z",
  "recurrenceUntil": "2024-12-31T23:59:59Z",
  "employeeIds": [
    10,
    20
  ],
  "createdAt": "2025-01-01T06:00:00Z",
  "updatedAt": "2025-01-01T06:00:00Z",
  "deletedAt": "2025-01-01T06:00:00Z"
}

Changes

  • 922fc15f43a7Revision changes
    • warning

      the / request property's max was set to 999.00

    • info

      the security scope scheduling:shifts.write was added to the endpoint's security scheme oauth

    • info

      the security scope time_tracking.write was removed from the endpoint's security scheme oauth

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status