Deleting Shifts

Delete one or more shifts from a scheduler. Deleted shifts cannot be recovered.

Endpoints

Delete Single Shift

Path Parameters

Example

curl --request DELETE \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/6784dacb3c07733b0a849f49 \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shiftId": "6784dacb3c07733b0a849f49"
  }
}

Delete Multiple Shifts (Bulk)

Delete multiple shifts in a single request.

⚠️

Maximum 20 Shifts

The bulk delete endpoint supports a maximum of 20 shifts per request. Attempting to delete more will result in a 400 error.

Path Parameters

Request Body

Send a JSON body containing the shift IDs to delete (maximum 20).

Example

curl --request DELETE \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "shiftsIds": [
      "6784dacb3c07733b0a849f49",
      "6784dacb3c07733b0a849f50",
      "6784dacb3c07733b0a849f51"
    ]
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shiftsIds": [
      "6784dacb3c07733b0a849f49",
      "6784dacb3c07733b0a849f50",
      "6784dacb3c07733b0a849f51"
    ]
  }
}

Deleting Large Numbers of Shifts

When you need to delete more than 20 shifts, you must batch your requests.

async function deleteShifts(schedulerId, shiftIds) {
  const BATCH_SIZE = 20;
  const allDeleted = [];
  
  // Split into batches of 20
  for (let i = 0; i < shiftIds.length; i += BATCH_SIZE) {
    const batch = shiftIds.slice(i, i + BATCH_SIZE);
    
    const response = await fetch(
      `https://api.connecteam.com/scheduler/v1/schedulers/${schedulerId}/shifts`,
      {
        method: 'DELETE',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ shiftsIds: batch })
      }
    );
    
    const result = await response.json();
    allDeleted.push(...result.data.shiftsIds);
  }
  
  return allDeleted;
}

📝

Batch Processing

Consider adding delays between batch requests to avoid rate limiting. A 1-second delay between batches is recommended for large deletion operations.

Group Shift Deletion (JS Vision)

On JS Vision-migrated companies, how a delete affects a group depends on the API version and the ID you pass:

For the full V1 vs V2 ID rules and examples, see JS Vision: Endpoint-by-Endpoint Reference.

Important Considerations

Notifications

Deletion does not trigger notifications to users by default. If users were assigned to the shift, they will not receive a notification about the cancellation unless your application handles this separately.

Webhook Events

Shift deletions trigger the shift_deleted webhook event if you have configured a scheduler webhook.

Repeating Shifts

⚠️

Repeating Shift Deletion

Deleting a repeating shift will delete all instances of that repeating shift. If you only want to delete a single occurrence, you must first convert it to a non-repeating shift (not currently supported via API).

Already Completed Shifts

You can delete shifts that users have already completed (checked in/out). However, this action is irreversible and may affect reporting.

Error Responses

400 Bad Request

Shift not found:

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

Too many shifts: sending more than 20 IDs returns a 422 validation error (the shiftsIds array exceeds its maximum length of 20).

Empty shift IDs:

{
  "detail": [
    {
      "loc": ["body", "shiftsIds"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

404 Not Found

Single shift not found:

{
  "detail": "Shift not found"
}

Best Practices

1. Verify before deleting: Always confirm the shift IDs before deletion - this operation cannot be undone

2. Handle partial failures: In bulk operations, some shifts may delete successfully while others fail. Check the response carefully

3. Batch large deletions: For more than 20 shifts, use the batching approach shown above

4. Consider timing: Avoid deleting shifts while users may be actively working them

5. Update related systems: After deletion, ensure any external systems that reference these shifts are updated

API Reference