VX Agents

API directory · HR

Square Staff Shifts & Timecards

v1.0.0 · 14 endpoints · 0 connections · shared by vx.ai

Who is working Saturday, and did everyone clock out last night? For salons, cafes and shops on Square: draft and publish the staff rota as scheduled shifts, pull timecards with breaks for payroll checks, fix a missed clock-out, and look up team members, hourly wages and break rules per location.

Connect this API to an AI agent Browse all specs

What you can do with Square Staff Shifts & Timecards via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /v2/locations listLocations List the seller's locations with their ids and time zones
POST /v2/team-members/search searchTeamMembers Find team members by location or status to get their ids
POST /v2/labor/scheduled-shifts/search searchScheduledShifts Find scheduled shifts by location, team member and date range
GET /v2/labor/scheduled-shifts/{id} getScheduledShift Get one scheduled shift with its draft and published details
PUT /v2/labor/scheduled-shifts/{id} updateScheduledShift Change a scheduled shift's draft time, location, job or assignee
POST /v2/labor/scheduled-shifts createScheduledShift Create a draft shift on the schedule for a team member
POST /v2/labor/scheduled-shifts/{id}/publish publishScheduledShift Publish a draft shift so the team member sees it
POST /v2/labor/timecards/search searchTimecards Find timecards (clock-in/out and breaks) by location, team member, status or date
GET /v2/labor/timecards/{id} getTimecard Get one timecard with its breaks, wage and status
PUT /v2/labor/timecards/{id} updateTimecard Fix a timecard, for example add a missed clock-out or break
POST /v2/labor/timecards createTimecard Add a timecard for hours a team member worked
GET /v2/labor/break-types listBreakTypes List the break types (paid or unpaid, length) set up per location
GET /v2/labor/workweek-configs listWorkweekConfigs Get the workweek start day and time used for overtime
GET /v2/labor/team-member-wages listTeamMemberWages List team members' job titles and hourly rates

Authentication

square_token

Bearer token — sent as Authorization: Bearer <token>

Square access token, sent as Authorization: Bearer <token>.

How to get a credential

  1. Sign in to the Square Developer Console (https://developer.squareup.com/apps) with the seller's Square account.
  2. Create an application (or open an existing one).
  3. Switch to Production, open Credentials and copy the Production access token (it acts for your own seller account with full permissions).
  4. To act for other sellers, use OAuth instead and request the scopes below.

Permissions used

OAuth scope Operations
EMPLOYEES_READ searchTeamMembers, listTeamMemberWages
MERCHANT_PROFILE_READ listLocations
TIMECARDS_READ searchScheduledShifts, getScheduledShift, searchTimecards, getTimecard, updateTimecard
TIMECARDS_WRITE createScheduledShift, updateScheduledShift, publishScheduledShift, createTimecard, updateTimecard
TIMECARDS_SETTINGS_READ listBreakTypes, listWorkweekConfigs

Common errors

Status Meaning Fix
401 Token missing, expired or a sandbox token Use the production token; refresh OAuth tokens before they expire.
403 Missing scope or the seller has no access to Shifts Request the scope above; the seller needs Square Team / Shifts enabled.
400 Invalid field or time Send RFC 3339 times with offset and existing team member / location ids.
409 Version conflict Re-read the shift or timecard and resend with its current version.
429 Rate limited Wait and retry with backoff.

Store the token as a VX Agents credential (Bearer token).

Usage guide

Setup

  1. Add the seller's Square production access token (or an OAuth token with the scopes in Authentication) as a VX Agents Bearer credential.
  2. Call listLocations once and pin the shop's location_id in prompts or presets so shifts never land at the wrong branch. Note its timezone.
  3. Square-Version is fixed at 2026-09-16.

Plan next week's rota

  1. searchTeamMembers with query.filter (location_ids, status: ACTIVE) to get team member ids.
  2. searchScheduledShifts with query.filter.location_ids and workday.date_range (start_date/end_date as YYYY-MM-DD) to see what is already planned.
  3. Confirm the shifts with the user, then createScheduledShift per shift: idempotency_key (new UUID) and scheduled_shift.draft_shift_details (team_member_id, location_id, start_at, end_at, optional job_id, notes). New shifts are drafts.
  4. To change one, updateScheduledShift with the new draft_shift_details and the current version.
  5. Publishing tells staff: confirm first, then publishScheduledShift with idempotency_key, version and scheduled_shift_notification_audience (ALL, AFFECTED or NONE).

Check hours worked

  1. searchTimecards with query.filter (location_ids, team_member_ids, status OPEN/CLOSED, workday.date_range). OPEN timecards are people still clocked in.
  2. getTimecard for the breaks, wage and version of one timecard.
  3. To fix a missed clock-out, confirm with the user, then updateTimecard with the full timecard (location_id, team_member_id, start_at, new end_at, existing breaks, version). Breaks need break_type_id from listBreakTypes.
  4. createTimecard adds hours that were never clocked; send a new idempotency_key so a retry does not add them twice.

Good to know

  • Times are RFC 3339 with the location's offset, e.g. 2026-10-24T09:00:00-07:00.
  • listTeamMemberWages gives job titles and hourly_rate (money in the smallest unit, e.g. cents) for cost estimates; listWorkweekConfigs gives the overtime week start.
  • Search results page with cursor; scheduled shifts default to 50 per page, timecards to 200.
  • A 409 or version error means someone else changed the record: read it again and retry with the new version.
  • Deletes are not part of this spec.

Source: Square Labor API reference (https://developer.squareup.com/reference/square/labor-api), checked 2026-10-20.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Square Staff Shifts & Timecards” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • BambooHR Time Off & Employee Directory — Who is out today, and who asked for leave next week? Reads BambooHR's Who's Out calendar and time off requests, looks p…
  • Ashby Candidates & Applications — Where does each candidate stand, and what did the interviewers say? Search Ashby candidates by name or email, read thei…
  • Personio HR — Lets an agent look up employees in Personio, check absence types and existing time-off, book new absences and review at…
  • Clockify Time Off & Holidays — Who is off next week, and how many vacation days does Ana have left? Read Clockify time off policies and balances, list…
  • BambooHR Hiring & Applicant Tracking — Who applied for the open roles this week, and who is still waiting on a reply? Work the BambooHR ATS pipeline: list job…