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": {
    "deletedShiftIds": ["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

Query Parameters

Example

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

Alternative: Repeated Query Parameters

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

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "deletedShiftIds": [
      "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 idsParam = batch.join(',');
    
    const response = await fetch(
      `https://api.connecteam.com/scheduler/v1/schedulers/${schedulerId}/shifts?shiftIds=${idsParam}`,
      {
        method: 'DELETE',
        headers: { 'X-API-KEY': 'YOUR_API_KEY' }
      }
    );
    
    const result = await response.json();
    allDeleted.push(...result.data.deletedShiftIds);
  }
  
  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

When deleting a shift that is part of a group (has multiple assigned users), the delete operation follows these rules:

📝

Group Shift IDs

In group shifts, each user has their own shift instance with a unique ID. The "root" shift ID represents the group as a whole, while individual IDs represent each user's copy.

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:

{
  "detail": "Maximum 20 shifts can be deleted at once"
}

Empty shift IDs:

{
  "detail": [
    {
      "loc": ["query", "shiftIds"],
      "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