Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Labor

  • List break types

  • Create break type

  • Delete break type

  • Get break type

  • Update break type

  • Create scheduled shift

  • Bulk publish scheduled shifts

  • Search scheduled shifts

  • Retrieve scheduled shift

  • Update scheduled shift

  • Publish scheduled shift

  • List team member wages

  • Get team member wage

  • Create timecard

  • Search timecards

  • Delete timecard

  • Retrieve timecard

  • Update timecard

  • List workweek configs

  • Update workweek config

  • Webhooks

  • labor.scheduled_shift.created

  • labor.scheduled_shift.deleted

  • labor.scheduled_shift.published

  • labor.scheduled_shift.updated

  • labor.timecard.created

  • labor.timecard.deleted

  • labor.timecard.updated

<- Labor API

Labor API

All versions ->

Create timecard

POST

 /v2/labor/timecards

Creates a new Timecard.

A Timecard represents a complete workday for a single team member. You must provide the following values in your request to this endpoint:

  • location_id
  • team_member_id
  • start_at

An attempt to create a new Timecard can result in a BAD_REQUEST error when:

  • The status of the new Timecard is OPEN and the team member has another timecard with an OPEN status.
  • The start_at date is in the future.
  • The start_at or end_at date overlaps another timecard for the same team member.
  • The Break instances are set in the request and a break start_at is before the Timecard.start_at, a break end_at is after the Timecard.end_at, or both.
Permissions:TIMECARDS_WRITE

Guide

Time Tracking with the Labor API

Try in API Explorer
Link to section

Request body

Example code

Link to section

idempotency_key

string

A unique string value to ensure the idempotency of the operation.

Max Length
128
Link to section

timecard

Required

The Timecard to be created.

Link to section

Response fields

Link to section

timecard

The Timecard that was created on the request.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/labor/timecards
curl https://connect.squareup.com/v2/labor/timecards \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "HIDSNG5KS478L", "timecard": { "team_member_id": "ormj0jJJZ5OZIzxrZYJI", "location_id": "PAA1RJZZKXBFG", "start_at": "2019-01-25T03:11:00-05:00", "end_at": "2019-01-25T13:11:00-05:00", "wage": { "title": "Barista", "hourly_rate": { "amount": 1100, "currency": "USD" }, "tip_eligible": true }, "breaks": [ { "start_at": "2019-01-25T06:11:00-05:00", "end_at": "2019-01-25T06:16:00-05:00", "break_type_id": "REGS1EQR1TPZ5", "name": "Tea Break", "expected_duration": "PT5M", "is_paid": true } ], "declared_cash_tip_money": { "amount": 500, "currency": "USD" } } }'

Response JSON

{ "timecard": { "id": "K0YH4CV5462JB", "team_member_id": "ormj0jJJZ5OZIzxrZYJI", "location_id": "PAA1RJZZKXBFG", "timezone": "America/New_York", "start_at": "2019-01-25T03:11:00-05:00", "end_at": "2019-01-25T13:11:00-05:00", "wage": { "title": "Barista", "hourly_rate": { "amount": 1100, "currency": "USD" }, "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", "tip_eligible": true }, "breaks": [ { "id": "X7GAQYVVRRG6P", "start_at": "2019-01-25T06:11:00-05:00", "end_at": "2019-01-25T06:16:00-05:00", "break_type_id": "REGS1EQR1TPZ5", "name": "Tea Break", "expected_duration": "PT5M", "is_paid": true } ], "declared_cash_tip_money": { "amount": 500, "currency": "USD" }, "status": "CLOSED", "version": 1, "created_at": "2019-02-28T00:39:02Z", "updated_at": "2019-02-28T00:39:02Z" } }