CreateShift

v1.0.0

Creates a new Shift.

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

location_id
employee_id
start_at

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

The status of the new Shift is OPEN and the employee has another shift with an OPEN status.
The start_at date is in the future.
The start_at or end_at date overlaps another shift for the same employee.
The Break instances are set in the request and a break start_at is before the Shift.start_at, a break end_at is after the Shift.end_at, or both.

Input

{
  "type": "object",
  "description": "Represents a request to create a `Shift`.",
  "required": [
    "shift"
  ],
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "A unique string value to ensure the idempotency of the operation."
    },
    "shift": {
      "type": "object",
      "description": "A record of the hourly rate, start, and end times for a single work shift\nfor an employee. This might include a record of the start and end times for breaks\ntaken during the shift.",
      "required": [
        "start_at"
      ],
      "properties": {
        "breaks": {
          "type": "array",
          "description": "A list of all the paid or unpaid breaks that were taken during this shift.",
          "items": {
            "type": "object",
            "description": "A record of an employee's break during a shift.",
            "required": [
              "start_at",
              "break_type_id",
              "name",
              "expected_duration",
              "is_paid"
            ],
            "properties": {
              "break_type_id": {
                "type": "string",
                "description": "The `BreakType` that this `Break` was templated on."
              },
              "end_at": {
                "type": "string",
                "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
              },
              "expected_duration": {
                "type": "string",
                "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break."
              },
              "id": {
                "type": "string",
                "description": "The UUID for this object."
              },
              "is_paid": {
                "type": "boolean",
                "description": "Whether this break counts towards time worked for compensation\npurposes."
              },
              "name": {
                "type": "string",
                "description": "A human-readable name."
              },
              "start_at": {
                "type": "string",
                "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
              }
            }
          }
        },
        "created_at": {
          "type": "string",
          "description": "A read-only timestamp in RFC 3339 format; presented in UTC."
        },
        "employee_id": {
          "type": "string",
          "description": "The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead."
        },
        "end_at": {
          "type": "string",
          "description": "RFC 3339; shifted to the timezone + offset. Precision up to the minute is\nrespected; seconds are truncated."
        },
        "id": {
          "type": "string",
          "description": "The UUID for this object."
        },
        "location_id": {
          "type": "string",
          "description": "The ID of the location this shift occurred at. The location should be based on\nwhere the employee clocked in."
        },
        "start_at": {
          "type": "string",
          "description": "RFC 3339; shifted to the location timezone + offset. Precision up to the\nminute is respected; seconds are truncated."
        },
        "status": {
          "type": "string",
          "description": "Describes the working state of the current `Shift`."
        },
        "team_member_id": {
          "type": "string",
          "description": "The ID of the team member this shift belongs to. Replaced `employee_id` at version \"2020-08-26\"."
        },
        "timezone": {
          "type": "string",
          "description": "The read-only convenience value that is calculated from the location based\non the `location_id`. Format: the IANA timezone database identifier for the\nlocation timezone."
        },
        "updated_at": {
          "type": "string",
          "description": "A read-only timestamp in RFC 3339 format; presented in UTC."
        },
        "version": {
          "type": "integer",
          "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write; potentially overwriting data from another\nwrite."
        },
        "wage": {
          "type": "object",
          "description": "The hourly wage rate used to compensate an employee for this shift.",
          "properties": {
            "hourly_rate": {
              "type": "object",
              "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
              "properties": {
                "amount": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
                },
                "currency": {
                  "type": "string",
                  "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
                }
              }
            },
            "title": {
              "type": "string",
              "description": "The name of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by title."
            }
          }
        }
      }
    }
  }
}

Output

{
  "type": "object",
  "description": "The response to a request to create a `Shift`. The response contains\nthe created `Shift` object and might contain a set of `Error` objects if\nthe request resulted in errors.",
  "properties": {
    "errors": {
      "type": "array",
      "description": "Any errors that occurred during the request.",
      "items": {
        "type": "object",
        "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.",
        "required": [
          "category",
          "code"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "The high-level category for the error."
          },
          "code": {
            "type": "string",
            "description": "The specific code of the error."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable description of the error for debugging purposes."
          },
          "field": {
            "type": "string",
            "description": "The name of the field provided in the original request (if any) that\nthe error pertains to."
          }
        }
      }
    },
    "shift": {
      "type": "object",
      "description": "A record of the hourly rate, start, and end times for a single work shift\nfor an employee. This might include a record of the start and end times for breaks\ntaken during the shift.",
      "required": [
        "start_at"
      ],
      "properties": {
        "breaks": {
          "type": "array",
          "description": "A list of all the paid or unpaid breaks that were taken during this shift.",
          "items": {
            "type": "object",
            "description": "A record of an employee's break during a shift.",
            "required": [
              "start_at",
              "break_type_id",
              "name",
              "expected_duration",
              "is_paid"
            ],
            "properties": {
              "break_type_id": {
                "type": "string",
                "description": "The `BreakType` that this `Break` was templated on."
              },
              "end_at": {
                "type": "string",
                "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
              },
              "expected_duration": {
                "type": "string",
                "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break."
              },
              "id": {
                "type": "string",
                "description": "The UUID for this object."
              },
              "is_paid": {
                "type": "boolean",
                "description": "Whether this break counts towards time worked for compensation\npurposes."
              },
              "name": {
                "type": "string",
                "description": "A human-readable name."
              },
              "start_at": {
                "type": "string",
                "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated."
              }
            }
          }
        },
        "created_at": {
          "type": "string",
          "description": "A read-only timestamp in RFC 3339 format; presented in UTC."
        },
        "employee_id": {
          "type": "string",
          "description": "The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead."
        },
        "end_at": {
          "type": "string",
          "description": "RFC 3339; shifted to the timezone + offset. Precision up to the minute is\nrespected; seconds are truncated."
        },
        "id": {
          "type": "string",
          "description": "The UUID for this object."
        },
        "location_id": {
          "type": "string",
          "description": "The ID of the location this shift occurred at. The location should be based on\nwhere the employee clocked in."
        },
        "start_at": {
          "type": "string",
          "description": "RFC 3339; shifted to the location timezone + offset. Precision up to the\nminute is respected; seconds are truncated."
        },
        "status": {
          "type": "string",
          "description": "Describes the working state of the current `Shift`."
        },
        "team_member_id": {
          "type": "string",
          "description": "The ID of the team member this shift belongs to. Replaced `employee_id` at version \"2020-08-26\"."
        },
        "timezone": {
          "type": "string",
          "description": "The read-only convenience value that is calculated from the location based\non the `location_id`. Format: the IANA timezone database identifier for the\nlocation timezone."
        },
        "updated_at": {
          "type": "string",
          "description": "A read-only timestamp in RFC 3339 format; presented in UTC."
        },
        "version": {
          "type": "integer",
          "description": "Used for resolving concurrency issues. The request fails if the version\nprovided does not match the server version at the time of the request. If not provided,\nSquare executes a blind write; potentially overwriting data from another\nwrite."
        },
        "wage": {
          "type": "object",
          "description": "The hourly wage rate used to compensate an employee for this shift.",
          "properties": {
            "hourly_rate": {
              "type": "object",
              "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
              "properties": {
                "amount": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
                },
                "currency": {
                  "type": "string",
                  "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
                }
              }
            },
            "title": {
              "type": "string",
              "description": "The name of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by title."
            }
          }
        }
      }
    }
  }
}