Updating Shifts

Update one or more existing shifts. Only include fields you want to change - unspecified fields retain their current values.

📘
JS Vision (Scheduler V2)
This page documents the standard V1 API, available on all companies. Editing group / multi-user shifts, changing the set of assignedUserIds, updating openSpots, and isEditForAllUsers require Scheduler V2 on a JS Vision–migrated company — see JS Vision: V1 vs V2 Shifts API.

Endpoint

Method	Endpoint	Description
PUT	/scheduler/v1/schedulers/{schedulerId}/shifts	Update one or more shifts

Path Parameters

Parameter	Type	Required	Description
schedulerId	integer	Yes	The scheduler's unique ID

Query Parameters

Parameter	Type	Default	Description
notifyUsers	boolean	true	Send notifications for changes

Request Body

The request body is an array of shift update objects.

Shift Update Fields

Field	Type	Required	Description
shiftId	string	Yes	The shift ID to update
startTime	integer	No	New start time (Unix timestamp)
endTime	integer	No	New end time (Unix timestamp)
title	string	No	New shift title
jobId	string	No	New associated job ID
timezone	string	No	New timezone (Tz format)
isPublished	boolean	No	Publish/unpublish the shift
isOpenShift	boolean	No	Convert to/from open shift
openSpots	integer	No	Update open spots (JS Vision only)
isRequireAdminApproval	boolean	No	Toggle admin approval requirement
assignedUserIds	array	No	Update assigned users
locationData	object	No	Update location
color	string	No	Update color
notes	array	No	Replace all notes
breaks	array	No	Replace all breaks
customFields	array	No	Update custom field values
isEditForAllUsers	boolean	No	Apply changes to all users in a group shift (Scheduler V2 / JS Vision only)

📝
Partial Updates
Only include fields you want to change. Omitted fields retain their current values.

Group & Multi-User Editing (Scheduler V2 / JS Vision)

Editing a shift that has multiple users, changing the set of assigned users, updating openSpots, and using isEditForAllUsers are Scheduler V2 behaviors, available only on JS Vision–migrated companies. Scheduler V1 rejects these fields. The full request patterns — update all users, replace the whole group, or separate one user — are documented with examples in JS Vision: Endpoint-by-Endpoint Reference.

📘
Quick rule of thumb (V2)

Update fields for everyone (keep all members) -> isEditForAllUsers: true, leave assignedUserIds out.

Change who's on the shift -> isEditForAllUsers: true + the full assignedUserIds list.

Give some people different details -> isEditForAllUsers: false + just those assignedUserIds (they're split onto their own shift).

⚠️ On a multi-user shift, always set isEditForAllUsers. If you explicitly send isEditForAllUsers: false without assignedUserIds on a group / base shift, the request is rejected with a 400 — the API can't tell which user to target. Use isEditForAllUsers: true to edit the whole group, or include assignedUserIds to peel specific users off. A bare update (no isEditForAllUsers, no assignedUserIds) still applies to the whole group.

Restrictions

🚫
Repeating Shifts
Repeating shifts cannot be edited via API. Attempting to update a repeating shift will return an error.

⚠️
Root Open Shift Restriction
When not using JS Vision, you cannot edit the root open shift if there are multiple open spots. This is a legacy architecture limitation.

Examples

Update Shift Time

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?notifyUsers=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "startTime": 1736928000,
      "endTime": 1736956800
    }
  ]'

Update Shift Title and Color

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "title": "Updated Morning Shift",
      "color": "#487037"
    }
  ]'

Publish a Draft Shift

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?notifyUsers=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "isPublished": true,
      "assignedUserIds": [9170357]
    }
  ]'

📝
Publishing Requires Assignment
When publishing a non-open shift, you must ensure at least one user is assigned.

Reassign Shift to Different User

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?notifyUsers=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "assignedUserIds": [9170358]
    }
  ]'

Convert to Open Shift

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "isOpenShift": true,
      "assignedUserIds": [],
      "isRequireAdminApproval": true
    }
  ]'

Update Location

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "locationData": {
        "isReferencedToJob": false,
        "gps": {
          "address": "789 New Location Ave",
          "latitude": 40.7484,
          "longitude": -73.9857
        }
      }
    }
  ]'

Update Breaks

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "breaks": [
        {
          "id": "break-existing-001",
          "name": "Updated Lunch",
          "type": "unpaid",
          "startTime": 750,
          "duration": 45
        },
        {
          "name": "New Afternoon Break",
          "type": "paid",
          "startTime": 900,
          "duration": 15
        }
      ]
    }
  ]'

📝
Updating Breaks

Include id to update an existing break

Omit id to create a new break

Breaks not included in the array will be removed

If a break id doesn't exist, the API returns an error

Update Custom Fields

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "customFields": [
        {
          "id": "field_abc123",
          "value": "PROJ-2024-002"
        },
        {
          "id": "field_def456",
          "value": "CC-Sales"
        }
      ]
    }
  ]'

📝
Partial Custom Field Updates
When updating custom fields, you only need to include the fields you want to change. Other custom field values remain unchanged.

Bulk Update

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "title": "Updated Shift 1"
    },
    {
      "shiftId": "6784dacb3c07733b0a849f50",
      "isPublished": true
    },
    {
      "shiftId": "6784dacb3c07733b0a849f51",
      "color": "#AE2121"
    }
  ]'

Response

The update response may include additional fields for group shift operations:

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shifts": [
      {
        "id": "6784dacb3c07733b0a849f49",
        "title": "Updated Shift",
        "color": "#4B7AC5",
        "assignedUserIds": [9170357],
        "startTime": 1736928000,
        "endTime": 1736956800,
        "timezone": "America/New_York",
        "isOpenShift": false,
        "isPublished": true,
        "updateTime": 1736761000
      }
    ],
    "deletedShiftIds": [],
    "createdShifts": []
  }
}

Response Fields

Field	Type	Description
shifts	array	Updated shifts
deletedShiftIds	array	Shift IDs deleted during update (e.g., when removing users from group)
createdShifts	array	New shifts created during update (e.g., when splitting a group shift)

📝
Group Shift Side Effects
On Scheduler V2 (JS Vision), updating a group shift may delete some slots (returned in deletedShiftIds) or create new ones (returned in createdShifts). On V1 both arrays are always empty.

Error Responses

400 Bad Request

Shift not found:

{
  "detail": "Shifts with ids ['invalid-shift-id'] not found"
}

Repeating shift:

{
  "detail": "Editing repeating shifts is not supported at the moment (id: 6784dacb3c07733b0a849f49)"
}

Invalid isEditForAllUsers:

{
  "detail": "is_edit_for_all_users can be set only for shifts that are part of a group"
}

Targeted V2 group edit without assignedUserIds:

{
  "detail": "Invalid shift update request. For targeted V2 Vision base/group edits, assignedUserIds must be provided when isEditForAllUsers is explicitly false."
}

Break not found:

{
  "detail": "A break with the id 'invalid-break-id' cannot be found."
}

Root open shift edit:

{
  "detail": "can't edit root open shift with multiple open spots"
}

API Reference