StaffMagic

Shift Swaps Guide

Trade shifts with coworkers using direct swaps or the open marketplace.

This guide explains how to use the shift swap feature in StaffMagic. Shift swaps allow employees to trade shifts with coworkers, subject to manager approval.

Overview

The shift swap system supports two types of swap requests:

  1. Direct Swaps - Offer your shift to a specific coworker
  2. Open Swaps (Marketplace) - Post your shift for anyone to claim

All swaps require manager approval before the shift is officially reassigned.

Using the Web Interface

For Employees

Requesting a Shift Swap

  1. Go to My Schedule from the sidebar
  2. Click on the shift you want to swap
  3. In the shift details sheet, click Request Shift Swap
  4. Choose how you want to offer the shift:
    • Post to Marketplace - Anyone can claim (first come, first served)
    • Offer to Specific Coworker - Only they can accept or decline
  5. Optionally add a reason for the swap
  6. Click Submit Request

Managing Your Swap Requests

Navigate to Shift Swaps from the sidebar to see:

My Requests Tab:

  • View all your pending and past swap requests
  • See the status of each request (Pending, Accepted, Approved, etc.)
  • Cancel requests that are still pending or accepted

Offers to Me Tab:

  • See direct swap offers from coworkers
  • Accept or decline incoming offers
  • View shift details before deciding

Using the Marketplace

Navigate to Marketplace from the sidebar to:

  • Browse available shifts posted by coworkers
  • Filter by location or position (if configured)
  • View shift details including position, date, and time
  • Click Claim This Shift to take a shift
  • After claiming, await manager approval

Note: Your own posted shifts won't appear in the marketplace.

For Managers

Approving Swap Requests

Navigate to Swap Approvals from the sidebar to:

Pending Approval Tab:

  • See all swap requests awaiting your review
  • View who is swapping with whom
  • See conflict warnings if the swap causes scheduling issues
  • Click Approve or Deny for each request
  • Add optional notes explaining your decision

All Requests Tab:

  • View the complete history of swap requests
  • Filter by status (Pending, Accepted, Approved, Denied, etc.)
  • Track swap patterns across your team

Reviewing a Swap

When reviewing a swap request:

  1. Check the shift details (position, date, time)
  2. Review who is giving up the shift and who is taking it
  3. Look for any conflict warnings (scheduling overlaps)
  4. Click Approve to reassign the shift, or Deny to reject
  5. Add notes to explain your decision (optional but helpful)

Warning: If there are conflicts, you'll see a warning badge. You can still approve with the "force" option, but the conflicts will remain.

API Reference

For Employees

Creating a Swap Request

Direct Swap (To a Specific Person)
POST /api/v1/organizations/{org_slug}/shift-swaps/my-requests
Content-Type: application/json

{
  "shift_id": "uuid-of-your-shift",
  "target_user_id": "uuid-of-coworker",
  "notes": "Doctor appointment, can you cover?"
}
Open Swap (Marketplace)

Post your shift so anyone can claim it:

POST /api/v1/organizations/{org_slug}/shift-swaps/my-requests
Content-Type: application/json

{
  "shift_id": "uuid-of-your-shift",
  "notes": "Available for pickup - family event"
}

When target_user_id is omitted, the swap is posted to the marketplace.

Viewing Your Swap Requests

List all swap requests you've created:

GET /api/v1/organizations/{org_slug}/shift-swaps/my-requests

Filter by status:

GET /api/v1/organizations/{org_slug}/shift-swaps/my-requests?status=pending

Cancelling a Swap Request

You can cancel a swap request while it's still pending or accepted (before manager approval):

DELETE /api/v1/organizations/{org_slug}/shift-swaps/my-requests/{request_id}

Responding to Swap Offers

View Offers Directed at You

See swaps that coworkers have offered specifically to you:

GET /api/v1/organizations/{org_slug}/shift-swaps/offers
Accept an Offer
POST /api/v1/organizations/{org_slug}/shift-swaps/offers/{request_id}/accept

After accepting, the request moves to "accepted" status and awaits manager approval.

Decline an Offer
POST /api/v1/organizations/{org_slug}/shift-swaps/offers/{request_id}/decline

Using the Marketplace

Browse Available Shifts

See open swaps available for pickup:

GET /api/v1/organizations/{org_slug}/shift-swaps/marketplace

Filter by location or position:

GET /api/v1/organizations/{org_slug}/shift-swaps/marketplace?location_id=xxx&position_id=yyy

Note: Your own swap requests won't appear in the marketplace.

Claim a Shift
POST /api/v1/organizations/{org_slug}/shift-swaps/marketplace/{request_id}/claim

After claiming, the request moves to "accepted" status and awaits manager approval.

For Managers

Viewing All Swap Requests

See all swap requests in your organization:

GET /api/v1/organizations/{org_slug}/shift-swaps

Filter by status:

GET /api/v1/organizations/{org_slug}/shift-swaps?status=accepted

Pending Approval Queue

See swap requests waiting for your approval:

GET /api/v1/organizations/{org_slug}/shift-swaps/pending

These are requests in "accepted" status (employee accepted/claimed, needs manager review).

Approving a Swap

POST /api/v1/organizations/{org_slug}/shift-swaps/{request_id}/review
Content-Type: application/json

{
  "status": "approved",
  "review_notes": "Approved - enjoy your day off!"
}

When approved:

  • The shift is automatically reassigned from the requester to the accepter
  • Both employees are notified (when notifications are implemented)

Denying a Swap

POST /api/v1/organizations/{org_slug}/shift-swaps/{request_id}/review
Content-Type: application/json

{
  "status": "denied",
  "review_notes": "Sorry, we need experienced staff that day"
}

Status Workflow

Swap Request Statuses

| Status | Description | |--------|-------------| | pending | Awaiting target response (direct) or claim (open) | | accepted | Target accepted/claimed, awaiting manager approval | | approved | Manager approved, shift has been reassigned | | denied | Manager denied the request | | cancelled | Requester cancelled the request | | declined | Target declined the direct offer | | expired | Shift date passed (auto-expired) |

Direct Swap Flow

Employee A creates direct swap to Employee B
                    ↓
            Status: PENDING
                    ↓
         Employee B responds
                    ↓
    ┌───────────────┴───────────────┐
    ↓                               ↓
ACCEPTED                        DECLINED
(B accepted)                    (B said no)
    ↓
Manager reviews
    ↓
┌───┴───┐
↓       ↓
APPROVED  DENIED
(shift    (no change)
reassigned)

Open Swap (Marketplace) Flow

Employee A creates open swap
                    ↓
            Status: PENDING
            (visible in marketplace)
                    ↓
         Employee C claims it
                    ↓
            Status: ACCEPTED
                    ↓
            Manager reviews
                    ↓
            ┌───────┴───────┐
            ↓               ↓
        APPROVED         DENIED
        (shift           (no change)
        reassigned
        to C)

Validation Rules

Creating Swap Requests

  • You can only swap your own shifts
  • Cannot swap a shift that has already started
  • Cannot create multiple swap requests for the same shift
  • Cannot offer a direct swap to yourself

Accepting/Claiming

  • Direct swaps: Only the target user can accept
  • Open swaps: Anyone except the requester can claim
  • Cannot accept/claim an already-accepted request

Manager Review

  • Can only review requests in "accepted" status
  • Cannot review already-reviewed requests
  • Must choose "approved" or "denied" status

API Response Format

Swap Request Object

{
  "id": "uuid",
  "organization_id": "uuid",
  "shift_id": "uuid",
  "requester_id": "uuid",
  "target_user_id": "uuid or null",
  "accepter_id": "uuid or null",
  "type": "direct or open",
  "status": "pending|accepted|approved|denied|cancelled|declined|expired",
  "notes": "string or null",
  "reviewed_by_id": "uuid or null",
  "reviewed_at": "datetime or null",
  "review_notes": "string or null",
  "created_at": "datetime",
  "updated_at": "datetime",
  "shift": {
    "id": "uuid",
    "start_time": "datetime",
    "end_time": "datetime",
    "position_name": "string",
    "location_name": "string"
  },
  "requester": {
    "id": "uuid",
    "first_name": "string",
    "last_name": "string",
    "email": "string"
  },
  "target_user": { ... },
  "accepter": { ... },
  "reviewer": { ... }
}

List Response

{
  "items": [ /* array of swap requests */ ],
  "total": 10,
  "pending_count": 3
}

Permissions

| Action | Owner | Admin | Manager | Employee | |--------|-------|-------|---------|----------| | Create swap for own shift | Yes | Yes | Yes | Yes | | Cancel own swap request | Yes | Yes | Yes | Yes | | Accept/decline offers to me | Yes | Yes | Yes | Yes | | Claim marketplace swaps | Yes | Yes | Yes | Yes | | View all org swap requests | Yes | Yes | Yes | No | | Approve/deny swaps | Yes | Yes | Yes | No |

Tips

  1. Include notes: Help coworkers and managers understand why you need the swap
  2. Check availability: Before claiming a shift, make sure you're available for those hours
  3. Act quickly: Marketplace swaps are first-come, first-served
  4. Direct swaps for reliability: If you need a specific reliable coworker, use direct swaps
  5. Managers: Review swaps promptly to help employees plan

Navigation

| Page | URL | Description | |------|-----|-------------| | My Swaps | /shift-swaps | View and manage your swap requests | | Marketplace | /shift-swaps/marketplace | Browse and claim open shifts | | Swap Approvals | /manage/shift-swaps | Manager approval queue | | My Schedule | /my-schedule | View your schedule and request swaps |

Last updated: December 2024 (Task 26: Shift Swap UI Complete)