diff --git a/.mock/definition/__package__.yml b/.mock/definition/__package__.yml index 19a3e9a6..18627737 100644 --- a/.mock/definition/__package__.yml +++ b/.mock/definition/__package__.yml @@ -1178,7 +1178,7 @@ types: source: openapi: openapi/openapi.json Break: - docs: A record of an employee's break during a shift. + docs: A record of a team member's break on a [timecard](entity:Timecard). properties: id: type: optional @@ -1186,8 +1186,8 @@ types: start_at: type: string docs: >- - RFC 3339; follows the same timezone information as `Shift`. Precision - up to + RFC 3339; follows the same timezone information as the + [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. validation: @@ -1195,13 +1195,13 @@ types: end_at: type: optional> docs: >- - RFC 3339; follows the same timezone information as `Shift`. Precision - up to + RFC 3339; follows the same timezone information as the + [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. break_type_id: type: string - docs: The `BreakType` that this `Break` was templated on. + docs: The [BreakType](entity:BreakType) that this break was templated on. validation: minLength: 1 name: @@ -1214,6 +1214,8 @@ types: docs: |- Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of the break. + + Example for break expected duration of 15 minutes: PT15M validation: minLength: 1 is_paid: @@ -1224,9 +1226,11 @@ types: source: openapi: openapi/openapi.json BreakType: - docs: |- - A defined break template that sets an expectation for possible `Break` - instances on a `Shift`. + docs: >- + A template for a type of [break](entity:Break) that can be added to a + + [timecard](entity:Timecard), including the expected duration and paid + status. properties: id: type: optional @@ -1242,7 +1246,7 @@ types: type: string docs: |- A human-readable name for this type of break. The name is displayed to - employees in Square products. + team members in Square products. validation: minLength: 1 expected_duration: @@ -1251,7 +1255,7 @@ types: Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of this break. Precision less than minutes is truncated. - Example for break expected duration of 15 minutes: T15M + Example for break expected duration of 15 minutes: PT15M validation: minLength: 1 is_paid: @@ -1653,6 +1657,62 @@ types: or an `errors` field. source: openapi: openapi/openapi.json + BulkPublishScheduledShiftsData: + docs: >- + Represents options for an individual publish request in a + + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) + + operation, provided as the value in a key-value pair. + properties: + version: + type: optional + docs: >- + The current version of the scheduled shift, used to enable [optimistic + concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + + control. If the provided version doesn't match the server version, the + request fails. + + If omitted, Square executes a blind write, potentially overwriting + data from another publish request. + source: + openapi: openapi/openapi.json + BulkPublishScheduledShiftsResponse: + docs: >- + Represents a + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) + response. + + Either `scheduled_shifts` or `errors` is present in the response. + properties: + responses: + type: optional> + docs: >- + A map of key-value pairs that represent responses for individual + publish requests. + + The order of responses might differ from the order in which the + requests were provided. + + + - Each key is the scheduled shift ID that was specified for a publish + request. + + - Each value is the corresponding response. If the request succeeds, + the value is the + + published scheduled shift. If the request fails, the value is an + `errors` array containing + + any errors that occurred while processing the request. + errors: + type: optional> + docs: >- + Any top-level errors that prevented the bulk operation from + succeeding. + source: + openapi: openapi/openapi.json BulkRetrieveBookingsResponse: docs: Response payload for bulk retrieval of bookings. properties: @@ -4223,13 +4283,13 @@ types: ecom_uri: type: optional> docs: >- - Deprecated; see go/ecomUriUseCases. A URI pointing to a published - e-commerce product page for the Item. + Deprecated. A URI pointing to a published e-commerce product page for + the Item. ecom_image_uris: type: optional>> docs: >- - Deprecated; see go/ecomUriUseCases. A comma-separated list of encoded - URIs pointing to a set of published e-commerce images for the Item. + Deprecated. A comma-separated list of encoded URIs pointing to a set + of published e-commerce images for the Item. image_ids: type: optional>> docs: |- @@ -4454,10 +4514,10 @@ types: openapi: openapi/openapi.json CatalogItemModifierListInfo: docs: >- - References a text-based modifier or a list of non text-based modifiers - applied to a `CatalogItem` instance + Controls how a modifier list is applied to a specific item. This object + allows for item-specific customization of modifier list behavior - and specifies supported behaviors of the application. + and provides the ability to override global modifier list settings. properties: modifier_list_id: type: string @@ -4469,60 +4529,49 @@ types: modifier_overrides: type: optional>> docs: >- - A set of `CatalogModifierOverride` objects that override whether a - given `CatalogModifier` is enabled by default. + A set of `CatalogModifierOverride` objects that override default + modifier settings for this item. min_selected_modifiers: type: optional> docs: >- - If 0 or larger, the smallest number of `CatalogModifier`s that must be - selected from this `CatalogModifierList`. - - The default value is `-1`. + The minimum number of modifiers that must be selected from this + modifier list. + Values: - When `CatalogModifierList.selection_type` is `MULTIPLE`, - `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from - zero to the maximum number of modifiers of + - 0: No selection is required. - the `CatalogModifierList` can be selected from the - `CatalogModifierList`. + - -1: Default value, the attribute was not set by the client. When + `max_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the + `CatalogItemModifierList`. - When the `CatalogModifierList.selection_type` is `SINGLE`, - `CatalogModifierListInfo.min_selected_modifiers=-1` + - >0: The required minimum modifier selections. This can be larger + than the total `CatalogModifiers` when `allow_quantities` is enabled. - and `CatalogModifierListInfo.max_selected_modifier=-1` means that - exactly one modifier must be present in - - and can be selected from the `CatalogModifierList` + - < -1: Invalid. Treated as no selection required. max_selected_modifiers: type: optional> docs: >- - If 0 or larger, the largest number of `CatalogModifier`s that can be - selected from this `CatalogModifierList`. - - The default value is `-1`. + The maximum number of modifiers that can be selected. + Values: - When `CatalogModifierList.selection_type` is `MULTIPLE`, - `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from - zero to the maximum number of modifiers of + - 0: No maximum limit. - the `CatalogModifierList` can be selected from the - `CatalogModifierList`. + - -1: Default value, the attribute was not set by the client. When + `min_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the + `CatalogItemModifierList`. - When the `CatalogModifierList.selection_type` is `SINGLE`, - `CatalogModifierListInfo.min_selected_modifiers=-1` + - >0: The maximum total modifier selections. This can be larger + than the total `CatalogModifiers` when `allow_quantities` is enabled. - and `CatalogModifierListInfo.max_selected_modifier=-1` means that - exactly one modifier must be present in - - and can be selected from the `CatalogModifierList` + - < -1: Invalid. Treated as no maximum limit. enabled: type: optional> docs: >- @@ -4535,6 +4584,9 @@ types: `modifier_list_info` list applied to a `CatalogItem` instance. + allow_quantities: optional + is_conversational: optional + hidden_from_customer_override: optional source: openapi: openapi/openapi.json CatalogItemOption: @@ -4906,8 +4958,9 @@ types: openapi: openapi/openapi.json CatalogModifier: docs: >- - A modifier applicable to items at the time of sale. An example of a - modifier is a Cheese add-on to a Burger item. + A modifier that can be applied to items at the time of sale. For example, + a cheese modifier for a burger, or a flavor modifier for a serving of ice + cream. properties: name: type: optional> @@ -4920,6 +4973,14 @@ types: price_money: type: optional docs: The modifier price. + on_by_default: + type: optional> + docs: >- + When `true`, this modifier is selected by default when displaying the + modifier list. + + This setting can be overridden at the item level using + `CatalogModifierListInfo.modifier_overrides`. ordinal: type: optional> docs: >- @@ -4938,37 +4999,29 @@ types: Currently this image is not displayed by Square, but is free to be displayed in 3rd party applications. + hidden_online: + type: optional> + docs: >- + When `true`, this modifier is hidden from online ordering channels. + This setting can be overridden at the item level using + `CatalogModifierListInfo.modifier_overrides`. source: openapi: openapi/openapi.json CatalogModifierList: docs: >- - For a text-based modifier, this encapsulates the modifier's text when its - `modifier_type` is `TEXT`. - - For example, to sell T-shirts with custom prints, a text-based modifier - can be used to capture the buyer-supplied - - text string to be selected for the T-shirt at the time of sale. - + A container for a list of modifiers, or a text-based modifier. - For non text-based modifiers, this encapsulates a non-empty list of - modifiers applicable to items + For text-based modifiers, this represents text configuration for an item. + (For example, custom text to print on a t-shirt). - at the time of sale. Each element of the modifier list is a - `CatalogObject` instance of the `MODIFIER` type. + For non text-based modifiers, this represents a list of modifiers that can + be applied to items at the time of sale. - For example, a "Condiments" modifier list applicable to a "Hot Dog" item + (For example, a list of condiments for a hot dog, or a list of ice cream + flavors). - may contain "Ketchup", "Mustard", and "Relish" modifiers. - - - A non text-based modifier can be applied to the modified item once or - multiple times, if the `selection_type` field - - is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a - text-based modifier can be applied to the item - - only once and the `selection_type` field is always set to `SINGLE`. + Each element of the modifier list is a `CatalogObject` instance of the + `MODIFIER` type. properties: name: type: optional> @@ -4988,14 +5041,10 @@ types: selection_type: type: optional docs: >- - Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) - modifiers from the list + __Deprecated__: Indicates whether a single (`SINGLE`) modifier or + multiple (`MULTIPLE`) modifiers can be selected. Use - can be applied to a single `CatalogItem`. - - - For text-based modifiers, the `selection_type` attribute is always - `SINGLE`. The other value is ignored. + `min_selected_modifiers` and `max_selected_modifiers` instead. See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) @@ -5032,6 +5081,14 @@ types: Currently these images are not displayed on Square products, but may be displayed in 3rd-party applications. + allow_quantities: + type: optional> + docs: >- + When `true`, allows multiple quantities of the same modifier to be + selected. + is_conversational: + type: optional> + docs: True if modifiers belonging to this list can be used conversationally. modifier_type: type: optional docs: >- @@ -5084,6 +5141,52 @@ types: internal use. validation: maxLength: 512 + min_selected_modifiers: + type: optional> + docs: >- + The minimum number of modifiers that must be selected from this list. + The value can be overridden with `CatalogItemModifierListInfo`. + + + Values: + + + - 0: No selection is required. + + - -1: Default value, the attribute was not set by the client. Treated + as no selection required. + + - >0: The required minimum modifier selections. This can be larger + than the total `CatalogModifiers` when `allow_quantities` is enabled. + + - < -1: Invalid. Treated as no selection required. + max_selected_modifiers: + type: optional> + docs: >- + The maximum number of modifiers that must be selected from this list. + The value can be overridden with `CatalogItemModifierListInfo`. + + + Values: + + + - 0: No maximum limit. + + - -1: Default value, the attribute was not set by the client. Treated + as no maximum limit. + + - >0: The maximum total modifier selections. This can be larger + than the total `CatalogModifiers` when `allow_quantities` is enabled. + + - < -1: Invalid. Treated as no maximum limit. + hidden_from_customer: + type: optional> + docs: >- + If `true`, modifiers from this list are hidden from customer receipts. + The default value is `false`. + + This setting can be overridden with + `CatalogItemModifierListInfo.hidden_from_customer_override`. source: openapi: openapi/openapi.json CatalogModifierListModifierType: @@ -5114,9 +5217,9 @@ types: minLength: 1 on_by_default: type: optional> - docs: >- - If `true`, this `CatalogModifier` should be selected by default for - this `CatalogItem`. + docs: '__Deprecated__: Use `on_by_default_override` instead.' + hidden_online_override: optional + on_by_default_override: optional source: openapi: openapi/openapi.json CatalogObject: @@ -7631,6 +7734,26 @@ types: docs: The newly created payment. source: openapi: openapi/openapi.json + CreateScheduledShiftResponse: + docs: >- + Represents a + [CreateScheduledShift](api-endpoint:Labor-CreateScheduledShift) response. + + Either `scheduled_shift` or `errors` is present in the response. + properties: + scheduled_shift: + type: optional + docs: >- + The new scheduled shift. To make the shift public, call + + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json CreateShiftResponse: docs: |- The response to a request to create a `Shift`. The response contains @@ -7735,6 +7858,23 @@ types: docs: The created `TerminalRefund`. source: openapi: openapi/openapi.json + CreateTimecardResponse: + docs: >- + The response to a request to create a `Timecard`. The response contains + + the created `Timecard` object and might contain a set of `Error` objects + if + + the request resulted in errors. + properties: + timecard: + type: optional + docs: The `Timecard` that was created on the request. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json CreateVendorResponse: docs: >- Represents an output from a call to @@ -9487,6 +9627,18 @@ types: docs: The subscription that has the specified action deleted. source: openapi: openapi/openapi.json + DeleteTimecardResponse: + docs: >- + The response to a request to delete a `Timecard`. The response might + contain a set of + + `Error` objects if the request resulted in errors. + properties: + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json DeleteWebhookSubscriptionResponse: docs: >- Defines the fields that are included in the response body of @@ -21253,6 +21405,22 @@ types: docs: Information about errors encountered during the request. source: openapi: openapi/openapi.json + PublishScheduledShiftResponse: + docs: >- + Represents a + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) + response. + + Either `scheduled_shift` or `errors` is present in the response. + properties: + scheduled_shift: + type: optional + docs: The published scheduled shift. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json QrCodeOptions: docs: Fields to describe the action that displays QR-Codes. properties: @@ -22093,6 +22261,22 @@ types: docs: The payment link that is retrieved. source: openapi: openapi/openapi.json + RetrieveScheduledShiftResponse: + docs: >- + Represents a + [RetrieveScheduledShift](api-endpoint:Labor-RetrieveScheduledShift) + response. + + Either `scheduled_shift` or `errors` is present in the response. + properties: + scheduled_shift: + type: optional + docs: The requested scheduled shift. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json GetSnippetResponse: docs: >- Represents a `RetrieveSnippet` response. The response can include either @@ -22144,6 +22328,23 @@ types: docs: The errors that occurred during the request. source: openapi: openapi/openapi.json + RetrieveTimecardResponse: + docs: >- + A response to a request to get a `Timecard`. The response contains + + the requested `Timecard` object and might contain a set of `Error` objects + if + + the request resulted in errors. + properties: + timecard: + type: optional + docs: The requested `Timecard`. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json RetrieveTokenStatusResponse: docs: |- Defines the fields that are included in the response body of @@ -22312,86 +22513,406 @@ types: maxLength: 128 source: openapi: openapi/openapi.json - SearchAvailabilityFilter: - docs: A query filter to search for buyer-accessible availabilities by. + ScheduledShift: + docs: >- + Represents a specific time slot in a work schedule. This object is used to + manage the + + lifecycle of a scheduled shift from the draft to published state. A + scheduled shift contains + + the latest draft shift details and current published shift details. properties: - start_at_range: - type: TimeRange + id: + type: optional + docs: '**Read only** The Square-issued ID of the scheduled shift.' + validation: + maxLength: 255 + draft_shift_details: + type: optional docs: >- - The query expression to search for buy-accessible availabilities with - their starting times falling within the specified time range. + The latest draft shift details for the scheduled shift. Draft shift + details are used to - The time range must be at least 24 hours and at most 32 days long. + stage and manage shifts before publishing. This field is always + present. + published_shift_details: + type: optional + docs: >- + The current published (public) shift details for the scheduled shift. + This field is - For waitlist availabilities, the time range can be 0 or more up to 367 - days long. - location_id: - type: optional> + present only if the shift was published. + version: + type: optional docs: >- - The query expression to search for buyer-accessible availabilities - with their location IDs matching the specified location ID. + **Read only** The current version of the scheduled shift, which is + incremented with each update. - This query expression cannot be set if `booking_id` is set. - validation: - maxLength: 32 - segment_filters: - type: optional>> + This field is used for [optimistic + concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + + control to ensure that requests don't overwrite data from another + request. + created_at: + type: optional docs: >- - The query expression to search for buyer-accessible availabilities - matching the specified list of segment filters. + The timestamp of when the scheduled shift was created, in RFC 3339 + format presented as UTC. + access: read-only + updated_at: + type: optional + docs: >- + The timestamp of when the scheduled shift was last updated, in RFC + 3339 format presented as UTC. + access: read-only + source: + openapi: openapi/openapi.json + ScheduledShiftDetails: + docs: >- + Represents shift details for draft and published versions of a [scheduled + shift](entity:ScheduledShift), - If the size of the `segment_filters` list is `n`, the search returns - availabilities with `n` segments per availability. + such as job ID, team member assignment, and start and end times. + properties: + team_member_id: + type: optional> + docs: >- + The ID of the [team member](entity:TeamMember) scheduled for the + shift. + validation: + maxLength: 255 + location_id: + type: optional> + docs: The ID of the [location](entity:Location) the shift is scheduled for. + validation: + maxLength: 255 + job_id: + type: optional> + docs: The ID of the [job](entity:Job) the shift is scheduled for. + start_at: + type: optional> + docs: >- + The start time of the shift, in RFC 3339 format in the time zone + + + offset of the shift location specified in `location_id`. Precision up + to the minute - This query expression cannot be set if `booking_id` is set. - booking_id: + is respected; seconds are truncated. + end_at: type: optional> docs: >- - The query expression to search for buyer-accessible availabilities for - an existing booking by matching the specified `booking_id` value. + The end time for the shift, in RFC 3339 format in the time zone + - This is commonly used to reschedule an appointment. + offset of the shift location specified in `location_id`. Precision up + to the minute - If this expression is set, the `location_id` and `segment_filters` - expressions cannot be set. + is respected; seconds are truncated. + notes: + type: optional> + docs: Optional notes for the shift. validation: - maxLength: 36 - source: - openapi: openapi/openapi.json - SearchAvailabilityQuery: - docs: The query used to search for buyer-accessible availabilities of bookings. - properties: - filter: - type: SearchAvailabilityFilter + maxLength: 1000 + is_deleted: + type: optional> docs: >- - The query filter to search for buyer-accessible availabilities of - existing bookings. - source: - openapi: openapi/openapi.json - SearchAvailabilityResponse: - properties: - availabilities: - type: optional> - docs: List of appointment slots available for booking. - errors: - type: optional> - docs: Errors that occurred during the request. - source: - openapi: openapi/openapi.json - SearchCatalogItemsRequestStockLevel: - enum: - - OUT - - LOW - docs: Defines supported stock levels of the item inventory. + Indicates whether the draft shift version is deleted. If set to `true` + when the shift + + is published, the entire scheduled shift (including the published + shift) is deleted and + + cannot be accessed using any endpoint. + timezone: + type: optional + docs: >- + The time zone of the shift location, calculated based on the + `location_id`. This field + + is provided for convenience. + access: read-only source: openapi: openapi/openapi.json - SearchCatalogItemsResponse: + ScheduledShiftFilter: docs: >- - Defines the response body returned from the - [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint. + Defines filter criteria for a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + + request. Multiple filters in a query are combined as an `AND` operation. properties: - errors: + location_ids: + type: optional>> + docs: >- + Return shifts for the specified locations. When omitted, shifts for + all + + locations are returned. If needed, call + [ListLocations](api-endpoint:Locations-ListLocations) + + to get location IDs. + start: + type: optional + docs: |- + Return shifts whose `start_at` time is within the specified + time range (inclusive). + end: + type: optional + docs: |- + Return shifts whose `end_at` time is within the specified + time range (inclusive). + workday: + type: optional + docs: Return shifts based on a workday date range. + team_member_ids: + type: optional>> + docs: >- + Return shifts assigned to specified team members. If needed, call + + [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get team + member IDs. + + + To return only the shifts assigned to the specified team members, + include the + + `assignment_status` filter in the query. Otherwise, all unassigned + shifts are + + returned along with shifts assigned to the specified team members. + assignment_status: + type: optional + docs: >- + Return shifts based on whether a team member is assigned. A shift is + + assigned if the `team_member_id` field is populated in the + `draft_shift_details` + + or `published_shift details` field of the shift. + + + To return only draft or published shifts, include the + `scheduled_shift_statuses` + + filter in the query. + + See + [ScheduledShiftFilterAssignmentStatus](#type-scheduledshiftfilterassignmentstatus) + for possible values + scheduled_shift_statuses: + type: optional>> + docs: >- + Return shifts based on the draft or published status of the shift. + + A shift is published if the `published_shift_details` field is + present. + + + Note that shifts with `draft_shift_details.is_deleted` set to `true` + are ignored + + with the `DRAFT` filter. + + See + [ScheduledShiftFilterScheduledShiftStatus](#type-scheduledshiftfilterscheduledshiftstatus) + for possible values + source: + openapi: openapi/openapi.json + ScheduledShiftFilterAssignmentStatus: + enum: + - ASSIGNED + - UNASSIGNED + docs: |- + Defines valid values for the `assignment_status` filter in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + Assignment status is based on the `draft_shift_details.team_member_id` and + `published_shift_details.team_member_id` fields of the scheduled shift. + source: + openapi: openapi/openapi.json + ScheduledShiftFilterScheduledShiftStatus: + enum: + - DRAFT + - PUBLISHED + docs: |- + Defines valid values for the `scheduled_shift_statuses` filter in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + source: + openapi: openapi/openapi.json + ScheduledShiftNotificationAudience: + enum: + - ALL + - AFFECTED + - NONE + docs: >- + Indicates whether Square sends an email notification to team members + + when a scheduled shift is published and which team members receive the + notification. + source: + openapi: openapi/openapi.json + ScheduledShiftQuery: + docs: |- + Represents filter and sort criteria for the `query` field in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + properties: + filter: + type: optional + docs: Filtering options for the query. + sort: + type: optional + docs: Sorting options for the query. + source: + openapi: openapi/openapi.json + ScheduledShiftSort: + docs: >- + Defines sort criteria for a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + + request. + properties: + field: + type: optional + docs: >- + The field to sort on. The default value is `START_AT`. + + See [ScheduledShiftSortField](#type-scheduledshiftsortfield) for + possible values + order: + type: optional + docs: |- + The order in which results are returned. The default value is `ASC`. + See [SortOrder](#type-sortorder) for possible values + source: + openapi: openapi/openapi.json + ScheduledShiftSortField: + enum: + - START_AT + - END_AT + - CREATED_AT + - UPDATED_AT + docs: |- + Defines valid values for the `field` sort setting in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + source: + openapi: openapi/openapi.json + ScheduledShiftWorkday: + docs: >- + A `ScheduledShift` search query filter parameter that sets a range of days + that + + a `Shift` must start or end in before passing the filter condition. + properties: + date_range: + type: optional + docs: Dates for fetching the scheduled shifts. + match_scheduled_shifts_by: + type: optional + docs: >- + The strategy on which the dates are applied. + + See [ScheduledShiftWorkdayMatcher](#type-scheduledshiftworkdaymatcher) + for possible values + default_timezone: + type: optional> + docs: >- + Location-specific timezones convert workdays to datetime filters. + + Every location included in the query must have a timezone or this + field + + must be provided as a fallback. Format: the IANA timezone database + + identifier for the relevant timezone. + source: + openapi: openapi/openapi.json + ScheduledShiftWorkdayMatcher: + enum: + - START_AT + - END_AT + - INTERSECTION + docs: Defines the logic used to apply a workday filter. + source: + openapi: openapi/openapi.json + SearchAvailabilityFilter: + docs: A query filter to search for buyer-accessible availabilities by. + properties: + start_at_range: + type: TimeRange + docs: >- + The query expression to search for buy-accessible availabilities with + their starting times falling within the specified time range. + + The time range must be at least 24 hours and at most 32 days long. + + For waitlist availabilities, the time range can be 0 or more up to 367 + days long. + location_id: + type: optional> + docs: >- + The query expression to search for buyer-accessible availabilities + with their location IDs matching the specified location ID. + + This query expression cannot be set if `booking_id` is set. + validation: + maxLength: 32 + segment_filters: + type: optional>> + docs: >- + The query expression to search for buyer-accessible availabilities + matching the specified list of segment filters. + + If the size of the `segment_filters` list is `n`, the search returns + availabilities with `n` segments per availability. + + + This query expression cannot be set if `booking_id` is set. + booking_id: + type: optional> + docs: >- + The query expression to search for buyer-accessible availabilities for + an existing booking by matching the specified `booking_id` value. + + This is commonly used to reschedule an appointment. + + If this expression is set, the `location_id` and `segment_filters` + expressions cannot be set. + validation: + maxLength: 36 + source: + openapi: openapi/openapi.json + SearchAvailabilityQuery: + docs: The query used to search for buyer-accessible availabilities of bookings. + properties: + filter: + type: SearchAvailabilityFilter + docs: >- + The query filter to search for buyer-accessible availabilities of + existing bookings. + source: + openapi: openapi/openapi.json + SearchAvailabilityResponse: + properties: + availabilities: + type: optional> + docs: List of appointment slots available for booking. + errors: + type: optional> + docs: Errors that occurred during the request. + source: + openapi: openapi/openapi.json + SearchCatalogItemsRequestStockLevel: + enum: + - OUT + - LOW + docs: Defines supported stock levels of the item inventory. + source: + openapi: openapi/openapi.json + SearchCatalogItemsResponse: + docs: >- + Defines the response body returned from the + [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint. + properties: + errors: type: optional> docs: Any errors that occurred during the request. items: @@ -22968,6 +23489,29 @@ types: type: list source: openapi: openapi/openapi.json + SearchScheduledShiftsResponse: + docs: >- + Represents a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + response. + + Either `scheduled_shifts` or `errors` is present in the response. + properties: + scheduled_shifts: + type: optional> + docs: A paginated list of scheduled shifts that match the query conditions. + cursor: + type: optional + docs: >- + The pagination cursor used to retrieve the next page of results. This + field is present + + only if additional results are available. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json SearchShiftsResponse: docs: >- The response to a request for `Shift` objects. The response contains @@ -23180,6 +23724,26 @@ types: for more information. source: openapi: openapi/openapi.json + SearchTimecardsResponse: + docs: >- + The response to a request for `Timecard` objects. The response contains + + the requested `Timecard` objects and might contain a set of `Error` + objects if + + the request resulted in errors. + properties: + timecards: + type: optional> + docs: Timecards. + cursor: + type: optional + docs: An opaque cursor for fetching the next page. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json SearchVendorsRequestFilter: docs: Defines supported query expressions to search for vendors by. properties: @@ -23322,6 +23886,13 @@ types: for breaks taken during the shift. + + + Deprecated at Square API version 2025-05-21. Replaced by + [Timecard](entity:Timecard). + + See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: id: type: optional @@ -23420,9 +23991,14 @@ types: source: openapi: openapi/openapi.json ShiftFilter: - docs: |- + docs: >- Defines a filter used in a search for `Shift` records. `AND` logic is + used by Square's servers to apply each filter property specified. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: location_ids: type: optional>> @@ -23457,13 +24033,22 @@ types: enum: - OPEN - CLOSED - docs: Specifies the `status` of `Shift` records to be returned. + docs: >- + Specifies the `status` of `Shift` records to be returned. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). source: openapi: openapi/openapi.json ShiftQuery: docs: >- The parameters of a `Shift` search query, which includes filter and sort options. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: filter: type: optional @@ -23474,7 +24059,12 @@ types: source: openapi: openapi/openapi.json ShiftSort: - docs: Sets the sort order of search results. + docs: >- + Sets the sort order of search results. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: field: type: optional @@ -23494,18 +24084,33 @@ types: - END_AT - CREATED_AT - UPDATED_AT - docs: Enumerates the `Shift` fields to sort on. + docs: >- + Enumerates the `Shift` fields to sort on. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). source: openapi: openapi/openapi.json ShiftStatus: enum: - OPEN - CLOSED - docs: Enumerates the possible status of a `Shift`. + docs: >- + Enumerates the possible status of a `Shift`. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). source: openapi: openapi/openapi.json ShiftWage: - docs: The hourly wage rate used to compensate an employee for this shift. + docs: >- + The hourly wage rate used to compensate an employee for this shift. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: title: type: optional> @@ -23517,11 +24122,9 @@ types: wage based on the annual wage and hours worked per week. job_id: type: optional - docs: >- + docs: |- The id of the job performed during this shift. Square - - labor-reporting UIs might group shifts together by id. This cannot be - used to retrieve the job. + labor-reporting UIs might group shifts together by id. access: read-only tip_eligible: type: optional> @@ -23529,9 +24132,14 @@ types: source: openapi: openapi/openapi.json ShiftWorkday: - docs: |- + docs: >- A `Shift` search query filter parameter that sets a range of days that + a `Shift` must start or end in before passing the filter condition. + + + Deprecated at Square API version 2025-05-21. See the [migration + notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). properties: date_range: type: optional @@ -24405,11 +25013,10 @@ types: source: openapi: openapi/openapi.json TeamMemberWage: - docs: >- - The hourly wage rate that a team member earns on a `Shift` for doing the - job - - specified by the `title` property of this object. + docs: |- + Job and wage information for a [team member](entity:TeamMember). + This convenience object provides details needed to specify the `wage` + field for a [timecard](entity:Timecard). properties: id: type: optional @@ -24427,9 +25034,7 @@ types: wage based on the annual wage and hours worked per week. job_id: type: optional> - docs: |- - An identifier for the job that this wage relates to. This cannot be - used to retrieve the job. + docs: An identifier for the [job](entity:Job) that this wage relates to. tip_eligible: type: optional> docs: Whether team members are eligible for tips when working this job. @@ -25346,6 +25951,255 @@ types: ends. source: openapi: openapi/openapi.json + Timecard: + docs: >- + A record of the hourly rate, start time, and end time of a single timecard + (shift) + + for a team member. This might include a record of the start and end times + of breaks + + taken during the shift. + properties: + id: + type: optional + docs: '**Read only** The Square-issued UUID for this object.' + validation: + maxLength: 255 + location_id: + type: string + docs: >- + The ID of the [location](entity:Location) for this timecard. The + location should be based on + + where the team member clocked in. + validation: + minLength: 1 + timezone: + type: optional> + docs: >- + **Read only** The time zone calculated from the location based on the + `location_id`, + + provided as a convenience value. Format: the IANA time zone database + identifier for the + + location time zone. + start_at: + type: string + docs: >- + The start time of the timecard, in RFC 3339 format and shifted to the + location + + timezone + offset. Precision up to the minute is respected; seconds + are truncated. + validation: + minLength: 1 + end_at: + type: optional> + docs: >- + The end time of the timecard, in RFC 3339 format and shifted to the + location + + timezone + offset. Precision up to the minute is respected; seconds + are truncated. + wage: + type: optional + docs: >- + Job and pay related information. If the wage is not set on create, it + defaults to a wage + + of zero. If the title is not set on create, it defaults to the name of + the role the team member + + is assigned to, if any. + breaks: + type: optional>> + docs: >- + A list of all the paid or unpaid breaks that were taken during this + timecard. + status: + type: optional + docs: |- + Describes the working state of the timecard. + See [TimecardStatus](#type-timecardstatus) for possible values + version: + type: optional + docs: >- + **Read only** The current version of the timecard, which is + incremented with each update. + + This field is used for [optimistic + concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + + control to ensure that requests don't overwrite data from another + request. + created_at: + type: optional + docs: >- + The timestamp of when the timecard was created, in RFC 3339 format + presented as UTC. + access: read-only + updated_at: + type: optional + docs: >- + The timestamp of when the timecard was last updated, in RFC 3339 + format presented as UTC. + access: read-only + team_member_id: + type: string + docs: >- + The ID of the [team member](entity:TeamMember) this timecard belongs + to. + validation: + minLength: 1 + declared_cash_tip_money: + type: optional + docs: The cash tips declared by the team member for this timecard. + source: + openapi: openapi/openapi.json + TimecardFilter: + docs: |- + Defines a filter used in a search for `Timecard` records. `AND` logic is + used by Square's servers to apply each filter property specified. + properties: + location_ids: + type: optional>> + docs: Fetch timecards for the specified location. + status: + type: optional + docs: >- + Fetch a `Timecard` instance by `Timecard.status`. + + See [TimecardFilterStatus](#type-timecardfilterstatus) for possible + values + start: + type: optional + docs: Fetch `Timecard` instances that start in the time range - Inclusive. + end: + type: optional + docs: Fetch the `Timecard` instances that end in the time range - Inclusive. + workday: + type: optional + docs: Fetch the `Timecard` instances based on the workday date range. + team_member_ids: + type: optional>> + docs: Fetch timecards for the specified team members. + source: + openapi: openapi/openapi.json + TimecardFilterStatus: + enum: + - OPEN + - CLOSED + docs: Specifies the `status` of `Timecard` records to be returned. + source: + openapi: openapi/openapi.json + TimecardQuery: + docs: >- + The parameters of a `Timecard` search query, which includes filter and + sort options. + properties: + filter: + type: optional + docs: Query filter options. + sort: + type: optional + docs: Sort order details. + source: + openapi: openapi/openapi.json + TimecardSort: + docs: Sets the sort order of search results. + properties: + field: + type: optional + docs: |- + The field to sort on. + See [TimecardSortField](#type-timecardsortfield) for possible values + order: + type: optional + docs: |- + The order in which results are returned. Defaults to DESC. + See [SortOrder](#type-sortorder) for possible values + source: + openapi: openapi/openapi.json + TimecardSortField: + enum: + - START_AT + - END_AT + - CREATED_AT + - UPDATED_AT + docs: Enumerates the `Timecard` fields to sort on. + source: + openapi: openapi/openapi.json + TimecardStatus: + enum: + - OPEN + - CLOSED + docs: >- + **Read only** Enumerates the possible status of a + [timecard](entity:Timecard). + source: + openapi: openapi/openapi.json + TimecardWage: + docs: >- + The hourly wage rate used to compensate a team member for a + [timecard](entity:Timecard). + properties: + title: + type: optional> + docs: The name of the job performed during this timecard. + hourly_rate: + type: optional + docs: |- + Can be a custom-set hourly wage or the calculated effective hourly + wage based on the annual wage and hours worked per week. + job_id: + type: optional + docs: |- + The ID of the [job](entity:Job) performed for this timecard. Square + labor-reporting UIs might group timecards together by ID. + access: read-only + tip_eligible: + type: optional> + docs: Whether team members are eligible for tips when working this job. + source: + openapi: openapi/openapi.json + TimecardWorkday: + docs: |- + A `Timecard` search query filter parameter that sets a range of days that + a `Timecard` must start or end in before passing the filter condition. + properties: + date_range: + type: optional + docs: Dates for fetching the timecards. + match_timecards_by: + type: optional + docs: >- + The strategy on which the dates are applied. + + See [TimecardWorkdayMatcher](#type-timecardworkdaymatcher) for + possible values + default_timezone: + type: optional> + docs: >- + Location-specific timezones convert workdays to datetime filters. + + Every location included in the query must have a timezone or this + field + + must be provided as a fallback. Format: the IANA timezone database + + identifier for the relevant timezone. + source: + openapi: openapi/openapi.json + TimecardWorkdayMatcher: + enum: + - START_AT + - END_AT + - INTERSECTION + docs: Defines the logic used to apply a workday filter. + source: + openapi: openapi/openapi.json TipSettings: properties: allow_tipping: @@ -25822,6 +26676,26 @@ types: docs: The updated payment. source: openapi: openapi/openapi.json + UpdateScheduledShiftResponse: + docs: >- + Represents an + [UpdateScheduledShift](api-endpoint:Labor-UpdateScheduledShift) response. + + Either `scheduled_shift` or `errors` is present in the response. + properties: + scheduled_shift: + type: optional + docs: >- + The updated scheduled shift. To make the changes public, call + + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json UpdateShiftResponse: docs: |- The response to a request to update a `Shift`. The response contains @@ -25880,6 +26754,23 @@ types: docs: The errors that occurred during the request. source: openapi: openapi/openapi.json + UpdateTimecardResponse: + docs: >- + The response to a request to update a `Timecard`. The response contains + + the updated `Timecard` object and might contain a set of `Error` objects + if + + the request resulted in errors. + properties: + timecard: + type: optional + docs: The updated `Timecard`. + errors: + type: optional> + docs: Any errors that occurred during the request. + source: + openapi: openapi/openapi.json UpdateVendorRequest: docs: >- Represents an input to a call to diff --git a/.mock/definition/api.yml b/.mock/definition/api.yml index 28aa10da..e2b13bab 100644 --- a/.mock/definition/api.yml +++ b/.mock/definition/api.yml @@ -10,7 +10,7 @@ headers: Square-Version: name: version env: VERSION - type: literal<"2025-04-16"> + type: literal<"2025-05-21"> auth-schemes: Bearer: scheme: bearer diff --git a/.mock/definition/labor.yml b/.mock/definition/labor.yml new file mode 100644 index 00000000..824f6c0e --- /dev/null +++ b/.mock/definition/labor.yml @@ -0,0 +1,1001 @@ +imports: + root: __package__.yml +service: + auth: false + base-path: '' + endpoints: + CreateScheduledShift: + path: /v2/labor/scheduled-shifts + method: POST + auth: true + docs: >- + Creates a scheduled shift by providing draft shift details such as job + ID, + + team member assignment, and start and end times. + + + The following `draft_shift_details` fields are required: + + - `location_id` + + - `job_id` + + - `start_at` + + - `end_at` + source: + openapi: openapi/openapi.json + display-name: CreateScheduledShift + request: + name: CreateScheduledShiftRequest + body: + properties: + idempotency_key: + type: optional + docs: >- + A unique identifier for the `CreateScheduledShift` request, used + to ensure the + + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + + of the operation. + validation: + maxLength: 128 + scheduled_shift: + type: root.ScheduledShift + docs: >- + The scheduled shift with `draft_shift_details`. + + If needed, call + [ListLocations](api-endpoint:Locations-ListLocations) to get + location IDs, + + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and + [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + + to get team member IDs and current job assignments. + + + The `start_at` and `end_at` timestamps must be provided in the + time zone + offset of the + + shift location specified in `location_id`. Example for Pacific + Standard Time: 2024-10-31T12:30:00-08:00 + content-type: application/json + response: + docs: Success + type: root.CreateScheduledShiftResponse + status-code: 200 + examples: + - request: + idempotency_key: HIDSNG5KS478L + scheduled_shift: + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + response: + body: + scheduled_shift: + id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + timezone: America/New_York + published_shift_details: + team_member_id: team_member_id + location_id: location_id + job_id: job_id + start_at: start_at + end_at: end_at + notes: notes + is_deleted: true + timezone: timezone + version: 1 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:00-05:00' + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + BulkPublishScheduledShifts: + path: /v2/labor/scheduled-shifts/bulk-publish + method: POST + auth: true + docs: >- + Publishes 1 - 100 scheduled shifts. This endpoint takes a map of + individual publish + + requests and returns a map of responses. When a scheduled shift is + published, Square keeps + + the `draft_shift_details` field as is and copies it to the + `published_shift_details` field. + + + The minimum `start_at` and maximum `end_at` timestamps of all shifts in + a + + `BulkPublishScheduledShifts` request must fall within a two-week period. + source: + openapi: openapi/openapi.json + display-name: BulkPublishScheduledShifts + request: + name: BulkPublishScheduledShiftsRequest + body: + properties: + scheduled_shifts: + type: map + docs: >- + A map of 1 to 100 key-value pairs that represent individual + publish requests. + + + - Each key is the ID of a scheduled shift you want to publish. + + - Each value is a `BulkPublishScheduledShiftsData` object that + contains the + + `version` field or is an empty object. + scheduled_shift_notification_audience: + type: optional + docs: >- + Indicates whether Square should send email notifications to team + members and + + which team members should receive the notifications. This + setting applies to all shifts + + specified in the bulk operation. The default value is + `AFFECTED`. + + See + [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) + for possible values + content-type: application/json + response: + docs: Success + type: root.BulkPublishScheduledShiftsResponse + status-code: 200 + examples: + - request: + scheduled_shifts: + key: {} + scheduled_shift_notification_audience: AFFECTED + response: + body: + responses: + idp_key_1: + scheduled_shift: + id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-03-25T03:11:00-05:00' + end_at: '2019-03-25T13:18:00-05:00' + notes: Don't forget to prep the vegetables + is_deleted: false + timezone: America/New_York + published_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-03-25T03:11:00-05:00' + end_at: '2019-03-25T13:18:00-05:00' + notes: Don't forget to prep the vegetables + is_deleted: false + timezone: America/New_York + version: 3 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:15-05:00' + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + idp_key_2: + errors: + - category: INVALID_REQUEST_ERROR + code: INVALID_VALUE + detail: Scheduled shift with id 'scheduled-shift-2' not found + field: scheduled-shifts.scheduled-shift-2 + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + SearchScheduledShifts: + path: /v2/labor/scheduled-shifts/search + method: POST + auth: true + docs: >- + Returns a paginated list of scheduled shifts, with optional filter and + sort settings. + + By default, results are sorted by `start_at` in ascending order. + source: + openapi: openapi/openapi.json + display-name: SearchScheduledShifts + request: + name: SearchScheduledShiftsRequest + body: + properties: + query: + type: optional + docs: Query conditions used to filter and sort the results. + limit: + type: optional + docs: >- + The maximum number of results to return in a single response + page. The default value is 50. + validation: + min: 1 + max: 50 + cursor: + type: optional + docs: >- + The pagination cursor returned by the previous call to this + endpoint. Provide + + this cursor to retrieve the next page of results for your + original request. For more + + information, see + [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + content-type: application/json + response: + docs: Success + type: root.SearchScheduledShiftsResponse + status-code: 200 + examples: + - request: + query: + filter: + assignment_status: ASSIGNED + sort: + field: CREATED_AT + order: ASC + limit: 2 + cursor: xoxp-1234-5678-90123 + response: + body: + scheduled_shifts: + - id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + timezone: America/New_York + version: 1 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:00-05:00' + cursor: xoxp-123-2123-123232 + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + RetrieveScheduledShift: + path: /v2/labor/scheduled-shifts/{id} + method: GET + auth: true + docs: Retrieves a scheduled shift by ID. + source: + openapi: openapi/openapi.json + display-name: RetrieveScheduledShift + request: + name: RetrieveScheduledShiftRequest + path-parameters: + id: + type: string + docs: The ID of the scheduled shift to retrieve. + response: + docs: Success + type: root.RetrieveScheduledShiftResponse + status-code: 200 + examples: + - path-parameters: + id: id + response: + body: + scheduled_shift: + id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-03-25T03:11:00-05:00' + end_at: '2019-03-25T13:18:00-05:00' + notes: Don't forget to prep the vegetables + is_deleted: false + timezone: America/New_York + published_shift_details: + team_member_id: team_member_id + location_id: location_id + job_id: job_id + start_at: start_at + end_at: end_at + notes: notes + is_deleted: true + timezone: timezone + version: 2 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:15-05:00' + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + UpdateScheduledShift: + path: /v2/labor/scheduled-shifts/{id} + method: PUT + auth: true + docs: >- + Updates the draft shift details for a scheduled shift. This endpoint + supports + + sparse updates, so only new, changed, or removed fields are required in + the request. + + You must publish the shift to make updates public. + + + You can make the following updates to `draft_shift_details`: + + - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. + + - Add, change, or clear the `team_member_id` and `notes` fields. To + clear these fields, + + set the value to null. + + - Change the `is_deleted` field. To delete a scheduled shift, set + `is_deleted` to true + + and then publish the shift. + source: + openapi: openapi/openapi.json + display-name: UpdateScheduledShift + request: + name: UpdateScheduledShiftRequest + path-parameters: + id: + type: string + docs: The ID of the scheduled shift to update. + body: + properties: + scheduled_shift: + type: root.ScheduledShift + docs: >- + The scheduled shift with any updates in the + `draft_shift_details` field. + + If needed, call + [ListLocations](api-endpoint:Locations-ListLocations) to get + location IDs, + + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and + [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + + to get team member IDs and current job assignments. Updates made + to `published_shift_details` + + are ignored. + + + If provided, the `start_at` and `end_at` timestamps must be in + the time zone + offset of the + + shift location specified in `location_id`. Example for Pacific + Standard Time: 2024-10-31T12:30:00-08:00 + + + To enable [optimistic + concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + + control for the request, provide the current version of the + shift in the `version` field. + + If the provided version doesn't match the server version, the + request fails. If `version` is + + omitted, Square executes a blind write, potentially overwriting + data from another publish request. + content-type: application/json + response: + docs: Success + type: root.UpdateScheduledShiftResponse + status-code: 200 + examples: + - path-parameters: + id: id + request: + scheduled_shift: + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-03-25T03:11:00-05:00' + end_at: '2019-03-25T13:18:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + version: 1 + response: + body: + scheduled_shift: + id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-03-25T03:11:00-05:00' + end_at: '2019-03-25T13:18:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + timezone: America/New_York + published_shift_details: + team_member_id: team_member_id + location_id: location_id + job_id: job_id + start_at: start_at + end_at: end_at + notes: notes + is_deleted: true + timezone: timezone + version: 2 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:15-05:00' + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + PublishScheduledShift: + path: /v2/labor/scheduled-shifts/{id}/publish + method: POST + auth: true + docs: >- + Publishes a scheduled shift. When a scheduled shift is published, Square + keeps the + + `draft_shift_details` field as is and copies it to the + `published_shift_details` field. + source: + openapi: openapi/openapi.json + display-name: PublishScheduledShift + request: + name: PublishScheduledShiftRequest + path-parameters: + id: + type: string + docs: The ID of the scheduled shift to publish. + body: + properties: + idempotency_key: + type: string + docs: >- + A unique identifier for the `PublishScheduledShift` request, + used to ensure the + + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + + of the operation. + validation: + minLength: 1 + maxLength: 128 + version: + type: optional + docs: >- + The current version of the scheduled shift, used to enable + [optimistic + concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + + control. If the provided version doesn't match the server + version, the request fails. + + If omitted, Square executes a blind write, potentially + overwriting data from another publish request. + scheduled_shift_notification_audience: + type: optional + docs: >- + Indicates whether Square should send an email notification to + team members and + + which team members should receive the notification. The default + value is `AFFECTED`. + + See + [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) + for possible values + content-type: application/json + response: + docs: Success + type: root.PublishScheduledShiftResponse + status-code: 200 + examples: + - path-parameters: + id: id + request: + idempotency_key: HIDSNG5KS478L + version: 2 + scheduled_shift_notification_audience: ALL + response: + body: + scheduled_shift: + id: K0YH4CV5462JB + draft_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + timezone: America/New_York + published_shift_details: + team_member_id: ormj0jJJZ5OZIzxrZYJI + location_id: PAA1RJZZKXBFG + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + notes: Dont forget to prep the vegetables + is_deleted: false + timezone: America/New_York + version: 2 + created_at: '2019-02-25T03:11:00-05:00' + updated_at: '2019-02-25T03:11:00-05:00' + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + CreateTimecard: + path: /v2/labor/timecards + method: POST + auth: true + docs: >- + 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. + source: + openapi: openapi/openapi.json + display-name: CreateTimecard + request: + name: CreateTimecardRequest + body: + properties: + idempotency_key: + type: optional + docs: >- + A unique string value to ensure the idempotency of the + operation. + validation: + maxLength: 128 + timecard: + type: root.Timecard + docs: The `Timecard` to be created. + content-type: application/json + response: + docs: Success + type: root.CreateTimecardResponse + status-code: 200 + examples: + - request: + idempotency_key: HIDSNG5KS478L + timecard: + 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 + team_member_id: ormj0jJJZ5OZIzxrZYJI + declared_cash_tip_money: + amount: 500 + currency: USD + response: + body: + timecard: + id: K0YH4CV5462JB + 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 + status: CLOSED + version: 1 + created_at: '2019-02-28T00:39:02Z' + updated_at: '2019-02-28T00:39:02Z' + team_member_id: ormj0jJJZ5OZIzxrZYJI + declared_cash_tip_money: + amount: 500 + currency: USD + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + SearchTimecards: + path: /v2/labor/timecards/search + method: POST + auth: true + docs: |- + Returns a paginated list of `Timecard` records for a business. + The list to be returned can be filtered by: + - Location IDs + - Team member IDs + - Timecard status (`OPEN` or `CLOSED`) + - Timecard start + - Timecard end + - Workday details + + The list can be sorted by: + - `START_AT` + - `END_AT` + - `CREATED_AT` + - `UPDATED_AT` + source: + openapi: openapi/openapi.json + display-name: SearchTimecards + request: + name: SearchTimecardsRequest + body: + properties: + query: + type: optional + docs: Query filters. + limit: + type: optional + docs: The number of resources in a page (200 by default). + validation: + min: 1 + max: 200 + cursor: + type: optional + docs: An opaque cursor for fetching the next page. + content-type: application/json + response: + docs: Success + type: root.SearchTimecardsResponse + status-code: 200 + examples: + - request: + query: + filter: + workday: + date_range: + start_date: '2019-01-20' + end_date: '2019-02-03' + match_timecards_by: START_AT + default_timezone: America/Los_Angeles + limit: 100 + response: + body: + timecards: + - id: X714F3HA6D1PT + location_id: PAA1RJZZKXBFG + timezone: America/New_York + start_at: '2019-01-21T03:11:00-05:00' + end_at: '2019-01-21T13:11:00-05:00' + wage: + title: Barista + hourly_rate: + amount: 1100 + currency: USD + job_id: FzbJAtt9qEWncK1BWgVCxQ6M + tip_eligible: true + breaks: + - id: SJW7X6AKEJQ65 + start_at: '2019-01-21T06:11:00-05:00' + end_at: '2019-01-21T06:11:00-05:00' + break_type_id: REGS1EQR1TPZ5 + name: Tea Break + expected_duration: PT10M + is_paid: true + status: CLOSED + version: 6 + created_at: '2019-01-24T01:12:03Z' + updated_at: '2019-02-07T22:21:08Z' + team_member_id: ormj0jJJZ5OZIzxrZYJI + declared_cash_tip_money: + amount: 500 + currency: USD + - id: GDHYBZYWK0P2V + location_id: PAA1RJZZKXBFG + timezone: America/New_York + start_at: '2019-01-22T12:02:00-05:00' + end_at: '2019-01-22T13:02:00-05:00' + wage: + title: Cook + hourly_rate: + amount: 1600 + currency: USD + job_id: gcbz15vKGnMKmaWJJ152kjim + tip_eligible: true + breaks: + - id: BKS6VR7WR748A + start_at: '2019-01-22T14:30:00-05:00' + end_at: '2019-01-22T14:40:00-05:00' + break_type_id: WQX00VR99F53J + name: Tea Break + expected_duration: PT10M + is_paid: true + - id: BQFEZSHFZSC51 + start_at: '2019-01-22T12:30:00-05:00' + end_at: '2019-01-22T12:44:00-05:00' + break_type_id: P6Q468ZFRN1AC + name: Coffee Break + expected_duration: PT15M + is_paid: false + status: CLOSED + version: 16 + created_at: '2019-01-23T23:32:45Z' + updated_at: '2019-01-24T00:56:25Z' + team_member_id: 33fJchumvVdJwxV0H6L9 + declared_cash_tip_money: + amount: 0 + currency: USD + cursor: cursor + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + RetrieveTimecard: + path: /v2/labor/timecards/{id} + method: GET + auth: true + docs: Returns a single `Timecard` specified by `id`. + source: + openapi: openapi/openapi.json + display-name: RetrieveTimecard + request: + name: RetrieveTimecardRequest + path-parameters: + id: + type: string + docs: The UUID for the `Timecard` being retrieved. + response: + docs: Success + type: root.RetrieveTimecardResponse + status-code: 200 + examples: + - path-parameters: + id: id + response: + body: + timecard: + id: T35HMQSN89SV4 + location_id: PAA1RJZZKXBFG + timezone: America/New_York + start_at: '2019-02-23T18:00:00-05:00' + end_at: '2019-02-23T21:00:00-05:00' + wage: + title: Cashier + hourly_rate: + amount: 1457 + currency: USD + job_id: N4YKVLzFj3oGtNocqoYHYpW3 + tip_eligible: true + breaks: + - id: M9BBKEPQAQD2T + start_at: '2019-02-23T19:00:00-05:00' + end_at: '2019-02-23T20:00:00-05:00' + break_type_id: 92EPDRQKJ5088 + name: Lunch Break + expected_duration: PT1H + is_paid: true + status: CLOSED + version: 1 + created_at: '2019-02-27T00:12:12Z' + updated_at: '2019-02-27T00:12:12Z' + team_member_id: D71KRMQof6cXGUW0aAv7 + declared_cash_tip_money: + amount: 500 + currency: USD + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + UpdateTimecard: + path: /v2/labor/timecards/{id} + method: PUT + auth: true + docs: >- + Updates an existing `Timecard`. + + + When adding a `Break` to a `Timecard`, any earlier `Break` instances in + the `Timecard` have + + the `end_at` property set to a valid RFC-3339 datetime string. + + + When closing a `Timecard`, all `Break` instances in the `Timecard` must + be complete with `end_at` + + set on each `Break`. + source: + openapi: openapi/openapi.json + display-name: UpdateTimecard + request: + name: UpdateTimecardRequest + path-parameters: + id: + type: string + docs: The ID of the object being updated. + body: + properties: + timecard: + type: root.Timecard + docs: The updated `Timecard` object. + content-type: application/json + response: + docs: Success + type: root.UpdateTimecardResponse + status-code: 200 + examples: + - path-parameters: + id: id + request: + timecard: + location_id: PAA1RJZZKXBFG + start_at: '2019-01-25T03:11:00-05:00' + end_at: '2019-01-25T13:11:00-05:00' + wage: + title: Bartender + hourly_rate: + amount: 1500 + currency: USD + 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 + status: CLOSED + version: 1 + team_member_id: ormj0jJJZ5OZIzxrZYJI + declared_cash_tip_money: + amount: 500 + currency: USD + response: + body: + timecard: + id: K0YH4CV5462JB + 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: Bartender + hourly_rate: + amount: 1500 + currency: USD + job_id: dZtrPh5GSDGugyXGByesVp51 + 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 + status: CLOSED + version: 2 + created_at: '2019-02-28T00:39:02Z' + updated_at: '2019-02-28T00:42:41Z' + team_member_id: ormj0jJJZ5OZIzxrZYJI + declared_cash_tip_money: + amount: 500 + currency: USD + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + DeleteTimecard: + path: /v2/labor/timecards/{id} + method: DELETE + auth: true + docs: Deletes a `Timecard`. + source: + openapi: openapi/openapi.json + display-name: DeleteTimecard + request: + name: DeleteTimecardRequest + path-parameters: + id: + type: string + docs: The UUID for the `Timecard` being deleted. + response: + docs: Success + type: root.DeleteTimecardResponse + status-code: 200 + examples: + - path-parameters: + id: id + response: + body: + errors: + - category: API_ERROR + code: INTERNAL_SERVER_ERROR + detail: detail + field: field + source: + openapi: openapi/openapi.json diff --git a/.mock/definition/labor/shifts.yml b/.mock/definition/labor/shifts.yml index 85647a69..93669d62 100644 --- a/.mock/definition/labor/shifts.yml +++ b/.mock/definition/labor/shifts.yml @@ -66,6 +66,7 @@ service: docs: Success type: root.CreateShiftResponse status-code: 200 + availability: deprecated examples: - request: idempotency_key: HIDSNG5KS478L @@ -170,6 +171,7 @@ service: docs: Success type: root.SearchShiftsResponse status-code: 200 + availability: deprecated examples: - request: query: @@ -273,6 +275,7 @@ service: docs: Success type: root.GetShiftResponse status-code: 200 + availability: deprecated examples: - path-parameters: id: id @@ -350,6 +353,7 @@ service: docs: Success type: root.UpdateShiftResponse status-code: 200 + availability: deprecated examples: - path-parameters: id: id @@ -432,6 +436,7 @@ service: docs: Success type: root.DeleteShiftResponse status-code: 200 + availability: deprecated examples: - path-parameters: id: id diff --git a/.mock/openapi/openapi.json b/.mock/openapi/openapi.json index cbb5c9be..bad38922 100644 --- a/.mock/openapi/openapi.json +++ b/.mock/openapi/openapi.json @@ -146,7 +146,7 @@ "name": "Square-Version", "description": "Square Connect API versions", "schema": { - "default": "2025-04-16" + "default": "2025-05-21" } } ], @@ -2734,7 +2734,7 @@ }, "Break": { "type": "object", - "description": "A record of an employee's break during a shift.", + "description": "A record of a team member's break on a [timecard](entity:Timecard).", "x-release-status": "PUBLIC", "required": [ "start_at", @@ -2750,17 +2750,17 @@ }, "start_at": { "type": "string", - "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", + "description": "RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to\nthe minute is respected; seconds are truncated.", "minLength": 1 }, "end_at": { "type": "string", - "description": "RFC 3339; follows the same timezone information as `Shift`. Precision up to\nthe minute is respected; seconds are truncated.", + "description": "RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to\nthe minute is respected; seconds are truncated.", "nullable": true }, "break_type_id": { "type": "string", - "description": "The `BreakType` that this `Break` was templated on.", + "description": "The [BreakType](entity:BreakType) that this break was templated on.", "minLength": 1 }, "name": { @@ -2770,7 +2770,7 @@ }, "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.", + "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthe break.\n\nExample for break expected duration of 15 minutes: PT15M", "minLength": 1 }, "is_paid": { @@ -2781,7 +2781,7 @@ }, "BreakType": { "type": "object", - "description": "A defined break template that sets an expectation for possible `Break`\ninstances on a `Shift`.", + "description": "A template for a type of [break](entity:Break) that can be added to a\n[timecard](entity:Timecard), including the expected duration and paid status.", "x-release-status": "PUBLIC", "required": [ "location_id", @@ -2802,12 +2802,12 @@ }, "break_name": { "type": "string", - "description": "A human-readable name for this type of break. The name is displayed to\nemployees in Square products.", + "description": "A human-readable name for this type of break. The name is displayed to\nteam members in Square products.", "minLength": 1 }, "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\nthis break. Precision less than minutes is truncated.\n\nExample for break expected duration of 15 minutes: T15M", + "description": "Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of\nthis break. Precision less than minutes is truncated.\n\nExample for break expected duration of 15 minutes: PT15M", "minLength": 1 }, "is_paid": { @@ -3659,6 +3659,113 @@ } } }, + "BulkPublishScheduledShiftsData": { + "type": "object", + "description": "Represents options for an individual publish request in a\n[BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts)\noperation, provided as the value in a key-value pair.", + "x-release-status": "BETA", + "properties": { + "version": { + "type": "integer", + "description": "The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol. If the provided version doesn't match the server version, the request fails.\nIf omitted, Square executes a blind write, potentially overwriting data from another publish request." + } + } + }, + "BulkPublishScheduledShiftsRequest": { + "type": "object", + "description": "Represents a [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) request.", + "x-release-status": "BETA", + "required": [ + "scheduled_shifts" + ], + "properties": { + "scheduled_shifts": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/BulkPublishScheduledShiftsData" + }, + "description": "A map of 1 to 100 key-value pairs that represent individual publish requests.\n\n- Each key is the ID of a scheduled shift you want to publish.\n- Each value is a `BulkPublishScheduledShiftsData` object that contains the\n`version` field or is an empty object." + }, + "scheduled_shift_notification_audience": { + "$ref": "#/components/schemas/ScheduledShiftNotificationAudience", + "description": "Indicates whether Square should send email notifications to team members and\nwhich team members should receive the notifications. This setting applies to all shifts\nspecified in the bulk operation. The default value is `AFFECTED`.\nSee [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values", + "nullable": true + } + }, + "example": { + "scheduled-shifts": { + "K0YH4CV5462JB": { + "version": 3 + }, + "scheduled-shift-2": { + "version": 2 + } + }, + "scheduled_shift_notification_audience": "AFFECTED" + } + }, + "BulkPublishScheduledShiftsResponse": { + "type": "object", + "description": "Represents a [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) response.\nEither `scheduled_shifts` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "responses": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/PublishScheduledShiftResponse" + }, + "description": "A map of key-value pairs that represent responses for individual publish requests.\nThe order of responses might differ from the order in which the requests were provided.\n\n- Each key is the scheduled shift ID that was specified for a publish request.\n- Each value is the corresponding response. If the request succeeds, the value is the\npublished scheduled shift. If the request fails, the value is an `errors` array containing\nany errors that occurred while processing the request." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any top-level errors that prevented the bulk operation from succeeding." + } + }, + "example": { + "responses": { + "idp_key_1": { + "scheduled_shift": { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-03-25T13:18:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Don't forget to prep the vegetables", + "start_at": "2019-03-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "published_shift_details": { + "end_at": "2019-03-25T13:18:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Don't forget to prep the vegetables", + "start_at": "2019-03-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "updated_at": "2019-02-25T03:11:15-05:00", + "version": 3 + } + }, + "idp_key_2": { + "errors": [ + { + "category": "INVALID_REQUEST_ERROR", + "code": "INVALID_VALUE", + "detail": "Scheduled shift with id 'scheduled-shift-2' not found", + "field": "scheduled-shifts.scheduled-shift-2" + } + ] + } + } + } + }, "BulkRetrieveBookingsRequest": { "type": "object", "description": "Request payload for bulk retrieval of bookings.", @@ -7845,7 +7952,7 @@ }, "ecom_uri": { "type": "string", - "description": "Deprecated; see go/ecomUriUseCases. A URI pointing to a published e-commerce product page for the Item.", + "description": "Deprecated. A URI pointing to a published e-commerce product page for the Item.", "x-release-status": "DEPRECATED", "nullable": true }, @@ -7854,7 +7961,7 @@ "items": { "type": "string" }, - "description": "Deprecated; see go/ecomUriUseCases. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item.", + "description": "Deprecated. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item.", "x-release-status": "DEPRECATED", "nullable": true }, @@ -8157,7 +8264,7 @@ }, "CatalogItemModifierListInfo": { "type": "object", - "description": "References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance\nand specifies supported behaviors of the application.", + "description": "Controls how a modifier list is applied to a specific item. This object allows for item-specific customization of modifier list behavior\nand provides the ability to override global modifier list settings.", "x-release-status": "PUBLIC", "required": [ "modifier_list_id" @@ -8173,17 +8280,17 @@ "items": { "$ref": "#/components/schemas/CatalogModifierOverride" }, - "description": "A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default.", + "description": "A set of `CatalogModifierOverride` objects that override default modifier settings for this item.", "nullable": true }, "min_selected_modifiers": { "type": "integer", - "description": "If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", + "description": "The minimum number of modifiers that must be selected from this modifier list.\nValues:\n\n- 0: No selection is required.\n- -1: Default value, the attribute was not set by the client. When `max_selected_modifiers` is\nalso -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`.\n- \u0026gt;0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled.\n- \u0026lt; -1: Invalid. Treated as no selection required.", "nullable": true }, "max_selected_modifiers": { "type": "integer", - "description": "If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`.\nThe default value is `-1`.\n\nWhen `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` \nand `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of\nthe `CatalogModifierList` can be selected from the `CatalogModifierList`. \n\nWhen the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1`\nand `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in \nand can be selected from the `CatalogModifierList`", + "description": "The maximum number of modifiers that can be selected.\nValues:\n\n- 0: No maximum limit.\n- -1: Default value, the attribute was not set by the client. When `min_selected_modifiers` is\nalso -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`.\n- \u0026gt;0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled.\n- \u0026lt; -1: Invalid. Treated as no maximum limit.", "nullable": true }, "enabled": { @@ -8196,6 +8303,24 @@ "description": "The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied \nto a `CatalogItem` instance.", "x-release-status": "BETA", "nullable": true + }, + "allow_quantities": { + "$ref": "#/components/schemas/CatalogModifierToggleOverrideType", + "description": "Controls whether multiple quantities of the same modifier can be selected for this item.\n- `YES` means that every modifier in the `CatalogModifierList` can have multiple quantities\nselected for this item.\n- `NO` means that each modifier in the `CatalogModifierList` can be selected only once for this item.\n- `NOT_SET` means that the `allow_quantities` setting on the `CatalogModifierList` is obeyed.\nSee [CatalogModifierToggleOverrideType](#type-catalogmodifiertoggleoverridetype) for possible values", + "x-release-status": "BETA", + "nullable": true + }, + "is_conversational": { + "$ref": "#/components/schemas/CatalogModifierToggleOverrideType", + "description": "Controls whether conversational mode is enabled for modifiers on this item.\n\n- `YES` means conversational mode is enabled for every modifier in the `CatalogModifierList`.\n- `NO` means that conversational mode is not enabled for any modifier in the `CatalogModifierList`.\n- `NOT_SET` means that conversational mode is not enabled for any modifier in the `CatalogModifierList`.\nSee [CatalogModifierToggleOverrideType](#type-catalogmodifiertoggleoverridetype) for possible values", + "x-release-status": "BETA", + "nullable": true + }, + "hidden_from_customer_override": { + "$ref": "#/components/schemas/CatalogModifierToggleOverrideType", + "description": "Controls whether all modifiers for this item are hidden from customer receipts.\n- `YES` means that all modifiers in the `CatalogModifierList` are hidden from customer\nreceipts for this item.\n- `NO` means that all modifiers in the `CatalogModifierList` are visible on customer receipts for this item.\n- `NOT_SET` means that the `hidden_from_customer` setting on the `CatalogModifierList` is obeyed.\nSee [CatalogModifierToggleOverrideType](#type-catalogmodifiertoggleoverridetype) for possible values", + "x-release-status": "BETA", + "nullable": true } } }, @@ -8500,7 +8625,7 @@ }, "CatalogModifier": { "type": "object", - "description": "A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item.", + "description": "A modifier that can be applied to items at the time of sale. For example, a cheese modifier for a burger, or a flavor modifier for a serving of ice cream.", "x-release-status": "PUBLIC", "properties": { "name": { @@ -8514,6 +8639,12 @@ "description": "The modifier price.", "nullable": true }, + "on_by_default": { + "type": "boolean", + "description": "When `true`, this modifier is selected by default when displaying the modifier list.\nThis setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`.", + "x-release-status": "BETA", + "nullable": true + }, "ordinal": { "type": "integer", "description": "Determines where this `CatalogModifier` appears in the `CatalogModifierList`.", @@ -8537,6 +8668,12 @@ "description": "The ID of the image associated with this `CatalogModifier` instance.\nCurrently this image is not displayed by Square, but is free to be displayed in 3rd party applications.", "x-release-status": "BETA", "nullable": true + }, + "hidden_online": { + "type": "boolean", + "description": "When `true`, this modifier is hidden from online ordering channels. This setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`.", + "x-release-status": "BETA", + "nullable": true } }, "example": { @@ -8555,7 +8692,7 @@ }, "CatalogModifierList": { "type": "object", - "description": "For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. \nFor example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied \ntext string to be selected for the T-shirt at the time of sale.\n\nFor non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items \nat the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. \nFor example, a \"Condiments\" modifier list applicable to a \"Hot Dog\" item\nmay contain \"Ketchup\", \"Mustard\", and \"Relish\" modifiers. \n\nA non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field \nis set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item \nonly once and the `selection_type` field is always set to `SINGLE`.", + "description": "A container for a list of modifiers, or a text-based modifier.\nFor text-based modifiers, this represents text configuration for an item. (For example, custom text to print on a t-shirt).\nFor non text-based modifiers, this represents a list of modifiers that can be applied to items at the time of sale.\n(For example, a list of condiments for a hot dog, or a list of ice cream flavors).\nEach element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type.", "x-release-status": "PUBLIC", "properties": { "name": { @@ -8571,7 +8708,8 @@ }, "selection_type": { "$ref": "#/components/schemas/CatalogModifierListSelectionType", - "description": "Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list\ncan be applied to a single `CatalogItem`.\n\nFor text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored.\nSee [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values", + "description": "__Deprecated__: Indicates whether a single (`SINGLE`) modifier or multiple (`MULTIPLE`) modifiers can be selected. Use\n`min_selected_modifiers` and `max_selected_modifiers` instead.\nSee [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values", + "x-release-status": "DEPRECATED", "nullable": true }, "modifiers": { @@ -8590,6 +8728,18 @@ "description": "The IDs of images associated with this `CatalogModifierList` instance.\nCurrently these images are not displayed on Square products, but may be displayed in 3rd-party applications.", "nullable": true }, + "allow_quantities": { + "type": "boolean", + "description": "When `true`, allows multiple quantities of the same modifier to be selected.", + "x-release-status": "BETA", + "nullable": true + }, + "is_conversational": { + "type": "boolean", + "description": "True if modifiers belonging to this list can be used conversationally.", + "x-release-status": "BETA", + "nullable": true + }, "modifier_type": { "$ref": "#/components/schemas/CatalogModifierListModifierType", "description": "The type of the modifier. \n\nWhen this `modifier_type` value is `TEXT`, the `CatalogModifierList` represents a text-based modifier. \nWhen this `modifier_type` value is `LIST`, the `CatalogModifierList` contains a list of `CatalogModifier` objects.\nSee [CatalogModifierListModifierType](#type-catalogmodifierlistmodifiertype) for possible values", @@ -8614,6 +8764,26 @@ "maxLength": 512, "x-release-status": "BETA", "nullable": true + }, + "min_selected_modifiers": { + "type": "integer", + "description": "The minimum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`.\n\nValues:\n\n- 0: No selection is required.\n- -1: Default value, the attribute was not set by the client. Treated as no selection required.\n- \u0026gt;0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled.\n- \u0026lt; -1: Invalid. Treated as no selection required.", + "format": "int64", + "x-release-status": "BETA", + "nullable": true + }, + "max_selected_modifiers": { + "type": "integer", + "description": "The maximum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`.\n\nValues:\n\n- 0: No maximum limit.\n- -1: Default value, the attribute was not set by the client. Treated as no maximum limit.\n- \u0026gt;0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled.\n- \u0026lt; -1: Invalid. Treated as no maximum limit.", + "format": "int64", + "x-release-status": "BETA", + "nullable": true + }, + "hidden_from_customer": { + "type": "boolean", + "description": "If `true`, modifiers from this list are hidden from customer receipts. The default value is `false`.\nThis setting can be overridden with `CatalogItemModifierListInfo.hidden_from_customer_override`.", + "x-release-status": "BETA", + "nullable": true } }, "example": { @@ -8715,7 +8885,20 @@ }, "on_by_default": { "type": "boolean", - "description": "If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`.", + "description": "__Deprecated__: Use `on_by_default_override` instead.", + "x-release-status": "DEPRECATED", + "nullable": true + }, + "hidden_online_override": { + "$ref": "#/components/schemas/CatalogModifierToggleOverrideType", + "description": "If `YES`, this setting overrides the `hidden_online` setting on the `CatalogModifier` object,\nand the modifier is always hidden from online sales channels.\nIf `NO`, the modifier is not hidden. It is always visible in online sales channels for this catalog item.\n`NOT_SET` means the `hidden_online` setting on the `CatalogModifier` object is obeyed.\nSee [CatalogModifierToggleOverrideType](#type-catalogmodifiertoggleoverridetype) for possible values", + "x-release-status": "BETA", + "nullable": true + }, + "on_by_default_override": { + "$ref": "#/components/schemas/CatalogModifierToggleOverrideType", + "description": "If `YES`, this setting overrides the `on_by_default` setting on the `CatalogModifier` object,\nand the modifier is always selected by default for the catalog item.\n\nIf `NO`, the modifier is not selected by default for this catalog item.\n`NOT_SET` means the `on_by_default` setting on the `CatalogModifier` object is obeyed.\nSee [CatalogModifierToggleOverrideType](#type-catalogmodifiertoggleoverridetype) for possible values", + "x-release-status": "BETA", "nullable": true } } @@ -15339,10 +15522,79 @@ "ruby": "/sdk_samples/CreateRefund/CreateRefundResponse.ruby" } }, + "CreateScheduledShiftRequest": { + "type": "object", + "description": "Represents a [CreateScheduledShift](api-endpoint:Labor-CreateScheduledShift) request.", + "x-release-status": "BETA", + "required": [ + "scheduled_shift" + ], + "properties": { + "idempotency_key": { + "type": "string", + "description": "A unique identifier for the `CreateScheduledShift` request, used to ensure the\n[idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)\nof the operation.", + "maxLength": 128 + }, + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The scheduled shift with `draft_shift_details`.\nIf needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs,\n[ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers)\nto get team member IDs and current job assignments.\n\nThe `start_at` and `end_at` timestamps must be provided in the time zone + offset of the\nshift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00" + } + }, + "example": { + "idempotency_key": "HIDSNG5KS478L", + "scheduled_shift": { + "draft_shift_details": { + "end_at": "2019-01-25T13:11:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI" + } + } + } + }, + "CreateScheduledShiftResponse": { + "type": "object", + "description": "Represents a [CreateScheduledShift](api-endpoint:Labor-CreateScheduledShift) response.\nEither `scheduled_shift` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The new scheduled shift. To make the shift public, call \n[PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or\n[BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts)." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "scheduled_shift": { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-01-25T13:11:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "updated_at": "2019-02-25T03:11:00-05:00", + "version": 1 + } + } + }, "CreateShiftRequest": { "type": "object", "description": "Represents a request to create a `Shift`.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "required": [ "shift" ], @@ -15392,7 +15644,7 @@ "CreateShiftResponse": { "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.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "shift": { "$ref": "#/components/schemas/Shift", @@ -15924,6 +16176,112 @@ } } }, + "CreateTimecardRequest": { + "type": "object", + "description": "Represents a request to create a `Timecard`.", + "x-release-status": "PUBLIC", + "required": [ + "timecard" + ], + "properties": { + "idempotency_key": { + "type": "string", + "description": "A unique string value to ensure the idempotency of the operation.", + "maxLength": 128 + }, + "timecard": { + "$ref": "#/components/schemas/Timecard", + "description": "The `Timecard` to be created." + } + }, + "example": { + "idempotency_key": "HIDSNG5KS478L", + "timecard": { + "breaks": [ + { + "break_type_id": "REGS1EQR1TPZ5", + "end_at": "2019-01-25T06:16:00-05:00", + "expected_duration": "PT5M", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-25T06:11:00-05:00" + } + ], + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-01-25T13:11:00-05:00", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "wage": { + "hourly_rate": { + "amount": 1100, + "currency": "USD" + }, + "tip_eligible": true, + "title": "Barista" + } + } + } + }, + "CreateTimecardResponse": { + "type": "object", + "description": "The response to a request to create a `Timecard`. The response contains\nthe created `Timecard` object and might contain a set of `Error` objects if\nthe request resulted in errors.", + "x-release-status": "PUBLIC", + "properties": { + "timecard": { + "$ref": "#/components/schemas/Timecard", + "description": "The `Timecard` that was created on the request." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "timecard": { + "breaks": [ + { + "break_type_id": "REGS1EQR1TPZ5", + "end_at": "2019-01-25T06:16:00-05:00", + "expected_duration": "PT5M", + "id": "X7GAQYVVRRG6P", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-25T06:11:00-05:00" + } + ], + "created_at": "2019-02-28T00:39:02Z", + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-01-25T13:11:00-05:00", + "id": "K0YH4CV5462JB", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "status": "CLOSED", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York", + "updated_at": "2019-02-28T00:39:02Z", + "version": 1, + "wage": { + "hourly_rate": { + "amount": 1100, + "currency": "USD" + }, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "tip_eligible": true, + "title": "Barista" + } + } + } + }, "CreateVendorRequest": { "type": "object", "description": "Represents an input to a call to [CreateVendor](api-endpoint:Vendors-CreateVendor).", @@ -18383,13 +18741,13 @@ "DeleteShiftRequest": { "type": "object", "description": "A request to delete a `Shift`.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": {} }, "DeleteShiftResponse": { "type": "object", "description": "The response to a request to delete a `Shift`. The response might contain a set of \n`Error` objects if the request resulted in errors.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "errors": { "type": "array", @@ -18472,6 +18830,27 @@ } } }, + "DeleteTimecardRequest": { + "type": "object", + "description": "A request to delete a `Timecard`.", + "x-release-status": "PUBLIC", + "properties": {} + }, + "DeleteTimecardResponse": { + "type": "object", + "description": "The response to a request to delete a `Timecard`. The response might contain a set of \n`Error` objects if the request resulted in errors.", + "x-release-status": "PUBLIC", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": {} + }, "DeleteWebhookSubscriptionRequest": { "type": "object", "description": "Deletes a [Subscription](entity:WebhookSubscription).", @@ -22419,13 +22798,13 @@ "GetShiftRequest": { "type": "object", "description": "A request to get a `Shift` by ID.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": {} }, "GetShiftResponse": { "type": "object", "description": "A response to a request to get a `Shift`. The response contains\nthe requested `Shift` object and might contain a set of `Error` objects if\nthe request resulted in errors.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "shift": { "$ref": "#/components/schemas/Shift", @@ -35851,6 +36230,82 @@ } } }, + "PublishScheduledShiftRequest": { + "type": "object", + "description": "Represents a [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) request.", + "x-release-status": "BETA", + "required": [ + "idempotency_key" + ], + "properties": { + "idempotency_key": { + "type": "string", + "description": "A unique identifier for the `PublishScheduledShift` request, used to ensure the\n[idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)\nof the operation.", + "minLength": 1, + "maxLength": 128 + }, + "version": { + "type": "integer", + "description": "The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol. If the provided version doesn't match the server version, the request fails.\nIf omitted, Square executes a blind write, potentially overwriting data from another publish request." + }, + "scheduled_shift_notification_audience": { + "$ref": "#/components/schemas/ScheduledShiftNotificationAudience", + "description": "Indicates whether Square should send an email notification to team members and\nwhich team members should receive the notification. The default value is `AFFECTED`.\nSee [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values", + "nullable": true + } + }, + "example": { + "idempotency_key": "HIDSNG5KS478L", + "scheduled_shift_notification_audience": "ALL", + "version": 2 + } + }, + "PublishScheduledShiftResponse": { + "type": "object", + "description": "Represents a [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) response.\nEither `scheduled_shift` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The published scheduled shift." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "scheduled_shift": { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-01-25T13:11:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "published_shift_details": { + "end_at": "2019-01-25T13:11:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "updated_at": "2019-02-25T03:11:00-05:00", + "version": 2 + } + } + }, "QrCodeOptions": { "type": "object", "description": "Fields to describe the action that displays QR-Codes.", @@ -38614,6 +39069,48 @@ } } }, + "RetrieveScheduledShiftRequest": { + "type": "object", + "description": "Represents a [RetrieveScheduledShift](api-endpoint:Labor-RetrieveScheduledShift) request.", + "x-release-status": "BETA", + "properties": {} + }, + "RetrieveScheduledShiftResponse": { + "type": "object", + "description": "Represents a [RetrieveScheduledShift](api-endpoint:Labor-RetrieveScheduledShift) response.\nEither `scheduled_shift` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The requested scheduled shift." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "scheduled_shift": { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-03-25T13:18:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Don't forget to prep the vegetables", + "start_at": "2019-03-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "updated_at": "2019-02-25T03:11:15-05:00", + "version": 2 + } + } + }, "RetrieveSnippetRequest": { "type": "object", "description": "Represents a `RetrieveSnippet` request.", @@ -38812,6 +39309,68 @@ } } }, + "RetrieveTimecardRequest": { + "type": "object", + "description": "A request to get a `Timecard` by ID.", + "x-release-status": "PUBLIC", + "properties": {} + }, + "RetrieveTimecardResponse": { + "type": "object", + "description": "A response to a request to get a `Timecard`. The response contains\nthe requested `Timecard` object and might contain a set of `Error` objects if\nthe request resulted in errors.", + "x-release-status": "PUBLIC", + "properties": { + "timecard": { + "$ref": "#/components/schemas/Timecard", + "description": "The requested `Timecard`." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "timecard": { + "breaks": [ + { + "break_type_id": "92EPDRQKJ5088", + "end_at": "2019-02-23T20:00:00-05:00", + "expected_duration": "PT1H", + "id": "M9BBKEPQAQD2T", + "is_paid": true, + "name": "Lunch Break", + "start_at": "2019-02-23T19:00:00-05:00" + } + ], + "created_at": "2019-02-27T00:12:12Z", + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-02-23T21:00:00-05:00", + "id": "T35HMQSN89SV4", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-02-23T18:00:00-05:00", + "status": "CLOSED", + "team_member_id": "D71KRMQof6cXGUW0aAv7", + "timezone": "America/New_York", + "updated_at": "2019-02-27T00:12:12Z", + "version": 1, + "wage": { + "hourly_rate": { + "amount": 1457, + "currency": "USD" + }, + "job_id": "N4YKVLzFj3oGtNocqoYHYpW3", + "tip_eligible": true, + "title": "Cashier" + } + } + } + }, "RetrieveTokenStatusRequest": { "type": "object", "description": "Request object for [RetrieveTokenStatus] endpoint.", @@ -39231,6 +39790,314 @@ } } }, + "ScheduledShift": { + "type": "object", + "description": "Represents a specific time slot in a work schedule. This object is used to manage the\nlifecycle of a scheduled shift from the draft to published state. A scheduled shift contains\nthe latest draft shift details and current published shift details.", + "x-release-status": "BETA", + "properties": { + "id": { + "type": "string", + "description": "**Read only** The Square-issued ID of the scheduled shift.", + "maxLength": 255 + }, + "draft_shift_details": { + "$ref": "#/components/schemas/ScheduledShiftDetails", + "description": "The latest draft shift details for the scheduled shift. Draft shift details are used to\nstage and manage shifts before publishing. This field is always present.", + "nullable": true + }, + "published_shift_details": { + "$ref": "#/components/schemas/ScheduledShiftDetails", + "description": "The current published (public) shift details for the scheduled shift. This field is\npresent only if the shift was published.", + "readOnly": true + }, + "version": { + "type": "integer", + "description": "**Read only** The current version of the scheduled shift, which is incremented with each update.\nThis field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol to ensure that requests don't overwrite data from another request." + }, + "created_at": { + "type": "string", + "description": "The timestamp of when the scheduled shift was created, in RFC 3339 format presented as UTC.", + "readOnly": true + }, + "updated_at": { + "type": "string", + "description": "The timestamp of when the scheduled shift was last updated, in RFC 3339 format presented as UTC.", + "readOnly": true + } + } + }, + "ScheduledShiftDetails": { + "type": "object", + "description": "Represents shift details for draft and published versions of a [scheduled shift](entity:ScheduledShift),\nsuch as job ID, team member assignment, and start and end times.", + "x-release-status": "BETA", + "properties": { + "team_member_id": { + "type": "string", + "description": "The ID of the [team member](entity:TeamMember) scheduled for the shift.", + "maxLength": 255, + "nullable": true + }, + "location_id": { + "type": "string", + "description": "The ID of the [location](entity:Location) the shift is scheduled for.", + "maxLength": 255, + "nullable": true + }, + "job_id": { + "type": "string", + "description": "The ID of the [job](entity:Job) the shift is scheduled for.", + "nullable": true + }, + "start_at": { + "type": "string", + "description": "The start time of the shift, in RFC 3339 format in the time zone \u0026plus;\noffset of the shift location specified in `location_id`. Precision up to the minute\nis respected; seconds are truncated.", + "nullable": true + }, + "end_at": { + "type": "string", + "description": "The end time for the shift, in RFC 3339 format in the time zone \u0026plus;\noffset of the shift location specified in `location_id`. Precision up to the minute\nis respected; seconds are truncated.", + "nullable": true + }, + "notes": { + "type": "string", + "description": "Optional notes for the shift.", + "maxLength": 1000, + "nullable": true + }, + "is_deleted": { + "type": "boolean", + "description": "Indicates whether the draft shift version is deleted. If set to `true` when the shift\nis published, the entire scheduled shift (including the published shift) is deleted and\ncannot be accessed using any endpoint.", + "nullable": true + }, + "timezone": { + "type": "string", + "description": "The time zone of the shift location, calculated based on the `location_id`. This field\nis provided for convenience.", + "readOnly": true + } + } + }, + "ScheduledShiftFilter": { + "type": "object", + "description": "Defines filter criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts)\nrequest. Multiple filters in a query are combined as an `AND` operation.", + "x-release-status": "BETA", + "properties": { + "location_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Return shifts for the specified locations. When omitted, shifts for all\nlocations are returned. If needed, call [ListLocations](api-endpoint:Locations-ListLocations)\nto get location IDs.", + "nullable": true + }, + "start": { + "$ref": "#/components/schemas/TimeRange", + "description": "Return shifts whose `start_at` time is within the specified\ntime range (inclusive).", + "nullable": true + }, + "end": { + "$ref": "#/components/schemas/TimeRange", + "description": "Return shifts whose `end_at` time is within the specified\ntime range (inclusive).", + "nullable": true + }, + "workday": { + "$ref": "#/components/schemas/ScheduledShiftWorkday", + "description": "Return shifts based on a workday date range.", + "nullable": true + }, + "team_member_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Return shifts assigned to specified team members. If needed, call\n[SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get team member IDs.\n\nTo return only the shifts assigned to the specified team members, include the\n`assignment_status` filter in the query. Otherwise, all unassigned shifts are\nreturned along with shifts assigned to the specified team members.", + "nullable": true + }, + "assignment_status": { + "$ref": "#/components/schemas/ScheduledShiftFilterAssignmentStatus", + "description": "Return shifts based on whether a team member is assigned. A shift is\nassigned if the `team_member_id` field is populated in the `draft_shift_details`\nor `published_shift details` field of the shift.\n\nTo return only draft or published shifts, include the `scheduled_shift_statuses`\nfilter in the query.\nSee [ScheduledShiftFilterAssignmentStatus](#type-scheduledshiftfilterassignmentstatus) for possible values", + "nullable": true + }, + "scheduled_shift_statuses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ScheduledShiftFilterScheduledShiftStatus" + }, + "description": "Return shifts based on the draft or published status of the shift.\nA shift is published if the `published_shift_details` field is present.\n\nNote that shifts with `draft_shift_details.is_deleted` set to `true` are ignored\nwith the `DRAFT` filter.\nSee [ScheduledShiftFilterScheduledShiftStatus](#type-scheduledshiftfilterscheduledshiftstatus) for possible values", + "nullable": true + } + } + }, + "ScheduledShiftFilterAssignmentStatus": { + "type": "string", + "enum": [ + "ASSIGNED", + "UNASSIGNED" + ], + "x-enum-elements": [ + { + "name": "ASSIGNED", + "description": "The shift is assigned to a team member." + }, + { + "name": "UNASSIGNED", + "description": "The shift isn't assigned to a team member." + } + ], + "description": "Defines valid values for the `assignment_status` filter in a\n[SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.\nAssignment status is based on the `draft_shift_details.team_member_id` and\n`published_shift_details.team_member_id` fields of the scheduled shift.", + "x-release-status": "BETA" + }, + "ScheduledShiftFilterScheduledShiftStatus": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED" + ], + "x-enum-elements": [ + { + "name": "DRAFT", + "description": "The scheduled shift has never been published or its draft details were\nupdated after it was published. This means that the shift has no `published_shift_details`\nfield or that `draft_shift_details` has different settings than `published_shift_details`." + }, + { + "name": "PUBLISHED", + "description": "The scheduled shift was published. This means that the shift has a\n`published_shift_details` field." + } + ], + "description": "Defines valid values for the `scheduled_shift_statuses` filter in a\n[SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.", + "x-release-status": "BETA" + }, + "ScheduledShiftNotificationAudience": { + "type": "string", + "enum": [ + "ALL", + "AFFECTED", + "NONE" + ], + "x-enum-elements": [ + { + "name": "ALL", + "description": "Notify all active team members. Note that republishing an unchanged\nshift with this setting resends the notification." + }, + { + "name": "AFFECTED", + "description": "Notify the team member assigned to the shift. If the shift assignment\nchanges, notify both the newly assigned and previously assigned team members." + }, + { + "name": "NONE", + "description": "Do not send a notification." + } + ], + "description": "Indicates whether Square sends an email notification to team members\nwhen a scheduled shift is published and which team members receive the notification.", + "x-release-status": "BETA" + }, + "ScheduledShiftQuery": { + "type": "object", + "description": "Represents filter and sort criteria for the `query` field in a\n[SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.", + "x-release-status": "BETA", + "properties": { + "filter": { + "$ref": "#/components/schemas/ScheduledShiftFilter", + "description": "Filtering options for the query.", + "nullable": true + }, + "sort": { + "$ref": "#/components/schemas/ScheduledShiftSort", + "description": "Sorting options for the query.", + "nullable": true + } + } + }, + "ScheduledShiftSort": { + "type": "object", + "description": "Defines sort criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts)\nrequest.", + "x-release-status": "BETA", + "properties": { + "field": { + "$ref": "#/components/schemas/ScheduledShiftSortField", + "description": "The field to sort on. The default value is `START_AT`.\nSee [ScheduledShiftSortField](#type-scheduledshiftsortfield) for possible values", + "nullable": true + }, + "order": { + "$ref": "#/components/schemas/SortOrder", + "description": "The order in which results are returned. The default value is `ASC`.\nSee [SortOrder](#type-sortorder) for possible values", + "nullable": true + } + } + }, + "ScheduledShiftSortField": { + "type": "string", + "enum": [ + "START_AT", + "END_AT", + "CREATED_AT", + "UPDATED_AT" + ], + "x-enum-elements": [ + { + "name": "START_AT", + "description": "Sort by the start time of the shift." + }, + { + "name": "END_AT", + "description": "Sort by the end time of the shift." + }, + { + "name": "CREATED_AT", + "description": "Sort by the creation date of the shift." + }, + { + "name": "UPDATED_AT", + "description": "Sort by the last updated date of the shift." + } + ], + "description": "Defines valid values for the `field` sort setting in a\n[SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.", + "x-release-status": "BETA" + }, + "ScheduledShiftWorkday": { + "type": "object", + "description": "A `ScheduledShift` search query filter parameter that sets a range of days that\na `Shift` must start or end in before passing the filter condition.", + "x-release-status": "BETA", + "properties": { + "date_range": { + "$ref": "#/components/schemas/DateRange", + "description": "Dates for fetching the scheduled shifts.", + "nullable": true + }, + "match_scheduled_shifts_by": { + "$ref": "#/components/schemas/ScheduledShiftWorkdayMatcher", + "description": "The strategy on which the dates are applied.\nSee [ScheduledShiftWorkdayMatcher](#type-scheduledshiftworkdaymatcher) for possible values", + "nullable": true + }, + "default_timezone": { + "type": "string", + "description": "Location-specific timezones convert workdays to datetime filters.\nEvery location included in the query must have a timezone or this field\nmust be provided as a fallback. Format: the IANA timezone database\nidentifier for the relevant timezone.", + "nullable": true + } + } + }, + "ScheduledShiftWorkdayMatcher": { + "type": "string", + "enum": [ + "START_AT", + "END_AT", + "INTERSECTION" + ], + "x-enum-elements": [ + { + "name": "START_AT", + "description": "All shifts that start on or after the specified workday" + }, + { + "name": "END_AT", + "description": "All shifts that end on or before the specified workday" + }, + { + "name": "INTERSECTION", + "description": "All shifts that start between the start and end workdays (inclusive)" + } + ], + "description": "Defines the logic used to apply a workday filter.", + "x-release-status": "BETA" + }, "SearchAvailabilityFilter": { "type": "object", "description": "A query filter to search for buyer-accessible availabilities by.", @@ -41118,10 +41985,94 @@ } } }, + "SearchScheduledShiftsRequest": { + "type": "object", + "description": "Represents a [SearchScheduledShift](api-endpoint:Labor-SearchScheduledShift) request.", + "x-release-status": "BETA", + "properties": { + "query": { + "$ref": "#/components/schemas/ScheduledShiftQuery", + "description": "Query conditions used to filter and sort the results." + }, + "limit": { + "type": "integer", + "description": "The maximum number of results to return in a single response page. The default value is 50.", + "minimum": 1, + "maximum": 50 + }, + "cursor": { + "type": "string", + "description": "The pagination cursor returned by the previous call to this endpoint. Provide\nthis cursor to retrieve the next page of results for your original request. For more\ninformation, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." + } + }, + "example": { + "cursor": "xoxp-1234-5678-90123", + "limit": 2, + "query": { + "filter": { + "assignment_status": "ASSIGNED", + "scheduled_shift_status": [ + "PUBLISHED", + "DRAFT" + ] + }, + "sort": { + "field": "CREATED_AT", + "order": "ASC" + } + } + } + }, + "SearchScheduledShiftsResponse": { + "type": "object", + "description": "Represents a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) response.\nEither `scheduled_shifts` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "scheduled_shifts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ScheduledShift" + }, + "description": "A paginated list of scheduled shifts that match the query conditions." + }, + "cursor": { + "type": "string", + "description": "The pagination cursor used to retrieve the next page of results. This field is present\nonly if additional results are available." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "cursor": "xoxp-123-2123-123232", + "scheduled_shifts": [ + { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-01-25T13:11:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-01-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "updated_at": "2019-02-25T03:11:00-05:00", + "version": 1 + } + ] + } + }, "SearchShiftsRequest": { "type": "object", "description": "A request for a filtered and sorted set of `Shift` objects.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "query": { "$ref": "#/components/schemas/ShiftQuery", @@ -41157,7 +42108,7 @@ "SearchShiftsResponse": { "type": "object", "description": "The response to a request for `Shift` objects. The response contains\nthe requested `Shift` objects and might contain a set of `Error` objects if\nthe request resulted in errors.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "shifts": { "type": "array", @@ -42061,6 +43012,152 @@ ] } }, + "SearchTimecardsRequest": { + "type": "object", + "description": "A request for a filtered and sorted set of `Timecard` objects.", + "x-release-status": "PUBLIC", + "properties": { + "query": { + "$ref": "#/components/schemas/TimecardQuery", + "description": "Query filters." + }, + "limit": { + "type": "integer", + "description": "The number of resources in a page (200 by default).", + "minimum": 1, + "maximum": 200 + }, + "cursor": { + "type": "string", + "description": "An opaque cursor for fetching the next page." + } + }, + "example": { + "limit": 100, + "query": { + "filter": { + "workday": { + "date_range": { + "end_date": "2019-02-03", + "start_date": "2019-01-20" + }, + "default_timezone": "America/Los_Angeles", + "match_timecards_by": "START_AT" + } + } + } + } + }, + "SearchTimecardsResponse": { + "type": "object", + "description": "The response to a request for `Timecard` objects. The response contains\nthe requested `Timecard` objects and might contain a set of `Error` objects if\nthe request resulted in errors.", + "x-release-status": "PUBLIC", + "properties": { + "timecards": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Timecard" + }, + "description": "Timecards." + }, + "cursor": { + "type": "string", + "description": "An opaque cursor for fetching the next page." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "timecards": [ + { + "breaks": [ + { + "break_type_id": "REGS1EQR1TPZ5", + "end_at": "2019-01-21T06:11:00-05:00", + "expected_duration": "PT10M", + "id": "SJW7X6AKEJQ65", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-21T06:11:00-05:00" + } + ], + "created_at": "2019-01-24T01:12:03Z", + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-01-21T13:11:00-05:00", + "id": "X714F3HA6D1PT", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-21T03:11:00-05:00", + "status": "CLOSED", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York", + "updated_at": "2019-02-07T22:21:08Z", + "version": 6, + "wage": { + "hourly_rate": { + "amount": 1100, + "currency": "USD" + }, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "tip_eligible": true, + "title": "Barista" + } + }, + { + "breaks": [ + { + "break_type_id": "WQX00VR99F53J", + "end_at": "2019-01-22T14:40:00-05:00", + "expected_duration": "PT10M", + "id": "BKS6VR7WR748A", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-22T14:30:00-05:00" + }, + { + "break_type_id": "P6Q468ZFRN1AC", + "end_at": "2019-01-22T12:44:00-05:00", + "expected_duration": "PT15M", + "id": "BQFEZSHFZSC51", + "is_paid": false, + "name": "Coffee Break", + "start_at": "2019-01-22T12:30:00-05:00" + } + ], + "created_at": "2019-01-23T23:32:45Z", + "declared_cash_tip_money": { + "amount": 0, + "currency": "USD" + }, + "end_at": "2019-01-22T13:02:00-05:00", + "id": "GDHYBZYWK0P2V", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-22T12:02:00-05:00", + "status": "CLOSED", + "team_member_id": "33fJchumvVdJwxV0H6L9", + "timezone": "America/New_York", + "updated_at": "2019-01-24T00:56:25Z", + "version": 16, + "wage": { + "hourly_rate": { + "amount": 1600, + "currency": "USD" + }, + "job_id": "gcbz15vKGnMKmaWJJ152kjim", + "tip_eligible": true, + "title": "Cook" + } + } + ] + } + }, "SearchVendorsRequest": { "type": "object", "description": "Represents an input into a call to [SearchVendors](api-endpoint:Vendors-SearchVendors).", @@ -42291,8 +43388,8 @@ }, "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.", - "x-release-status": "PUBLIC", + "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.\n\nDeprecated at Square API version 2025-05-21. Replaced by [Timecard](entity:Timecard).\nSee the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "required": [ "location_id", "start_at" @@ -42306,7 +43403,6 @@ "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.", - "x-release-status": "DEPRECATED", "nullable": true }, "location_id": { @@ -42375,8 +43471,8 @@ }, "ShiftFilter": { "type": "object", - "description": "Defines a filter used in a search for `Shift` records. `AND` logic is\nused by Square's servers to apply each filter property specified.", - "x-release-status": "PUBLIC", + "description": "Defines a filter used in a search for `Shift` records. `AND` logic is\nused by Square's servers to apply each filter property specified.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "properties": { "location_ids": { "type": "array", @@ -42392,7 +43488,6 @@ "type": "string" }, "description": "Fetch shifts for the specified employees. DEPRECATED at version 2020-08-26. Use `team_member_ids` instead.", - "x-release-status": "DEPRECATED", "nullable": true }, "status": { @@ -42441,13 +43536,13 @@ "description": "Shifts that have been started and ended." } ], - "description": "Specifies the `status` of `Shift` records to be returned.", - "x-release-status": "PUBLIC" + "description": "Specifies the `status` of `Shift` records to be returned.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED" }, "ShiftQuery": { "type": "object", - "description": "The parameters of a `Shift` search query, which includes filter and sort options.", - "x-release-status": "PUBLIC", + "description": "The parameters of a `Shift` search query, which includes filter and sort options.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "properties": { "filter": { "$ref": "#/components/schemas/ShiftFilter", @@ -42463,8 +43558,8 @@ }, "ShiftSort": { "type": "object", - "description": "Sets the sort order of search results.", - "x-release-status": "PUBLIC", + "description": "Sets the sort order of search results.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "properties": { "field": { "$ref": "#/components/schemas/ShiftSortField", @@ -42504,8 +43599,8 @@ "description": "The most recent date/time that a `Shift` is updated" } ], - "description": "Enumerates the `Shift` fields to sort on.", - "x-release-status": "PUBLIC" + "description": "Enumerates the `Shift` fields to sort on.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED" }, "ShiftStatus": { "type": "string", @@ -42523,13 +43618,13 @@ "description": "Employee started and ended a work shift." } ], - "description": "Enumerates the possible status of a `Shift`.", - "x-release-status": "PUBLIC" + "description": "Enumerates the possible status of a `Shift`.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED" }, "ShiftWage": { "type": "object", - "description": "The hourly wage rate used to compensate an employee for this shift.", - "x-release-status": "PUBLIC", + "description": "The hourly wage rate used to compensate an employee for this shift.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "properties": { "title": { "type": "string", @@ -42543,7 +43638,7 @@ }, "job_id": { "type": "string", - "description": "The id of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by id. This cannot be used to retrieve the job.", + "description": "The id of the job performed during this shift. Square\nlabor-reporting UIs might group shifts together by id.", "readOnly": true }, "tip_eligible": { @@ -42555,8 +43650,8 @@ }, "ShiftWorkday": { "type": "object", - "description": "A `Shift` search query filter parameter that sets a range of days that\na `Shift` must start or end in before passing the filter condition.", - "x-release-status": "PUBLIC", + "description": "A `Shift` search query filter parameter that sets a range of days that\na `Shift` must start or end in before passing the filter condition.\n\nDeprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes).", + "x-release-status": "DEPRECATED", "properties": { "date_range": { "$ref": "#/components/schemas/DateRange", @@ -42597,7 +43692,7 @@ } ], "description": "Defines the logic used to apply a workday filter.", - "x-release-status": "PUBLIC" + "x-release-status": "DEPRECATED" }, "ShippingFee": { "type": "object", @@ -43833,7 +44928,7 @@ }, "TeamMemberWage": { "type": "object", - "description": "The hourly wage rate that a team member earns on a `Shift` for doing the job\nspecified by the `title` property of this object.", + "description": "Job and wage information for a [team member](entity:TeamMember).\nThis convenience object provides details needed to specify the `wage`\nfield for a [timecard](entity:Timecard).", "x-release-status": "PUBLIC", "properties": { "id": { @@ -43857,7 +44952,7 @@ }, "job_id": { "type": "string", - "description": "An identifier for the job that this wage relates to. This cannot be\nused to retrieve the job.", + "description": "An identifier for the [job](entity:Job) that this wage relates to.", "nullable": true }, "tip_eligible": { @@ -44855,6 +45950,302 @@ } } }, + "Timecard": { + "type": "object", + "description": "A record of the hourly rate, start time, and end time of a single timecard (shift)\nfor a team member. This might include a record of the start and end times of breaks\ntaken during the shift.", + "x-release-status": "PUBLIC", + "required": [ + "location_id", + "start_at", + "team_member_id" + ], + "properties": { + "id": { + "type": "string", + "description": "**Read only** The Square-issued UUID for this object.", + "maxLength": 255 + }, + "location_id": { + "type": "string", + "description": "The ID of the [location](entity:Location) for this timecard. The location should be based on\nwhere the team member clocked in.", + "minLength": 1 + }, + "timezone": { + "type": "string", + "description": "**Read only** The time zone calculated from the location based on the `location_id`,\nprovided as a convenience value. Format: the IANA time zone database identifier for the\nlocation time zone.", + "nullable": true + }, + "start_at": { + "type": "string", + "description": "The start time of the timecard, in RFC 3339 format and shifted to the location\ntimezone + offset. Precision up to the minute is respected; seconds are truncated.", + "minLength": 1 + }, + "end_at": { + "type": "string", + "description": "The end time of the timecard, in RFC 3339 format and shifted to the location\ntimezone + offset. Precision up to the minute is respected; seconds are truncated.", + "nullable": true + }, + "wage": { + "$ref": "#/components/schemas/TimecardWage", + "description": "Job and pay related information. If the wage is not set on create, it defaults to a wage\nof zero. If the title is not set on create, it defaults to the name of the role the team member\nis assigned to, if any.", + "nullable": true + }, + "breaks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Break" + }, + "description": "A list of all the paid or unpaid breaks that were taken during this timecard.", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/TimecardStatus", + "description": "Describes the working state of the timecard.\nSee [TimecardStatus](#type-timecardstatus) for possible values", + "nullable": true + }, + "version": { + "type": "integer", + "description": "**Read only** The current version of the timecard, which is incremented with each update.\nThis field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol to ensure that requests don't overwrite data from another request." + }, + "created_at": { + "type": "string", + "description": "The timestamp of when the timecard was created, in RFC 3339 format presented as UTC.", + "readOnly": true + }, + "updated_at": { + "type": "string", + "description": "The timestamp of when the timecard was last updated, in RFC 3339 format presented as UTC.", + "readOnly": true + }, + "team_member_id": { + "type": "string", + "description": "The ID of the [team member](entity:TeamMember) this timecard belongs to.", + "minLength": 1 + }, + "declared_cash_tip_money": { + "$ref": "#/components/schemas/Money", + "description": "The cash tips declared by the team member for this timecard.", + "nullable": true + } + } + }, + "TimecardFilter": { + "type": "object", + "description": "Defines a filter used in a search for `Timecard` records. `AND` logic is\nused by Square's servers to apply each filter property specified.", + "x-release-status": "PUBLIC", + "properties": { + "location_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Fetch timecards for the specified location.", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/TimecardFilterStatus", + "description": "Fetch a `Timecard` instance by `Timecard.status`.\nSee [TimecardFilterStatus](#type-timecardfilterstatus) for possible values", + "nullable": true + }, + "start": { + "$ref": "#/components/schemas/TimeRange", + "description": "Fetch `Timecard` instances that start in the time range - Inclusive.", + "nullable": true + }, + "end": { + "$ref": "#/components/schemas/TimeRange", + "description": "Fetch the `Timecard` instances that end in the time range - Inclusive.", + "nullable": true + }, + "workday": { + "$ref": "#/components/schemas/TimecardWorkday", + "description": "Fetch the `Timecard` instances based on the workday date range.", + "nullable": true + }, + "team_member_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Fetch timecards for the specified team members.", + "nullable": true + } + } + }, + "TimecardFilterStatus": { + "type": "string", + "enum": [ + "OPEN", + "CLOSED" + ], + "x-enum-elements": [ + { + "name": "OPEN", + "description": "Timecards that have been started and not ended." + }, + { + "name": "CLOSED", + "description": "Timecards that have been started and ended." + } + ], + "description": "Specifies the `status` of `Timecard` records to be returned.", + "x-release-status": "PUBLIC" + }, + "TimecardQuery": { + "type": "object", + "description": "The parameters of a `Timecard` search query, which includes filter and sort options.", + "x-release-status": "PUBLIC", + "properties": { + "filter": { + "$ref": "#/components/schemas/TimecardFilter", + "description": "Query filter options.", + "nullable": true + }, + "sort": { + "$ref": "#/components/schemas/TimecardSort", + "description": "Sort order details.", + "nullable": true + } + } + }, + "TimecardSort": { + "type": "object", + "description": "Sets the sort order of search results.", + "x-release-status": "PUBLIC", + "properties": { + "field": { + "$ref": "#/components/schemas/TimecardSortField", + "description": "The field to sort on.\nSee [TimecardSortField](#type-timecardsortfield) for possible values", + "nullable": true + }, + "order": { + "$ref": "#/components/schemas/SortOrder", + "description": "The order in which results are returned. Defaults to DESC.\nSee [SortOrder](#type-sortorder) for possible values", + "nullable": true + } + } + }, + "TimecardSortField": { + "type": "string", + "enum": [ + "START_AT", + "END_AT", + "CREATED_AT", + "UPDATED_AT" + ], + "x-enum-elements": [ + { + "name": "START_AT", + "description": "The start date/time of a `Timecard`" + }, + { + "name": "END_AT", + "description": "The end date/time of a `Timecard`" + }, + { + "name": "CREATED_AT", + "description": "The date/time that a `Timecard` is created" + }, + { + "name": "UPDATED_AT", + "description": "The most recent date/time that a `Timecard` is updated" + } + ], + "description": "Enumerates the `Timecard` fields to sort on.", + "x-release-status": "PUBLIC" + }, + "TimecardStatus": { + "type": "string", + "enum": [ + "OPEN", + "CLOSED" + ], + "x-enum-elements": [ + { + "name": "OPEN", + "description": "The timecard has a `start_at` time but no `end_at` time, indicating an ongoing shift." + }, + { + "name": "CLOSED", + "description": "The timecard has both `start_at` and `end_at` times, indicating a completed shift." + } + ], + "description": "**Read only** Enumerates the possible status of a [timecard](entity:Timecard).", + "x-release-status": "PUBLIC" + }, + "TimecardWage": { + "type": "object", + "description": "The hourly wage rate used to compensate a team member for a [timecard](entity:Timecard).", + "x-release-status": "PUBLIC", + "properties": { + "title": { + "type": "string", + "description": "The name of the job performed during this timecard.", + "nullable": true + }, + "hourly_rate": { + "$ref": "#/components/schemas/Money", + "description": "Can be a custom-set hourly wage or the calculated effective hourly\nwage based on the annual wage and hours worked per week.", + "nullable": true + }, + "job_id": { + "type": "string", + "description": "The ID of the [job](entity:Job) performed for this timecard. Square\nlabor-reporting UIs might group timecards together by ID.", + "readOnly": true + }, + "tip_eligible": { + "type": "boolean", + "description": "Whether team members are eligible for tips when working this job.", + "nullable": true + } + } + }, + "TimecardWorkday": { + "type": "object", + "description": "A `Timecard` search query filter parameter that sets a range of days that\na `Timecard` must start or end in before passing the filter condition.", + "x-release-status": "PUBLIC", + "properties": { + "date_range": { + "$ref": "#/components/schemas/DateRange", + "description": "Dates for fetching the timecards.", + "nullable": true + }, + "match_timecards_by": { + "$ref": "#/components/schemas/TimecardWorkdayMatcher", + "description": "The strategy on which the dates are applied.\nSee [TimecardWorkdayMatcher](#type-timecardworkdaymatcher) for possible values", + "nullable": true + }, + "default_timezone": { + "type": "string", + "description": "Location-specific timezones convert workdays to datetime filters.\nEvery location included in the query must have a timezone or this field\nmust be provided as a fallback. Format: the IANA timezone database\nidentifier for the relevant timezone.", + "nullable": true + } + } + }, + "TimecardWorkdayMatcher": { + "type": "string", + "enum": [ + "START_AT", + "END_AT", + "INTERSECTION" + ], + "x-enum-elements": [ + { + "name": "START_AT", + "description": "All timecards that start on or after the specified workday" + }, + { + "name": "END_AT", + "description": "All timecards that end on or before the specified workday" + }, + { + "name": "INTERSECTION", + "description": "All timecards that start between the start and end workdays (inclusive)" + } + ], + "description": "Defines the logic used to apply a workday filter.", + "x-release-status": "PUBLIC" + }, "TipSettings": { "type": "object", "x-release-status": "PUBLIC", @@ -46661,10 +48052,73 @@ } } }, + "UpdateScheduledShiftRequest": { + "type": "object", + "x-release-status": "BETA", + "required": [ + "scheduled_shift" + ], + "properties": { + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The scheduled shift with any updates in the `draft_shift_details` field.\nIf needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs,\n[ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers)\nto get team member IDs and current job assignments. Updates made to `published_shift_details`\nare ignored.\n\nIf provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the\nshift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00\n\nTo enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)\ncontrol for the request, provide the current version of the shift in the `version` field.\nIf the provided version doesn't match the server version, the request fails. If `version` is\nomitted, Square executes a blind write, potentially overwriting data from another publish request." + } + }, + "example": { + "scheduled_shift": { + "draft_shift_details": { + "end_at": "2019-03-25T13:18:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-03-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI" + }, + "version": 1 + } + } + }, + "UpdateScheduledShiftResponse": { + "type": "object", + "description": "Represents an [UpdateScheduledShift](api-endpoint:Labor-UpdateScheduledShift) response.\nEither `scheduled_shift` or `errors` is present in the response.", + "x-release-status": "BETA", + "properties": { + "scheduled_shift": { + "$ref": "#/components/schemas/ScheduledShift", + "description": "The updated scheduled shift. To make the changes public, call \n[PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or\n[BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts)." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "scheduled_shift": { + "created_at": "2019-02-25T03:11:00-05:00", + "draft_shift_details": { + "end_at": "2019-03-25T13:18:00-05:00", + "is_deleted": false, + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "location_id": "PAA1RJZZKXBFG", + "notes": "Dont forget to prep the vegetables", + "start_at": "2019-03-25T03:11:00-05:00", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York" + }, + "id": "K0YH4CV5462JB", + "updated_at": "2019-02-25T03:11:15-05:00", + "version": 2 + } + } + }, "UpdateShiftRequest": { "type": "object", "description": "A request to update a `Shift` object.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "required": [ "shift" ], @@ -46710,7 +48164,7 @@ "UpdateShiftResponse": { "type": "object", "description": "The response to a request to update a `Shift`. The response contains\nthe updated `Shift` object and might contain a set of `Error` objects if\nthe request resulted in errors.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", "properties": { "shift": { "$ref": "#/components/schemas/Shift", @@ -46944,6 +48398,110 @@ } } }, + "UpdateTimecardRequest": { + "type": "object", + "description": "A request to update a `Timecard` object.", + "x-release-status": "PUBLIC", + "required": [ + "timecard" + ], + "properties": { + "timecard": { + "$ref": "#/components/schemas/Timecard", + "description": "The updated `Timecard` object." + } + }, + "example": { + "idempotency_key": "HIDSNG5KS478L", + "timecard": { + "breaks": [ + { + "break_type_id": "REGS1EQR1TPZ5", + "end_at": "2019-01-25T06:16:00-05:00", + "expected_duration": "PT5M", + "id": "X7GAQYVVRRG6P", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-25T06:11:00-05:00" + } + ], + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-01-25T13:11:00-05:00", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "status": "CLOSED", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "version": 1, + "wage": { + "hourly_rate": { + "amount": 1500, + "currency": "USD" + }, + "tip_eligible": true, + "title": "Bartender" + } + } + } + }, + "UpdateTimecardResponse": { + "type": "object", + "description": "The response to a request to update a `Timecard`. The response contains\nthe updated `Timecard` object and might contain a set of `Error` objects if\nthe request resulted in errors.", + "x-release-status": "PUBLIC", + "properties": { + "timecard": { + "$ref": "#/components/schemas/Timecard", + "description": "The updated `Timecard`." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "Any errors that occurred during the request." + } + }, + "example": { + "timecard": { + "breaks": [ + { + "break_type_id": "REGS1EQR1TPZ5", + "end_at": "2019-01-25T06:16:00-05:00", + "expected_duration": "PT5M", + "id": "X7GAQYVVRRG6P", + "is_paid": true, + "name": "Tea Break", + "start_at": "2019-01-25T06:11:00-05:00" + } + ], + "created_at": "2019-02-28T00:39:02Z", + "declared_cash_tip_money": { + "amount": 500, + "currency": "USD" + }, + "end_at": "2019-01-25T13:11:00-05:00", + "id": "K0YH4CV5462JB", + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "status": "CLOSED", + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "timezone": "America/New_York", + "updated_at": "2019-02-28T00:42:41Z", + "version": 2, + "wage": { + "hourly_rate": { + "amount": 1500, + "currency": "USD" + }, + "job_id": "dZtrPh5GSDGugyXGByesVp51", + "tip_eligible": true, + "title": "Bartender" + } + } + } + }, "UpdateVendorRequest": { "type": "object", "description": "Represents an input to a call to [UpdateVendor](api-endpoint:Vendors-UpdateVendor).", @@ -48806,8 +50364,8 @@ }, "Labor": { "name": "Labor", - "summary": "Manage shifts, breaks, and wages for employees in Square Point of Sale.", - "description": "\nThe Labor API allows you to see when employees clocked in and out, how much they worked during different\nperiods, and how many breaks they took. You can also call the API to register a past break, adjust a shift,\nor update a wage.\n\nThis API is used in conjunction with the Team API.\n\nFor more information, see the following guides:\n - [Labor](https://developer.squareup.com/docs/labor-api/what-it-does)\n - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)" + "summary": "Manage timecards and schedules for team members.", + "description": "\nThe Labor API allows applications to manage time tracking and shift scheduling workflows.\n\n**Time tracking** - Create and manage timecards (shifts) to track work hours, breaks, and declared cash tips for payroll processing and labor cost calculations. The Labor API provides search capabilities to retrieve timecards by location, time period, status, and team member assignments. It can also be used to access job and wage information for team members, define break types, and configure workweek start times for overtime calculations and reporting periods.\n\n**Scheduling** - Create and manage scheduled shifts with draft and published states to coordinate team member work schedules. The Labor API supports both individual and bulk publishing of scheduled shifts and provides search capabilities to retrieve scheduled shifts by location, time period, status, and team member assignments.\n\nThe Labor API integrates closely with the Team API.\n\nFor more information, see the following guides:\n - [Labor](https://developer.squareup.com/docs/labor-api/what-it-does)\n - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)\n" }, "LocationCustomAttributes": { "name": "Location Custom Attributes", @@ -48841,8 +50399,8 @@ }, "OAuth": { "name": "OAuth", - "summary": "Allow your application to gain programmatic access to other seller accounts.", - "description": "\nThe Square OAuth API lets applications request and obtain permission from a Square account to make API\ncalls on behalf of that account. Applications can request individual permissions so that users do not need\nto grant full access to their Square accounts.\n\nFor more information, see the following guides:\n - [OAuth](https://developer.squareup.com/docs/oauth-api/overview)\n - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)" + "summary": "Allow your application to gain programmatic access to Square seller accounts.", + "description": "\nApplications use the OAuth API to obtain access tokens that allow them to call Square APIs on behalf of Square sellers. Applications can request scoped permissions to limit their access to only the resources they need. The OAuth flow for obtaining an OAuth access token has three stages:\n\n**Authorization** - Your application directs the seller to the Square authorization page using an authorization URL that specifies your requested permissions. The seller signs in to Square and reviews the permissions.\n\n**Callback** - After approving the permissions, Square redirects the seller back to your application's registered redirect URL with an authorization code appended as a query parameter.\n\n**Token request** - Your application calls the `ObtainToken` endpoint with the authorization code, your application ID, and other information. Square returns an access token and refresh token.\n\nFor more information, see the following guides:\n - [OAuth](https://developer.squareup.com/docs/oauth-api/overview)\n - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)" }, "OrderCustomAttributes": { "name": "Order Custom Attributes", @@ -48892,7 +50450,7 @@ "Team": { "name": "Team", "summary": "Manage a roster of team members and pull employee data into accounting and payroll systems.", - "description": "\nThe Team API allows applications to manage team members and job definitions for Square sellers. \nThis includes creating and managing team member profiles, wage settings, and job data. The Team API \nsupports synchronization of team member data with accounting and payroll systems, which is useful \nfor applications that handle payroll, scheduling, and other team member-related activities. \nNote that some operations, such as setting permissions and passcodes, still need to be done directly \nthrough the Square Dashboard.\n\nThe Team API integrates closely with the Labor API for timecard management.\n\nFor more information, see the following guide:\n - [Team](https://developer.squareup.com/docs/team/overview)\n - [Square Webhooks](https://developer.squareup.com/docs/webhooks-overview)\n" + "description": "\nThe Team API allows applications to manage team members and job definitions for Square sellers. \nThis includes creating and managing team member profiles, wage settings, and job data. The Team API \nsupports synchronization of team member data with accounting and payroll systems, which is useful \nfor applications that handle payroll, scheduling, and other team member-related activities. \nNote that some operations, such as setting permissions and passcodes, still need to be done directly \nthrough the Square Dashboard.\n\nThe Team API integrates closely with the Labor API.\n\nFor more information, see the following guide:\n - [Team](https://developer.squareup.com/docs/team/overview)\n - [Square Webhooks](https://developer.squareup.com/docs/webhooks-overview)\n" }, "Terminal": { "name": "Terminal", @@ -48995,7 +50553,7 @@ }, "Staff": { "name": "Staff", - "summary": "Manage team members and jobs, and track shift hours.", + "summary": "Manage team members and jobs, track hours worked, and manage team schedules.", "description": "", "apis": [ "#/components/x-apis/Labor", @@ -56510,6 +58068,329 @@ } } }, + "/v2/labor/scheduled-shifts": { + "post": { + "tags": [ + "Labor" + ], + "summary": "CreateScheduledShift", + "operationId": "CreateScheduledShift", + "description": "Creates a scheduled shift by providing draft shift details such as job ID,\nteam member assignment, and start and end times.\n\nThe following `draft_shift_details` fields are required:\n- `location_id`\n- `job_id`\n- `start_at`\n- `end_at`", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateScheduledShiftRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateScheduledShiftResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + } + ] + } + }, + "/v2/labor/scheduled-shifts/bulk-publish": { + "post": { + "tags": [ + "Labor" + ], + "summary": "BulkPublishScheduledShifts", + "operationId": "BulkPublishScheduledShifts", + "description": "Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish\nrequests and returns a map of responses. When a scheduled shift is published, Square keeps\nthe `draft_shift_details` field as is and copies it to the `published_shift_details` field.\n\nThe minimum `start_at` and maximum `end_at` timestamps of all shifts in a\n`BulkPublishScheduledShifts` request must fall within a two-week period.", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkPublishScheduledShiftsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkPublishScheduledShiftsResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + } + ] + } + }, + "/v2/labor/scheduled-shifts/search": { + "post": { + "tags": [ + "Labor" + ], + "summary": "SearchScheduledShifts", + "operationId": "SearchScheduledShifts", + "description": "Returns a paginated list of scheduled shifts, with optional filter and sort settings.\nBy default, results are sorted by `start_at` in ascending order.", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_READ" + ] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchScheduledShiftsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchScheduledShiftsResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "EXPECTED_STRING" + }, + { + "error-code": "INVALID_VALUE" + }, + { + "error-code": "NOT_FOUND" + } + ] + } + }, + "/v2/labor/scheduled-shifts/{id}": { + "get": { + "tags": [ + "Labor" + ], + "summary": "RetrieveScheduledShift", + "operationId": "RetrieveScheduledShift", + "description": "Retrieves a scheduled shift by ID.", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_READ" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The ID of the scheduled shift to retrieve.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveScheduledShiftResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "NOT_FOUND" + } + ] + }, + "put": { + "tags": [ + "Labor" + ], + "summary": "UpdateScheduledShift", + "operationId": "UpdateScheduledShift", + "description": "Updates the draft shift details for a scheduled shift. This endpoint supports\nsparse updates, so only new, changed, or removed fields are required in the request.\nYou must publish the shift to make updates public.\n\nYou can make the following updates to `draft_shift_details`:\n- Change the `location_id`, `job_id`, `start_at`, and `end_at` fields.\n- Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields,\nset the value to null.\n- Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true\nand then publish the shift.", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The ID of the scheduled shift to update.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateScheduledShiftRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateScheduledShiftResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + }, + { + "error-code": "VERSION_MISMATCH" + } + ] + } + }, + "/v2/labor/scheduled-shifts/{id}/publish": { + "post": { + "tags": [ + "Labor" + ], + "summary": "PublishScheduledShift", + "operationId": "PublishScheduledShift", + "description": "Publishes a scheduled shift. When a scheduled shift is published, Square keeps the\n`draft_shift_details` field as is and copies it to the `published_shift_details` field.", + "x-release-status": "BETA", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The ID of the scheduled shift to publish.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublishScheduledShiftRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublishScheduledShiftResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + } + ] + } + }, "/v2/labor/shifts": { "post": { "tags": [ @@ -56518,7 +58399,14 @@ "summary": "CreateShift", "operationId": "CreateShift", "description": "Creates a new `Shift`.\n\nA `Shift` represents a complete workday for a single team member.\nYou must provide the following values in your request to this\nendpoint:\n\n- `location_id`\n- `team_member_id`\n- `start_at`\n\nAn attempt to create a new `Shift` can result in a `BAD_REQUEST` error when:\n- The `status` of the new `Shift` is `OPEN` and the team member has another\nshift with an `OPEN` status.\n- The `start_at` date is in the future.\n- The `start_at` or `end_at` date overlaps another shift for the same team member.\n- The `Break` instances are set in the request and a break `start_at`\nis before the `Shift.start_at`, a break `end_at` is after\nthe `Shift.end_at`, or both.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", + "deprecated": true, + "x-deprecation": { + "deprecationDate": "2025-05-21", + "retirementDate": "2026-05-21", + "replacedBy": "CreateTimecard", + "guideUrl": "https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes" + }, "security": [ { "oauth2": [ @@ -56560,7 +58448,14 @@ "summary": "SearchShifts", "operationId": "SearchShifts", "description": "Returns a paginated list of `Shift` records for a business.\nThe list to be returned can be filtered by:\n- Location IDs\n- Team member IDs\n- Shift status (`OPEN` or `CLOSED`)\n- Shift start\n- Shift end\n- Workday details\n\nThe list can be sorted by:\n- `START_AT`\n- `END_AT`\n- `CREATED_AT`\n- `UPDATED_AT`", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", + "deprecated": true, + "x-deprecation": { + "deprecationDate": "2025-05-21", + "retirementDate": "2026-05-21", + "replacedBy": "SearchTimecards", + "guideUrl": "https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes" + }, "security": [ { "oauth2": [ @@ -56602,7 +58497,14 @@ "summary": "DeleteShift", "operationId": "DeleteShift", "description": "Deletes a `Shift`.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", + "deprecated": true, + "x-deprecation": { + "deprecationDate": "2025-05-21", + "retirementDate": "2026-05-21", + "replacedBy": "DeleteTimecard", + "guideUrl": "https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes" + }, "security": [ { "oauth2": [ @@ -56641,7 +58543,14 @@ "summary": "GetShift", "operationId": "GetShift", "description": "Returns a single `Shift` specified by `id`.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", + "deprecated": true, + "x-deprecation": { + "deprecationDate": "2025-05-21", + "retirementDate": "2026-05-21", + "replacedBy": "RetrieveTimecard", + "guideUrl": "https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes" + }, "security": [ { "oauth2": [ @@ -56680,7 +58589,14 @@ "summary": "UpdateShift", "operationId": "UpdateShift", "description": "Updates an existing `Shift`.\n\nWhen adding a `Break` to a `Shift`, any earlier `Break` instances in the `Shift` have\nthe `end_at` property set to a valid RFC-3339 datetime string.\n\nWhen closing a `Shift`, all `Break` instances in the `Shift` must be complete with `end_at`\nset on each `Break`.", - "x-release-status": "PUBLIC", + "x-release-status": "DEPRECATED", + "deprecated": true, + "x-deprecation": { + "deprecationDate": "2025-05-21", + "retirementDate": "2026-05-21", + "replacedBy": "UpdateTimecard", + "guideUrl": "https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes" + }, "security": [ { "oauth2": [ @@ -56825,6 +58741,253 @@ } } }, + "/v2/labor/timecards": { + "post": { + "tags": [ + "Labor" + ], + "summary": "CreateTimecard", + "operationId": "CreateTimecard", + "description": "Creates a new `Timecard`.\n\nA `Timecard` represents a complete workday for a single team member.\nYou must provide the following values in your request to this\nendpoint:\n\n- `location_id`\n- `team_member_id`\n- `start_at`\n\nAn attempt to create a new `Timecard` can result in a `BAD_REQUEST` error when:\n- The `status` of the new `Timecard` is `OPEN` and the team member has another\ntimecard with an `OPEN` status.\n- The `start_at` date is in the future.\n- The `start_at` or `end_at` date overlaps another timecard for the same team member.\n- The `Break` instances are set in the request and a break `start_at`\nis before the `Timecard.start_at`, a break `end_at` is after\nthe `Timecard.end_at`, or both.", + "x-release-status": "PUBLIC", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTimecardRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTimecardResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + }, + { + "error-code": "NOT_FOUND" + } + ] + } + }, + "/v2/labor/timecards/search": { + "post": { + "tags": [ + "Labor" + ], + "summary": "SearchTimecards", + "operationId": "SearchTimecards", + "description": "Returns a paginated list of `Timecard` records for a business.\nThe list to be returned can be filtered by:\n- Location IDs\n- Team member IDs\n- Timecard status (`OPEN` or `CLOSED`)\n- Timecard start\n- Timecard end\n- Workday details\n\nThe list can be sorted by:\n- `START_AT`\n- `END_AT`\n- `CREATED_AT`\n- `UPDATED_AT`", + "x-release-status": "PUBLIC", + "security": [ + { + "oauth2": [ + "TIMECARDS_READ" + ] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchTimecardsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchTimecardsResponse" + } + } + } + } + } + } + }, + "/v2/labor/timecards/{id}": { + "delete": { + "tags": [ + "Labor" + ], + "summary": "DeleteTimecard", + "operationId": "DeleteTimecard", + "description": "Deletes a `Timecard`.", + "x-release-status": "PUBLIC", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The UUID for the `Timecard` being deleted.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteTimecardResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "NOT_FOUND" + } + ] + }, + "get": { + "tags": [ + "Labor" + ], + "summary": "RetrieveTimecard", + "operationId": "RetrieveTimecard", + "description": "Returns a single `Timecard` specified by `id`.", + "x-release-status": "PUBLIC", + "security": [ + { + "oauth2": [ + "TIMECARDS_READ" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The UUID for the `Timecard` being retrieved.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveTimecardResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "NOT_FOUND" + } + ] + }, + "put": { + "tags": [ + "Labor" + ], + "summary": "UpdateTimecard", + "operationId": "UpdateTimecard", + "description": "Updates an existing `Timecard`.\n\nWhen adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have\nthe `end_at` property set to a valid RFC-3339 datetime string.\n\nWhen closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at`\nset on each `Break`.", + "x-release-status": "PUBLIC", + "security": [ + { + "oauth2": [ + "TIMECARDS_WRITE", + "TIMECARDS_READ" + ] + } + ], + "parameters": [ + { + "name": "id", + "description": "The ID of the object being updated.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ], + "requestBody": { + "required": true, + "description": "An object containing the fields to POST for the request.\n\nSee the corresponding object definition for field details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTimecardRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTimecardResponse" + } + } + } + } + }, + "x-endpoint-errors": [ + { + "error-code": "BAD_REQUEST" + }, + { + "error-code": "INVALID_VALUE" + }, + { + "error-code": "VERSION_MISMATCH" + } + ] + } + }, "/v2/labor/workweek-configs": { "get": { "tags": [ @@ -64777,7 +66940,7 @@ "name": "version", "optional": true, "env": "VERSION", - "type": "literal\u003c\"2025-04-16\"\u003e" + "type": "literal\u003c\"2025-05-21\"\u003e" } ] } \ No newline at end of file diff --git a/poetry.lock b/poetry.lock index 451995a4..f13c117d 100644 --- a/poetry.lock +++ b/poetry.lock @@ -60,15 +60,18 @@ files = [ [[package]] name = "exceptiongroup" -version = "1.2.2" +version = "1.3.0" description = "Backport of PEP 654 (exception groups)" optional = false python-versions = ">=3.7" files = [ - {file = "exceptiongroup-1.2.2-py3-none-any.whl", hash = "sha256:3111b9d131c238bec2f8f516e123e14ba243563fb135d3fe885990585aa7795b"}, - {file = "exceptiongroup-1.2.2.tar.gz", hash = "sha256:47c2edf7c6738fafb49fd34290706d1a1a2f4d1c6df275526b62cbb4aa5393cc"}, + {file = "exceptiongroup-1.3.0-py3-none-any.whl", hash = "sha256:4d111e6e0c13d0644cad6ddaa7ed0261a0b36971f6d23e7ec9b4b9097da78a10"}, + {file = "exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88"}, ] +[package.dependencies] +typing-extensions = {version = ">=4.6.0", markers = "python_version < \"3.13\""} + [package.extras] test = ["pytest (>=6)"] diff --git a/pyproject.toml b/pyproject.toml index cb845219..28040e1f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "squareup" [tool.poetry] name = "squareup" -version = "42.1.0.20250416" +version = "42.1.0.20250521" description = "" readme = "README.md" authors = [] diff --git a/reference.md b/reference.md index 0a9eab00..48d280b2 100644 --- a/reference.md +++ b/reference.md @@ -8873,6 +8873,1076 @@ For more information, see [Idempotency](https://developer.squareup.com/docs/buil + + + + +## Labor +
client.labor.create_scheduled_shift(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Creates a scheduled shift by providing draft shift details such as job ID, +team member assignment, and start and end times. + +The following `draft_shift_details` fields are required: +- `location_id` +- `job_id` +- `start_at` +- `end_at` +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.create_scheduled_shift( + idempotency_key="HIDSNG5KS478L", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + } + }, +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**scheduled_shift:** `ScheduledShiftParams` + +The scheduled shift with `draft_shift_details`. +If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, +[ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) +to get team member IDs and current job assignments. + +The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the +shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + +
+
+ +
+
+ +**idempotency_key:** `typing.Optional[str]` + +A unique identifier for the `CreateScheduledShift` request, used to ensure the +[idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) +of the operation. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.bulk_publish_scheduled_shifts(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish +requests and returns a map of responses. When a scheduled shift is published, Square keeps +the `draft_shift_details` field as is and copies it to the `published_shift_details` field. + +The minimum `start_at` and maximum `end_at` timestamps of all shifts in a +`BulkPublishScheduledShifts` request must fall within a two-week period. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.bulk_publish_scheduled_shifts( + scheduled_shifts={"key": {}}, + scheduled_shift_notification_audience="AFFECTED", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**scheduled_shifts:** `typing.Dict[str, BulkPublishScheduledShiftsDataParams]` + +A map of 1 to 100 key-value pairs that represent individual publish requests. + +- Each key is the ID of a scheduled shift you want to publish. +- Each value is a `BulkPublishScheduledShiftsData` object that contains the +`version` field or is an empty object. + +
+
+ +
+
+ +**scheduled_shift_notification_audience:** `typing.Optional[ScheduledShiftNotificationAudience]` + +Indicates whether Square should send email notifications to team members and +which team members should receive the notifications. This setting applies to all shifts +specified in the bulk operation. The default value is `AFFECTED`. +See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.search_scheduled_shifts(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Returns a paginated list of scheduled shifts, with optional filter and sort settings. +By default, results are sorted by `start_at` in ascending order. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.search_scheduled_shifts( + query={ + "filter": {"assignment_status": "ASSIGNED"}, + "sort": {"field": "CREATED_AT", "order": "ASC"}, + }, + limit=2, + cursor="xoxp-1234-5678-90123", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**query:** `typing.Optional[ScheduledShiftQueryParams]` — Query conditions used to filter and sort the results. + +
+
+ +
+
+ +**limit:** `typing.Optional[int]` — The maximum number of results to return in a single response page. The default value is 50. + +
+
+ +
+
+ +**cursor:** `typing.Optional[str]` + +The pagination cursor returned by the previous call to this endpoint. Provide +this cursor to retrieve the next page of results for your original request. For more +information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.retrieve_scheduled_shift(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Retrieves a scheduled shift by ID. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.retrieve_scheduled_shift( + id="id", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The ID of the scheduled shift to retrieve. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.update_scheduled_shift(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Updates the draft shift details for a scheduled shift. This endpoint supports +sparse updates, so only new, changed, or removed fields are required in the request. +You must publish the shift to make updates public. + +You can make the following updates to `draft_shift_details`: +- Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. +- Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, +set the value to null. +- Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true +and then publish the shift. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.update_scheduled_shift( + id="id", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-03-25T03:11:00-05:00", + "end_at": "2019-03-25T13:18:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + }, + "version": 1, + }, +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The ID of the scheduled shift to update. + +
+
+ +
+
+ +**scheduled_shift:** `ScheduledShiftParams` + +The scheduled shift with any updates in the `draft_shift_details` field. +If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, +[ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) +to get team member IDs and current job assignments. Updates made to `published_shift_details` +are ignored. + +If provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the +shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + +To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) +control for the request, provide the current version of the shift in the `version` field. +If the provided version doesn't match the server version, the request fails. If `version` is +omitted, Square executes a blind write, potentially overwriting data from another publish request. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.publish_scheduled_shift(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Publishes a scheduled shift. When a scheduled shift is published, Square keeps the +`draft_shift_details` field as is and copies it to the `published_shift_details` field. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.publish_scheduled_shift( + id="id", + idempotency_key="HIDSNG5KS478L", + version=2, + scheduled_shift_notification_audience="ALL", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The ID of the scheduled shift to publish. + +
+
+ +
+
+ +**idempotency_key:** `str` + +A unique identifier for the `PublishScheduledShift` request, used to ensure the +[idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) +of the operation. + +
+
+ +
+
+ +**version:** `typing.Optional[int]` + +The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) +control. If the provided version doesn't match the server version, the request fails. +If omitted, Square executes a blind write, potentially overwriting data from another publish request. + +
+
+ +
+
+ +**scheduled_shift_notification_audience:** `typing.Optional[ScheduledShiftNotificationAudience]` + +Indicates whether Square should send an email notification to team members and +which team members should receive the notification. The default value is `AFFECTED`. +See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.create_timecard(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +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. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.create_timecard( + idempotency_key="HIDSNG5KS478L", + timecard={ + "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, + } + ], + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**timecard:** `TimecardParams` — The `Timecard` to be created. + +
+
+ +
+
+ +**idempotency_key:** `typing.Optional[str]` — A unique string value to ensure the idempotency of the operation. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.search_timecards(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Returns a paginated list of `Timecard` records for a business. +The list to be returned can be filtered by: +- Location IDs +- Team member IDs +- Timecard status (`OPEN` or `CLOSED`) +- Timecard start +- Timecard end +- Workday details + +The list can be sorted by: +- `START_AT` +- `END_AT` +- `CREATED_AT` +- `UPDATED_AT` +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.search_timecards( + query={ + "filter": { + "workday": { + "date_range": { + "start_date": "2019-01-20", + "end_date": "2019-02-03", + }, + "match_timecards_by": "START_AT", + "default_timezone": "America/Los_Angeles", + } + } + }, + limit=100, +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**query:** `typing.Optional[TimecardQueryParams]` — Query filters. + +
+
+ +
+
+ +**limit:** `typing.Optional[int]` — The number of resources in a page (200 by default). + +
+
+ +
+
+ +**cursor:** `typing.Optional[str]` — An opaque cursor for fetching the next page. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.retrieve_timecard(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Returns a single `Timecard` specified by `id`. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.retrieve_timecard( + id="id", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The UUID for the `Timecard` being retrieved. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.update_timecard(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Updates an existing `Timecard`. + +When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have +the `end_at` property set to a valid RFC-3339 datetime string. + +When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` +set on each `Break`. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.update_timecard( + id="id", + timecard={ + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Bartender", + "hourly_rate": {"amount": 1500, "currency": "USD"}, + "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, + } + ], + "status": "CLOSED", + "version": 1, + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The ID of the object being updated. + +
+
+ +
+
+ +**timecard:** `TimecardParams` — The updated `Timecard` object. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ + +
+
+
+ +
client.labor.delete_timecard(...) +
+
+ +#### 📝 Description + +
+
+ +
+
+ +Deletes a `Timecard`. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```python +from square import Square + +client = Square( + token="YOUR_TOKEN", +) +client.labor.delete_timecard( + id="id", +) + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**id:** `str` — The UUID for the `Timecard` being deleted. + +
+
+ +
+
+ +**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration. + +
+
+
+
+ +
diff --git a/src/square/client.py b/src/square/client.py index 32f7873d..d00177ed 100644 --- a/src/square/client.py +++ b/src/square/client.py @@ -21,6 +21,7 @@ from .gift_cards.client import GiftCardsClient from .inventory.client import InventoryClient from .invoices.client import InvoicesClient +from .labor.client import LaborClient from .locations.client import LocationsClient from .loyalty.client import LoyaltyClient from .merchants.client import MerchantsClient @@ -37,7 +38,6 @@ from .terminal.client import TerminalClient from .vendors.client import VendorsClient from .cash_drawers.client import CashDrawersClient -from .labor.client import LaborClient from .webhooks.client import WebhooksClient from .core.client_wrapper import AsyncClientWrapper from .mobile.client import AsyncMobileClient @@ -56,6 +56,7 @@ from .gift_cards.client import AsyncGiftCardsClient from .inventory.client import AsyncInventoryClient from .invoices.client import AsyncInvoicesClient +from .labor.client import AsyncLaborClient from .locations.client import AsyncLocationsClient from .loyalty.client import AsyncLoyaltyClient from .merchants.client import AsyncMerchantsClient @@ -72,7 +73,6 @@ from .terminal.client import AsyncTerminalClient from .vendors.client import AsyncVendorsClient from .cash_drawers.client import AsyncCashDrawersClient -from .labor.client import AsyncLaborClient from .webhooks.client import AsyncWebhooksClient @@ -155,6 +155,7 @@ def __init__( self.gift_cards = GiftCardsClient(client_wrapper=self._client_wrapper) self.inventory = InventoryClient(client_wrapper=self._client_wrapper) self.invoices = InvoicesClient(client_wrapper=self._client_wrapper) + self.labor = LaborClient(client_wrapper=self._client_wrapper) self.locations = LocationsClient(client_wrapper=self._client_wrapper) self.loyalty = LoyaltyClient(client_wrapper=self._client_wrapper) self.merchants = MerchantsClient(client_wrapper=self._client_wrapper) @@ -171,7 +172,6 @@ def __init__( self.terminal = TerminalClient(client_wrapper=self._client_wrapper) self.vendors = VendorsClient(client_wrapper=self._client_wrapper) self.cash_drawers = CashDrawersClient(client_wrapper=self._client_wrapper) - self.labor = LaborClient(client_wrapper=self._client_wrapper) self.webhooks = WebhooksClient(client_wrapper=self._client_wrapper) @@ -254,6 +254,7 @@ def __init__( self.gift_cards = AsyncGiftCardsClient(client_wrapper=self._client_wrapper) self.inventory = AsyncInventoryClient(client_wrapper=self._client_wrapper) self.invoices = AsyncInvoicesClient(client_wrapper=self._client_wrapper) + self.labor = AsyncLaborClient(client_wrapper=self._client_wrapper) self.locations = AsyncLocationsClient(client_wrapper=self._client_wrapper) self.loyalty = AsyncLoyaltyClient(client_wrapper=self._client_wrapper) self.merchants = AsyncMerchantsClient(client_wrapper=self._client_wrapper) @@ -270,7 +271,6 @@ def __init__( self.terminal = AsyncTerminalClient(client_wrapper=self._client_wrapper) self.vendors = AsyncVendorsClient(client_wrapper=self._client_wrapper) self.cash_drawers = AsyncCashDrawersClient(client_wrapper=self._client_wrapper) - self.labor = AsyncLaborClient(client_wrapper=self._client_wrapper) self.webhooks = AsyncWebhooksClient(client_wrapper=self._client_wrapper) diff --git a/src/square/core/client_wrapper.py b/src/square/core/client_wrapper.py index 2e99323b..37377251 100644 --- a/src/square/core/client_wrapper.py +++ b/src/square/core/client_wrapper.py @@ -22,15 +22,15 @@ def __init__( def get_headers(self) -> typing.Dict[str, str]: headers: typing.Dict[str, str] = { - "User-Agent": "squareup/42.1.0.20250416", + "User-Agent": "squareup/42.1.0.20250521", "X-Fern-Language": "Python", "X-Fern-SDK-Name": "squareup", - "X-Fern-SDK-Version": "42.1.0.20250416", + "X-Fern-SDK-Version": "42.1.0.20250521", } token = self._get_token() if token is not None: headers["Authorization"] = f"Bearer {token}" - headers["Square-Version"] = self._version if self._version is not None else "2025-04-16" + headers["Square-Version"] = self._version if self._version is not None else "2025-05-21" return headers def _get_token(self) -> typing.Optional[str]: diff --git a/src/square/labor/client.py b/src/square/labor/client.py index aa170b26..e62db55c 100644 --- a/src/square/labor/client.py +++ b/src/square/labor/client.py @@ -1,5 +1,6 @@ # This file was auto-generated by Fern from our API Definition. +import typing from ..core.client_wrapper import SyncClientWrapper from .raw_client import RawLaborClient from .break_types.client import BreakTypesClient @@ -7,6 +8,24 @@ from .shifts.client import ShiftsClient from .team_member_wages.client import TeamMemberWagesClient from .workweek_configs.client import WorkweekConfigsClient +from ..requests.scheduled_shift import ScheduledShiftParams +from ..core.request_options import RequestOptions +from ..types.create_scheduled_shift_response import CreateScheduledShiftResponse +from ..requests.bulk_publish_scheduled_shifts_data import BulkPublishScheduledShiftsDataParams +from ..types.scheduled_shift_notification_audience import ScheduledShiftNotificationAudience +from ..types.bulk_publish_scheduled_shifts_response import BulkPublishScheduledShiftsResponse +from ..requests.scheduled_shift_query import ScheduledShiftQueryParams +from ..types.search_scheduled_shifts_response import SearchScheduledShiftsResponse +from ..types.retrieve_scheduled_shift_response import RetrieveScheduledShiftResponse +from ..types.update_scheduled_shift_response import UpdateScheduledShiftResponse +from ..types.publish_scheduled_shift_response import PublishScheduledShiftResponse +from ..requests.timecard import TimecardParams +from ..types.create_timecard_response import CreateTimecardResponse +from ..requests.timecard_query import TimecardQueryParams +from ..types.search_timecards_response import SearchTimecardsResponse +from ..types.retrieve_timecard_response import RetrieveTimecardResponse +from ..types.update_timecard_response import UpdateTimecardResponse +from ..types.delete_timecard_response import DeleteTimecardResponse from ..core.client_wrapper import AsyncClientWrapper from .raw_client import AsyncRawLaborClient from .break_types.client import AsyncBreakTypesClient @@ -15,6 +34,9 @@ from .team_member_wages.client import AsyncTeamMemberWagesClient from .workweek_configs.client import AsyncWorkweekConfigsClient +# this is used as the default value for optional parameters +OMIT = typing.cast(typing.Any, ...) + class LaborClient: def __init__(self, *, client_wrapper: SyncClientWrapper): @@ -40,6 +62,638 @@ def with_raw_response(self) -> RawLaborClient: """ return self._raw_client + def create_scheduled_shift( + self, + *, + scheduled_shift: ScheduledShiftParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> CreateScheduledShiftResponse: + """ + Creates a scheduled shift by providing draft shift details such as job ID, + team member assignment, and start and end times. + + The following `draft_shift_details` fields are required: + - `location_id` + - `job_id` + - `start_at` + - `end_at` + + Parameters + ---------- + scheduled_shift : ScheduledShiftParams + The scheduled shift with `draft_shift_details`. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. + + The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + idempotency_key : typing.Optional[str] + A unique identifier for the `CreateScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + CreateScheduledShiftResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.create_scheduled_shift( + idempotency_key="HIDSNG5KS478L", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + } + }, + ) + """ + response = self._raw_client.create_scheduled_shift( + scheduled_shift=scheduled_shift, idempotency_key=idempotency_key, request_options=request_options + ) + return response.data + + def bulk_publish_scheduled_shifts( + self, + *, + scheduled_shifts: typing.Dict[str, BulkPublishScheduledShiftsDataParams], + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> BulkPublishScheduledShiftsResponse: + """ + Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish + requests and returns a map of responses. When a scheduled shift is published, Square keeps + the `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + The minimum `start_at` and maximum `end_at` timestamps of all shifts in a + `BulkPublishScheduledShifts` request must fall within a two-week period. + + Parameters + ---------- + scheduled_shifts : typing.Dict[str, BulkPublishScheduledShiftsDataParams] + A map of 1 to 100 key-value pairs that represent individual publish requests. + + - Each key is the ID of a scheduled shift you want to publish. + - Each value is a `BulkPublishScheduledShiftsData` object that contains the + `version` field or is an empty object. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send email notifications to team members and + which team members should receive the notifications. This setting applies to all shifts + specified in the bulk operation. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + BulkPublishScheduledShiftsResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.bulk_publish_scheduled_shifts( + scheduled_shifts={"key": {}}, + scheduled_shift_notification_audience="AFFECTED", + ) + """ + response = self._raw_client.bulk_publish_scheduled_shifts( + scheduled_shifts=scheduled_shifts, + scheduled_shift_notification_audience=scheduled_shift_notification_audience, + request_options=request_options, + ) + return response.data + + def search_scheduled_shifts( + self, + *, + query: typing.Optional[ScheduledShiftQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> SearchScheduledShiftsResponse: + """ + Returns a paginated list of scheduled shifts, with optional filter and sort settings. + By default, results are sorted by `start_at` in ascending order. + + Parameters + ---------- + query : typing.Optional[ScheduledShiftQueryParams] + Query conditions used to filter and sort the results. + + limit : typing.Optional[int] + The maximum number of results to return in a single response page. The default value is 50. + + cursor : typing.Optional[str] + The pagination cursor returned by the previous call to this endpoint. Provide + this cursor to retrieve the next page of results for your original request. For more + information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + SearchScheduledShiftsResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.search_scheduled_shifts( + query={ + "filter": {"assignment_status": "ASSIGNED"}, + "sort": {"field": "CREATED_AT", "order": "ASC"}, + }, + limit=2, + cursor="xoxp-1234-5678-90123", + ) + """ + response = self._raw_client.search_scheduled_shifts( + query=query, limit=limit, cursor=cursor, request_options=request_options + ) + return response.data + + def retrieve_scheduled_shift( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> RetrieveScheduledShiftResponse: + """ + Retrieves a scheduled shift by ID. + + Parameters + ---------- + id : str + The ID of the scheduled shift to retrieve. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + RetrieveScheduledShiftResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.retrieve_scheduled_shift( + id="id", + ) + """ + response = self._raw_client.retrieve_scheduled_shift(id, request_options=request_options) + return response.data + + def update_scheduled_shift( + self, id: str, *, scheduled_shift: ScheduledShiftParams, request_options: typing.Optional[RequestOptions] = None + ) -> UpdateScheduledShiftResponse: + """ + Updates the draft shift details for a scheduled shift. This endpoint supports + sparse updates, so only new, changed, or removed fields are required in the request. + You must publish the shift to make updates public. + + You can make the following updates to `draft_shift_details`: + - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. + - Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, + set the value to null. + - Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true + and then publish the shift. + + Parameters + ---------- + id : str + The ID of the scheduled shift to update. + + scheduled_shift : ScheduledShiftParams + The scheduled shift with any updates in the `draft_shift_details` field. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. Updates made to `published_shift_details` + are ignored. + + If provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control for the request, provide the current version of the shift in the `version` field. + If the provided version doesn't match the server version, the request fails. If `version` is + omitted, Square executes a blind write, potentially overwriting data from another publish request. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + UpdateScheduledShiftResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.update_scheduled_shift( + id="id", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-03-25T03:11:00-05:00", + "end_at": "2019-03-25T13:18:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + }, + "version": 1, + }, + ) + """ + response = self._raw_client.update_scheduled_shift( + id, scheduled_shift=scheduled_shift, request_options=request_options + ) + return response.data + + def publish_scheduled_shift( + self, + id: str, + *, + idempotency_key: str, + version: typing.Optional[int] = OMIT, + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> PublishScheduledShiftResponse: + """ + Publishes a scheduled shift. When a scheduled shift is published, Square keeps the + `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + Parameters + ---------- + id : str + The ID of the scheduled shift to publish. + + idempotency_key : str + A unique identifier for the `PublishScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + version : typing.Optional[int] + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send an email notification to team members and + which team members should receive the notification. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + PublishScheduledShiftResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.publish_scheduled_shift( + id="id", + idempotency_key="HIDSNG5KS478L", + version=2, + scheduled_shift_notification_audience="ALL", + ) + """ + response = self._raw_client.publish_scheduled_shift( + id, + idempotency_key=idempotency_key, + version=version, + scheduled_shift_notification_audience=scheduled_shift_notification_audience, + request_options=request_options, + ) + return response.data + + def create_timecard( + self, + *, + timecard: TimecardParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> CreateTimecardResponse: + """ + 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. + + Parameters + ---------- + timecard : TimecardParams + The `Timecard` to be created. + + idempotency_key : typing.Optional[str] + A unique string value to ensure the idempotency of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + CreateTimecardResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.create_timecard( + idempotency_key="HIDSNG5KS478L", + timecard={ + "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, + } + ], + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, + ) + """ + response = self._raw_client.create_timecard( + timecard=timecard, idempotency_key=idempotency_key, request_options=request_options + ) + return response.data + + def search_timecards( + self, + *, + query: typing.Optional[TimecardQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> SearchTimecardsResponse: + """ + Returns a paginated list of `Timecard` records for a business. + The list to be returned can be filtered by: + - Location IDs + - Team member IDs + - Timecard status (`OPEN` or `CLOSED`) + - Timecard start + - Timecard end + - Workday details + + The list can be sorted by: + - `START_AT` + - `END_AT` + - `CREATED_AT` + - `UPDATED_AT` + + Parameters + ---------- + query : typing.Optional[TimecardQueryParams] + Query filters. + + limit : typing.Optional[int] + The number of resources in a page (200 by default). + + cursor : typing.Optional[str] + An opaque cursor for fetching the next page. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + SearchTimecardsResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.search_timecards( + query={ + "filter": { + "workday": { + "date_range": { + "start_date": "2019-01-20", + "end_date": "2019-02-03", + }, + "match_timecards_by": "START_AT", + "default_timezone": "America/Los_Angeles", + } + } + }, + limit=100, + ) + """ + response = self._raw_client.search_timecards( + query=query, limit=limit, cursor=cursor, request_options=request_options + ) + return response.data + + def retrieve_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> RetrieveTimecardResponse: + """ + Returns a single `Timecard` specified by `id`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being retrieved. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + RetrieveTimecardResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.retrieve_timecard( + id="id", + ) + """ + response = self._raw_client.retrieve_timecard(id, request_options=request_options) + return response.data + + def update_timecard( + self, id: str, *, timecard: TimecardParams, request_options: typing.Optional[RequestOptions] = None + ) -> UpdateTimecardResponse: + """ + Updates an existing `Timecard`. + + When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have + the `end_at` property set to a valid RFC-3339 datetime string. + + When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` + set on each `Break`. + + Parameters + ---------- + id : str + The ID of the object being updated. + + timecard : TimecardParams + The updated `Timecard` object. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + UpdateTimecardResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.update_timecard( + id="id", + timecard={ + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Bartender", + "hourly_rate": {"amount": 1500, "currency": "USD"}, + "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, + } + ], + "status": "CLOSED", + "version": 1, + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, + ) + """ + response = self._raw_client.update_timecard(id, timecard=timecard, request_options=request_options) + return response.data + + def delete_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> DeleteTimecardResponse: + """ + Deletes a `Timecard`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being deleted. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + DeleteTimecardResponse + Success + + Examples + -------- + from square import Square + + client = Square( + token="YOUR_TOKEN", + ) + client.labor.delete_timecard( + id="id", + ) + """ + response = self._raw_client.delete_timecard(id, request_options=request_options) + return response.data + class AsyncLaborClient: def __init__(self, *, client_wrapper: AsyncClientWrapper): @@ -64,3 +718,723 @@ def with_raw_response(self) -> AsyncRawLaborClient: AsyncRawLaborClient """ return self._raw_client + + async def create_scheduled_shift( + self, + *, + scheduled_shift: ScheduledShiftParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> CreateScheduledShiftResponse: + """ + Creates a scheduled shift by providing draft shift details such as job ID, + team member assignment, and start and end times. + + The following `draft_shift_details` fields are required: + - `location_id` + - `job_id` + - `start_at` + - `end_at` + + Parameters + ---------- + scheduled_shift : ScheduledShiftParams + The scheduled shift with `draft_shift_details`. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. + + The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + idempotency_key : typing.Optional[str] + A unique identifier for the `CreateScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + CreateScheduledShiftResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.create_scheduled_shift( + idempotency_key="HIDSNG5KS478L", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + } + }, + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.create_scheduled_shift( + scheduled_shift=scheduled_shift, idempotency_key=idempotency_key, request_options=request_options + ) + return response.data + + async def bulk_publish_scheduled_shifts( + self, + *, + scheduled_shifts: typing.Dict[str, BulkPublishScheduledShiftsDataParams], + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> BulkPublishScheduledShiftsResponse: + """ + Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish + requests and returns a map of responses. When a scheduled shift is published, Square keeps + the `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + The minimum `start_at` and maximum `end_at` timestamps of all shifts in a + `BulkPublishScheduledShifts` request must fall within a two-week period. + + Parameters + ---------- + scheduled_shifts : typing.Dict[str, BulkPublishScheduledShiftsDataParams] + A map of 1 to 100 key-value pairs that represent individual publish requests. + + - Each key is the ID of a scheduled shift you want to publish. + - Each value is a `BulkPublishScheduledShiftsData` object that contains the + `version` field or is an empty object. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send email notifications to team members and + which team members should receive the notifications. This setting applies to all shifts + specified in the bulk operation. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + BulkPublishScheduledShiftsResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.bulk_publish_scheduled_shifts( + scheduled_shifts={"key": {}}, + scheduled_shift_notification_audience="AFFECTED", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.bulk_publish_scheduled_shifts( + scheduled_shifts=scheduled_shifts, + scheduled_shift_notification_audience=scheduled_shift_notification_audience, + request_options=request_options, + ) + return response.data + + async def search_scheduled_shifts( + self, + *, + query: typing.Optional[ScheduledShiftQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> SearchScheduledShiftsResponse: + """ + Returns a paginated list of scheduled shifts, with optional filter and sort settings. + By default, results are sorted by `start_at` in ascending order. + + Parameters + ---------- + query : typing.Optional[ScheduledShiftQueryParams] + Query conditions used to filter and sort the results. + + limit : typing.Optional[int] + The maximum number of results to return in a single response page. The default value is 50. + + cursor : typing.Optional[str] + The pagination cursor returned by the previous call to this endpoint. Provide + this cursor to retrieve the next page of results for your original request. For more + information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + SearchScheduledShiftsResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.search_scheduled_shifts( + query={ + "filter": {"assignment_status": "ASSIGNED"}, + "sort": {"field": "CREATED_AT", "order": "ASC"}, + }, + limit=2, + cursor="xoxp-1234-5678-90123", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.search_scheduled_shifts( + query=query, limit=limit, cursor=cursor, request_options=request_options + ) + return response.data + + async def retrieve_scheduled_shift( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> RetrieveScheduledShiftResponse: + """ + Retrieves a scheduled shift by ID. + + Parameters + ---------- + id : str + The ID of the scheduled shift to retrieve. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + RetrieveScheduledShiftResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.retrieve_scheduled_shift( + id="id", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.retrieve_scheduled_shift(id, request_options=request_options) + return response.data + + async def update_scheduled_shift( + self, id: str, *, scheduled_shift: ScheduledShiftParams, request_options: typing.Optional[RequestOptions] = None + ) -> UpdateScheduledShiftResponse: + """ + Updates the draft shift details for a scheduled shift. This endpoint supports + sparse updates, so only new, changed, or removed fields are required in the request. + You must publish the shift to make updates public. + + You can make the following updates to `draft_shift_details`: + - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. + - Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, + set the value to null. + - Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true + and then publish the shift. + + Parameters + ---------- + id : str + The ID of the scheduled shift to update. + + scheduled_shift : ScheduledShiftParams + The scheduled shift with any updates in the `draft_shift_details` field. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. Updates made to `published_shift_details` + are ignored. + + If provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control for the request, provide the current version of the shift in the `version` field. + If the provided version doesn't match the server version, the request fails. If `version` is + omitted, Square executes a blind write, potentially overwriting data from another publish request. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + UpdateScheduledShiftResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.update_scheduled_shift( + id="id", + scheduled_shift={ + "draft_shift_details": { + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "location_id": "PAA1RJZZKXBFG", + "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M", + "start_at": "2019-03-25T03:11:00-05:00", + "end_at": "2019-03-25T13:18:00-05:00", + "notes": "Dont forget to prep the vegetables", + "is_deleted": False, + }, + "version": 1, + }, + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.update_scheduled_shift( + id, scheduled_shift=scheduled_shift, request_options=request_options + ) + return response.data + + async def publish_scheduled_shift( + self, + id: str, + *, + idempotency_key: str, + version: typing.Optional[int] = OMIT, + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> PublishScheduledShiftResponse: + """ + Publishes a scheduled shift. When a scheduled shift is published, Square keeps the + `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + Parameters + ---------- + id : str + The ID of the scheduled shift to publish. + + idempotency_key : str + A unique identifier for the `PublishScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + version : typing.Optional[int] + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send an email notification to team members and + which team members should receive the notification. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + PublishScheduledShiftResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.publish_scheduled_shift( + id="id", + idempotency_key="HIDSNG5KS478L", + version=2, + scheduled_shift_notification_audience="ALL", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.publish_scheduled_shift( + id, + idempotency_key=idempotency_key, + version=version, + scheduled_shift_notification_audience=scheduled_shift_notification_audience, + request_options=request_options, + ) + return response.data + + async def create_timecard( + self, + *, + timecard: TimecardParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> CreateTimecardResponse: + """ + 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. + + Parameters + ---------- + timecard : TimecardParams + The `Timecard` to be created. + + idempotency_key : typing.Optional[str] + A unique string value to ensure the idempotency of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + CreateTimecardResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.create_timecard( + idempotency_key="HIDSNG5KS478L", + timecard={ + "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, + } + ], + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.create_timecard( + timecard=timecard, idempotency_key=idempotency_key, request_options=request_options + ) + return response.data + + async def search_timecards( + self, + *, + query: typing.Optional[TimecardQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> SearchTimecardsResponse: + """ + Returns a paginated list of `Timecard` records for a business. + The list to be returned can be filtered by: + - Location IDs + - Team member IDs + - Timecard status (`OPEN` or `CLOSED`) + - Timecard start + - Timecard end + - Workday details + + The list can be sorted by: + - `START_AT` + - `END_AT` + - `CREATED_AT` + - `UPDATED_AT` + + Parameters + ---------- + query : typing.Optional[TimecardQueryParams] + Query filters. + + limit : typing.Optional[int] + The number of resources in a page (200 by default). + + cursor : typing.Optional[str] + An opaque cursor for fetching the next page. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + SearchTimecardsResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.search_timecards( + query={ + "filter": { + "workday": { + "date_range": { + "start_date": "2019-01-20", + "end_date": "2019-02-03", + }, + "match_timecards_by": "START_AT", + "default_timezone": "America/Los_Angeles", + } + } + }, + limit=100, + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.search_timecards( + query=query, limit=limit, cursor=cursor, request_options=request_options + ) + return response.data + + async def retrieve_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> RetrieveTimecardResponse: + """ + Returns a single `Timecard` specified by `id`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being retrieved. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + RetrieveTimecardResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.retrieve_timecard( + id="id", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.retrieve_timecard(id, request_options=request_options) + return response.data + + async def update_timecard( + self, id: str, *, timecard: TimecardParams, request_options: typing.Optional[RequestOptions] = None + ) -> UpdateTimecardResponse: + """ + Updates an existing `Timecard`. + + When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have + the `end_at` property set to a valid RFC-3339 datetime string. + + When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` + set on each `Break`. + + Parameters + ---------- + id : str + The ID of the object being updated. + + timecard : TimecardParams + The updated `Timecard` object. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + UpdateTimecardResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.update_timecard( + id="id", + timecard={ + "location_id": "PAA1RJZZKXBFG", + "start_at": "2019-01-25T03:11:00-05:00", + "end_at": "2019-01-25T13:11:00-05:00", + "wage": { + "title": "Bartender", + "hourly_rate": {"amount": 1500, "currency": "USD"}, + "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, + } + ], + "status": "CLOSED", + "version": 1, + "team_member_id": "ormj0jJJZ5OZIzxrZYJI", + "declared_cash_tip_money": {"amount": 500, "currency": "USD"}, + }, + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.update_timecard(id, timecard=timecard, request_options=request_options) + return response.data + + async def delete_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> DeleteTimecardResponse: + """ + Deletes a `Timecard`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being deleted. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + DeleteTimecardResponse + Success + + Examples + -------- + import asyncio + + from square import AsyncSquare + + client = AsyncSquare( + token="YOUR_TOKEN", + ) + + + async def main() -> None: + await client.labor.delete_timecard( + id="id", + ) + + + asyncio.run(main()) + """ + response = await self._raw_client.delete_timecard(id, request_options=request_options) + return response.data diff --git a/src/square/labor/raw_client.py b/src/square/labor/raw_client.py index a8d409c3..a6fcd97a 100644 --- a/src/square/labor/raw_client.py +++ b/src/square/labor/raw_client.py @@ -1,14 +1,1379 @@ # This file was auto-generated by Fern from our API Definition. +import typing from ..core.client_wrapper import SyncClientWrapper +from ..requests.scheduled_shift import ScheduledShiftParams +from ..core.request_options import RequestOptions +from ..core.http_response import HttpResponse +from ..types.create_scheduled_shift_response import CreateScheduledShiftResponse +from ..core.serialization import convert_and_respect_annotation_metadata +from ..core.unchecked_base_model import construct_type +from json.decoder import JSONDecodeError +from ..core.api_error import ApiError +from ..requests.bulk_publish_scheduled_shifts_data import BulkPublishScheduledShiftsDataParams +from ..types.scheduled_shift_notification_audience import ScheduledShiftNotificationAudience +from ..types.bulk_publish_scheduled_shifts_response import BulkPublishScheduledShiftsResponse +from ..requests.scheduled_shift_query import ScheduledShiftQueryParams +from ..types.search_scheduled_shifts_response import SearchScheduledShiftsResponse +from ..types.retrieve_scheduled_shift_response import RetrieveScheduledShiftResponse +from ..core.jsonable_encoder import jsonable_encoder +from ..types.update_scheduled_shift_response import UpdateScheduledShiftResponse +from ..types.publish_scheduled_shift_response import PublishScheduledShiftResponse +from ..requests.timecard import TimecardParams +from ..types.create_timecard_response import CreateTimecardResponse +from ..requests.timecard_query import TimecardQueryParams +from ..types.search_timecards_response import SearchTimecardsResponse +from ..types.retrieve_timecard_response import RetrieveTimecardResponse +from ..types.update_timecard_response import UpdateTimecardResponse +from ..types.delete_timecard_response import DeleteTimecardResponse from ..core.client_wrapper import AsyncClientWrapper +from ..core.http_response import AsyncHttpResponse + +# this is used as the default value for optional parameters +OMIT = typing.cast(typing.Any, ...) class RawLaborClient: def __init__(self, *, client_wrapper: SyncClientWrapper): self._client_wrapper = client_wrapper + def create_scheduled_shift( + self, + *, + scheduled_shift: ScheduledShiftParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[CreateScheduledShiftResponse]: + """ + Creates a scheduled shift by providing draft shift details such as job ID, + team member assignment, and start and end times. + + The following `draft_shift_details` fields are required: + - `location_id` + - `job_id` + - `start_at` + - `end_at` + + Parameters + ---------- + scheduled_shift : ScheduledShiftParams + The scheduled shift with `draft_shift_details`. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. + + The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + idempotency_key : typing.Optional[str] + A unique identifier for the `CreateScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[CreateScheduledShiftResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts", + method="POST", + json={ + "idempotency_key": idempotency_key, + "scheduled_shift": convert_and_respect_annotation_metadata( + object_=scheduled_shift, annotation=ScheduledShiftParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + CreateScheduledShiftResponse, + construct_type( + type_=CreateScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def bulk_publish_scheduled_shifts( + self, + *, + scheduled_shifts: typing.Dict[str, BulkPublishScheduledShiftsDataParams], + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[BulkPublishScheduledShiftsResponse]: + """ + Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish + requests and returns a map of responses. When a scheduled shift is published, Square keeps + the `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + The minimum `start_at` and maximum `end_at` timestamps of all shifts in a + `BulkPublishScheduledShifts` request must fall within a two-week period. + + Parameters + ---------- + scheduled_shifts : typing.Dict[str, BulkPublishScheduledShiftsDataParams] + A map of 1 to 100 key-value pairs that represent individual publish requests. + + - Each key is the ID of a scheduled shift you want to publish. + - Each value is a `BulkPublishScheduledShiftsData` object that contains the + `version` field or is an empty object. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send email notifications to team members and + which team members should receive the notifications. This setting applies to all shifts + specified in the bulk operation. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[BulkPublishScheduledShiftsResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts/bulk-publish", + method="POST", + json={ + "scheduled_shifts": convert_and_respect_annotation_metadata( + object_=scheduled_shifts, + annotation=typing.Dict[str, BulkPublishScheduledShiftsDataParams], + direction="write", + ), + "scheduled_shift_notification_audience": scheduled_shift_notification_audience, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + BulkPublishScheduledShiftsResponse, + construct_type( + type_=BulkPublishScheduledShiftsResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def search_scheduled_shifts( + self, + *, + query: typing.Optional[ScheduledShiftQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[SearchScheduledShiftsResponse]: + """ + Returns a paginated list of scheduled shifts, with optional filter and sort settings. + By default, results are sorted by `start_at` in ascending order. + + Parameters + ---------- + query : typing.Optional[ScheduledShiftQueryParams] + Query conditions used to filter and sort the results. + + limit : typing.Optional[int] + The maximum number of results to return in a single response page. The default value is 50. + + cursor : typing.Optional[str] + The pagination cursor returned by the previous call to this endpoint. Provide + this cursor to retrieve the next page of results for your original request. For more + information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[SearchScheduledShiftsResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts/search", + method="POST", + json={ + "query": convert_and_respect_annotation_metadata( + object_=query, annotation=ScheduledShiftQueryParams, direction="write" + ), + "limit": limit, + "cursor": cursor, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + SearchScheduledShiftsResponse, + construct_type( + type_=SearchScheduledShiftsResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def retrieve_scheduled_shift( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> HttpResponse[RetrieveScheduledShiftResponse]: + """ + Retrieves a scheduled shift by ID. + + Parameters + ---------- + id : str + The ID of the scheduled shift to retrieve. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[RetrieveScheduledShiftResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}", + method="GET", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + RetrieveScheduledShiftResponse, + construct_type( + type_=RetrieveScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def update_scheduled_shift( + self, id: str, *, scheduled_shift: ScheduledShiftParams, request_options: typing.Optional[RequestOptions] = None + ) -> HttpResponse[UpdateScheduledShiftResponse]: + """ + Updates the draft shift details for a scheduled shift. This endpoint supports + sparse updates, so only new, changed, or removed fields are required in the request. + You must publish the shift to make updates public. + + You can make the following updates to `draft_shift_details`: + - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. + - Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, + set the value to null. + - Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true + and then publish the shift. + + Parameters + ---------- + id : str + The ID of the scheduled shift to update. + + scheduled_shift : ScheduledShiftParams + The scheduled shift with any updates in the `draft_shift_details` field. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. Updates made to `published_shift_details` + are ignored. + + If provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control for the request, provide the current version of the shift in the `version` field. + If the provided version doesn't match the server version, the request fails. If `version` is + omitted, Square executes a blind write, potentially overwriting data from another publish request. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[UpdateScheduledShiftResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}", + method="PUT", + json={ + "scheduled_shift": convert_and_respect_annotation_metadata( + object_=scheduled_shift, annotation=ScheduledShiftParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + UpdateScheduledShiftResponse, + construct_type( + type_=UpdateScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def publish_scheduled_shift( + self, + id: str, + *, + idempotency_key: str, + version: typing.Optional[int] = OMIT, + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[PublishScheduledShiftResponse]: + """ + Publishes a scheduled shift. When a scheduled shift is published, Square keeps the + `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + Parameters + ---------- + id : str + The ID of the scheduled shift to publish. + + idempotency_key : str + A unique identifier for the `PublishScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + version : typing.Optional[int] + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send an email notification to team members and + which team members should receive the notification. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[PublishScheduledShiftResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}/publish", + method="POST", + json={ + "idempotency_key": idempotency_key, + "version": version, + "scheduled_shift_notification_audience": scheduled_shift_notification_audience, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + PublishScheduledShiftResponse, + construct_type( + type_=PublishScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def create_timecard( + self, + *, + timecard: TimecardParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[CreateTimecardResponse]: + """ + 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. + + Parameters + ---------- + timecard : TimecardParams + The `Timecard` to be created. + + idempotency_key : typing.Optional[str] + A unique string value to ensure the idempotency of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[CreateTimecardResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + "v2/labor/timecards", + method="POST", + json={ + "idempotency_key": idempotency_key, + "timecard": convert_and_respect_annotation_metadata( + object_=timecard, annotation=TimecardParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + CreateTimecardResponse, + construct_type( + type_=CreateTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def search_timecards( + self, + *, + query: typing.Optional[TimecardQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> HttpResponse[SearchTimecardsResponse]: + """ + Returns a paginated list of `Timecard` records for a business. + The list to be returned can be filtered by: + - Location IDs + - Team member IDs + - Timecard status (`OPEN` or `CLOSED`) + - Timecard start + - Timecard end + - Workday details + + The list can be sorted by: + - `START_AT` + - `END_AT` + - `CREATED_AT` + - `UPDATED_AT` + + Parameters + ---------- + query : typing.Optional[TimecardQueryParams] + Query filters. + + limit : typing.Optional[int] + The number of resources in a page (200 by default). + + cursor : typing.Optional[str] + An opaque cursor for fetching the next page. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[SearchTimecardsResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + "v2/labor/timecards/search", + method="POST", + json={ + "query": convert_and_respect_annotation_metadata( + object_=query, annotation=TimecardQueryParams, direction="write" + ), + "limit": limit, + "cursor": cursor, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + SearchTimecardsResponse, + construct_type( + type_=SearchTimecardsResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def retrieve_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> HttpResponse[RetrieveTimecardResponse]: + """ + Returns a single `Timecard` specified by `id`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being retrieved. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[RetrieveTimecardResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="GET", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + RetrieveTimecardResponse, + construct_type( + type_=RetrieveTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def update_timecard( + self, id: str, *, timecard: TimecardParams, request_options: typing.Optional[RequestOptions] = None + ) -> HttpResponse[UpdateTimecardResponse]: + """ + Updates an existing `Timecard`. + + When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have + the `end_at` property set to a valid RFC-3339 datetime string. + + When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` + set on each `Break`. + + Parameters + ---------- + id : str + The ID of the object being updated. + + timecard : TimecardParams + The updated `Timecard` object. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[UpdateTimecardResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="PUT", + json={ + "timecard": convert_and_respect_annotation_metadata( + object_=timecard, annotation=TimecardParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + UpdateTimecardResponse, + construct_type( + type_=UpdateTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + def delete_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> HttpResponse[DeleteTimecardResponse]: + """ + Deletes a `Timecard`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being deleted. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + HttpResponse[DeleteTimecardResponse] + Success + """ + _response = self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="DELETE", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + DeleteTimecardResponse, + construct_type( + type_=DeleteTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return HttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + class AsyncRawLaborClient: def __init__(self, *, client_wrapper: AsyncClientWrapper): self._client_wrapper = client_wrapper + + async def create_scheduled_shift( + self, + *, + scheduled_shift: ScheduledShiftParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[CreateScheduledShiftResponse]: + """ + Creates a scheduled shift by providing draft shift details such as job ID, + team member assignment, and start and end times. + + The following `draft_shift_details` fields are required: + - `location_id` + - `job_id` + - `start_at` + - `end_at` + + Parameters + ---------- + scheduled_shift : ScheduledShiftParams + The scheduled shift with `draft_shift_details`. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. + + The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + idempotency_key : typing.Optional[str] + A unique identifier for the `CreateScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[CreateScheduledShiftResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts", + method="POST", + json={ + "idempotency_key": idempotency_key, + "scheduled_shift": convert_and_respect_annotation_metadata( + object_=scheduled_shift, annotation=ScheduledShiftParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + CreateScheduledShiftResponse, + construct_type( + type_=CreateScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def bulk_publish_scheduled_shifts( + self, + *, + scheduled_shifts: typing.Dict[str, BulkPublishScheduledShiftsDataParams], + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[BulkPublishScheduledShiftsResponse]: + """ + Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish + requests and returns a map of responses. When a scheduled shift is published, Square keeps + the `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + The minimum `start_at` and maximum `end_at` timestamps of all shifts in a + `BulkPublishScheduledShifts` request must fall within a two-week period. + + Parameters + ---------- + scheduled_shifts : typing.Dict[str, BulkPublishScheduledShiftsDataParams] + A map of 1 to 100 key-value pairs that represent individual publish requests. + + - Each key is the ID of a scheduled shift you want to publish. + - Each value is a `BulkPublishScheduledShiftsData` object that contains the + `version` field or is an empty object. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send email notifications to team members and + which team members should receive the notifications. This setting applies to all shifts + specified in the bulk operation. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[BulkPublishScheduledShiftsResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts/bulk-publish", + method="POST", + json={ + "scheduled_shifts": convert_and_respect_annotation_metadata( + object_=scheduled_shifts, + annotation=typing.Dict[str, BulkPublishScheduledShiftsDataParams], + direction="write", + ), + "scheduled_shift_notification_audience": scheduled_shift_notification_audience, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + BulkPublishScheduledShiftsResponse, + construct_type( + type_=BulkPublishScheduledShiftsResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def search_scheduled_shifts( + self, + *, + query: typing.Optional[ScheduledShiftQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[SearchScheduledShiftsResponse]: + """ + Returns a paginated list of scheduled shifts, with optional filter and sort settings. + By default, results are sorted by `start_at` in ascending order. + + Parameters + ---------- + query : typing.Optional[ScheduledShiftQueryParams] + Query conditions used to filter and sort the results. + + limit : typing.Optional[int] + The maximum number of results to return in a single response page. The default value is 50. + + cursor : typing.Optional[str] + The pagination cursor returned by the previous call to this endpoint. Provide + this cursor to retrieve the next page of results for your original request. For more + information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[SearchScheduledShiftsResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + "v2/labor/scheduled-shifts/search", + method="POST", + json={ + "query": convert_and_respect_annotation_metadata( + object_=query, annotation=ScheduledShiftQueryParams, direction="write" + ), + "limit": limit, + "cursor": cursor, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + SearchScheduledShiftsResponse, + construct_type( + type_=SearchScheduledShiftsResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def retrieve_scheduled_shift( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> AsyncHttpResponse[RetrieveScheduledShiftResponse]: + """ + Retrieves a scheduled shift by ID. + + Parameters + ---------- + id : str + The ID of the scheduled shift to retrieve. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[RetrieveScheduledShiftResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}", + method="GET", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + RetrieveScheduledShiftResponse, + construct_type( + type_=RetrieveScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def update_scheduled_shift( + self, id: str, *, scheduled_shift: ScheduledShiftParams, request_options: typing.Optional[RequestOptions] = None + ) -> AsyncHttpResponse[UpdateScheduledShiftResponse]: + """ + Updates the draft shift details for a scheduled shift. This endpoint supports + sparse updates, so only new, changed, or removed fields are required in the request. + You must publish the shift to make updates public. + + You can make the following updates to `draft_shift_details`: + - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. + - Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, + set the value to null. + - Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true + and then publish the shift. + + Parameters + ---------- + id : str + The ID of the scheduled shift to update. + + scheduled_shift : ScheduledShiftParams + The scheduled shift with any updates in the `draft_shift_details` field. + If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs, + [ListJobs](api-endpoint:Team-ListJobs) to get job IDs, and [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) + to get team member IDs and current job assignments. Updates made to `published_shift_details` + are ignored. + + If provided, the `start_at` and `end_at` timestamps must be in the time zone + offset of the + shift location specified in `location_id`. Example for Pacific Standard Time: 2024-10-31T12:30:00-08:00 + + To enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control for the request, provide the current version of the shift in the `version` field. + If the provided version doesn't match the server version, the request fails. If `version` is + omitted, Square executes a blind write, potentially overwriting data from another publish request. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[UpdateScheduledShiftResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}", + method="PUT", + json={ + "scheduled_shift": convert_and_respect_annotation_metadata( + object_=scheduled_shift, annotation=ScheduledShiftParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + UpdateScheduledShiftResponse, + construct_type( + type_=UpdateScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def publish_scheduled_shift( + self, + id: str, + *, + idempotency_key: str, + version: typing.Optional[int] = OMIT, + scheduled_shift_notification_audience: typing.Optional[ScheduledShiftNotificationAudience] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[PublishScheduledShiftResponse]: + """ + Publishes a scheduled shift. When a scheduled shift is published, Square keeps the + `draft_shift_details` field as is and copies it to the `published_shift_details` field. + + Parameters + ---------- + id : str + The ID of the scheduled shift to publish. + + idempotency_key : str + A unique identifier for the `PublishScheduledShift` request, used to ensure the + [idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) + of the operation. + + version : typing.Optional[int] + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + + scheduled_shift_notification_audience : typing.Optional[ScheduledShiftNotificationAudience] + Indicates whether Square should send an email notification to team members and + which team members should receive the notification. The default value is `AFFECTED`. + See [ScheduledShiftNotificationAudience](#type-scheduledshiftnotificationaudience) for possible values + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[PublishScheduledShiftResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/scheduled-shifts/{jsonable_encoder(id)}/publish", + method="POST", + json={ + "idempotency_key": idempotency_key, + "version": version, + "scheduled_shift_notification_audience": scheduled_shift_notification_audience, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + PublishScheduledShiftResponse, + construct_type( + type_=PublishScheduledShiftResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def create_timecard( + self, + *, + timecard: TimecardParams, + idempotency_key: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[CreateTimecardResponse]: + """ + 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. + + Parameters + ---------- + timecard : TimecardParams + The `Timecard` to be created. + + idempotency_key : typing.Optional[str] + A unique string value to ensure the idempotency of the operation. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[CreateTimecardResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + "v2/labor/timecards", + method="POST", + json={ + "idempotency_key": idempotency_key, + "timecard": convert_and_respect_annotation_metadata( + object_=timecard, annotation=TimecardParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + CreateTimecardResponse, + construct_type( + type_=CreateTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def search_timecards( + self, + *, + query: typing.Optional[TimecardQueryParams] = OMIT, + limit: typing.Optional[int] = OMIT, + cursor: typing.Optional[str] = OMIT, + request_options: typing.Optional[RequestOptions] = None, + ) -> AsyncHttpResponse[SearchTimecardsResponse]: + """ + Returns a paginated list of `Timecard` records for a business. + The list to be returned can be filtered by: + - Location IDs + - Team member IDs + - Timecard status (`OPEN` or `CLOSED`) + - Timecard start + - Timecard end + - Workday details + + The list can be sorted by: + - `START_AT` + - `END_AT` + - `CREATED_AT` + - `UPDATED_AT` + + Parameters + ---------- + query : typing.Optional[TimecardQueryParams] + Query filters. + + limit : typing.Optional[int] + The number of resources in a page (200 by default). + + cursor : typing.Optional[str] + An opaque cursor for fetching the next page. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[SearchTimecardsResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + "v2/labor/timecards/search", + method="POST", + json={ + "query": convert_and_respect_annotation_metadata( + object_=query, annotation=TimecardQueryParams, direction="write" + ), + "limit": limit, + "cursor": cursor, + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + SearchTimecardsResponse, + construct_type( + type_=SearchTimecardsResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def retrieve_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> AsyncHttpResponse[RetrieveTimecardResponse]: + """ + Returns a single `Timecard` specified by `id`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being retrieved. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[RetrieveTimecardResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="GET", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + RetrieveTimecardResponse, + construct_type( + type_=RetrieveTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def update_timecard( + self, id: str, *, timecard: TimecardParams, request_options: typing.Optional[RequestOptions] = None + ) -> AsyncHttpResponse[UpdateTimecardResponse]: + """ + Updates an existing `Timecard`. + + When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have + the `end_at` property set to a valid RFC-3339 datetime string. + + When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` + set on each `Break`. + + Parameters + ---------- + id : str + The ID of the object being updated. + + timecard : TimecardParams + The updated `Timecard` object. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[UpdateTimecardResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="PUT", + json={ + "timecard": convert_and_respect_annotation_metadata( + object_=timecard, annotation=TimecardParams, direction="write" + ), + }, + headers={ + "content-type": "application/json", + }, + request_options=request_options, + omit=OMIT, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + UpdateTimecardResponse, + construct_type( + type_=UpdateTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) + + async def delete_timecard( + self, id: str, *, request_options: typing.Optional[RequestOptions] = None + ) -> AsyncHttpResponse[DeleteTimecardResponse]: + """ + Deletes a `Timecard`. + + Parameters + ---------- + id : str + The UUID for the `Timecard` being deleted. + + request_options : typing.Optional[RequestOptions] + Request-specific configuration. + + Returns + ------- + AsyncHttpResponse[DeleteTimecardResponse] + Success + """ + _response = await self._client_wrapper.httpx_client.request( + f"v2/labor/timecards/{jsonable_encoder(id)}", + method="DELETE", + request_options=request_options, + ) + try: + if 200 <= _response.status_code < 300: + _data = typing.cast( + DeleteTimecardResponse, + construct_type( + type_=DeleteTimecardResponse, # type: ignore + object_=_response.json(), + ), + ) + return AsyncHttpResponse(response=_response, data=_data) + _response_json = _response.json() + except JSONDecodeError: + raise ApiError(status_code=_response.status_code, body=_response.text) + raise ApiError(status_code=_response.status_code, body=_response_json) diff --git a/src/square/requests/break_.py b/src/square/requests/break_.py index 53f2b769..411ddd30 100644 --- a/src/square/requests/break_.py +++ b/src/square/requests/break_.py @@ -7,7 +7,7 @@ class BreakParams(typing_extensions.TypedDict): """ - A record of an employee's break during a shift. + A record of a team member's break on a [timecard](entity:Timecard). """ id: typing_extensions.NotRequired[str] @@ -17,19 +17,19 @@ class BreakParams(typing_extensions.TypedDict): start_at: str """ - RFC 3339; follows the same timezone information as `Shift`. Precision up to + RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. """ end_at: typing_extensions.NotRequired[typing.Optional[str]] """ - RFC 3339; follows the same timezone information as `Shift`. Precision up to + RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. """ break_type_id: str """ - The `BreakType` that this `Break` was templated on. + The [BreakType](entity:BreakType) that this break was templated on. """ name: str @@ -41,6 +41,8 @@ class BreakParams(typing_extensions.TypedDict): """ Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of the break. + + Example for break expected duration of 15 minutes: PT15M """ is_paid: bool diff --git a/src/square/requests/break_type.py b/src/square/requests/break_type.py index aa630780..4632bb07 100644 --- a/src/square/requests/break_type.py +++ b/src/square/requests/break_type.py @@ -6,8 +6,8 @@ class BreakTypeParams(typing_extensions.TypedDict): """ - A defined break template that sets an expectation for possible `Break` - instances on a `Shift`. + A template for a type of [break](entity:Break) that can be added to a + [timecard](entity:Timecard), including the expected duration and paid status. """ id: typing_extensions.NotRequired[str] @@ -23,7 +23,7 @@ class BreakTypeParams(typing_extensions.TypedDict): break_name: str """ A human-readable name for this type of break. The name is displayed to - employees in Square products. + team members in Square products. """ expected_duration: str @@ -31,7 +31,7 @@ class BreakTypeParams(typing_extensions.TypedDict): Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of this break. Precision less than minutes is truncated. - Example for break expected duration of 15 minutes: T15M + Example for break expected duration of 15 minutes: PT15M """ is_paid: bool diff --git a/src/square/requests/bulk_publish_scheduled_shifts_data.py b/src/square/requests/bulk_publish_scheduled_shifts_data.py new file mode 100644 index 00000000..9a2cf290 --- /dev/null +++ b/src/square/requests/bulk_publish_scheduled_shifts_data.py @@ -0,0 +1,19 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions + + +class BulkPublishScheduledShiftsDataParams(typing_extensions.TypedDict): + """ + Represents options for an individual publish request in a + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) + operation, provided as the value in a key-value pair. + """ + + version: typing_extensions.NotRequired[int] + """ + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + """ diff --git a/src/square/requests/bulk_publish_scheduled_shifts_response.py b/src/square/requests/bulk_publish_scheduled_shifts_response.py new file mode 100644 index 00000000..c3ff4e01 --- /dev/null +++ b/src/square/requests/bulk_publish_scheduled_shifts_response.py @@ -0,0 +1,30 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .publish_scheduled_shift_response import PublishScheduledShiftResponseParams +from .error import ErrorParams + + +class BulkPublishScheduledShiftsResponseParams(typing_extensions.TypedDict): + """ + Represents a [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) response. + Either `scheduled_shifts` or `errors` is present in the response. + """ + + responses: typing_extensions.NotRequired[typing.Dict[str, PublishScheduledShiftResponseParams]] + """ + A map of key-value pairs that represent responses for individual publish requests. + The order of responses might differ from the order in which the requests were provided. + + - Each key is the scheduled shift ID that was specified for a publish request. + - Each value is the corresponding response. If the request succeeds, the value is the + published scheduled shift. If the request fails, the value is an `errors` array containing + any errors that occurred while processing the request. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any top-level errors that prevented the bulk operation from succeeding. + """ diff --git a/src/square/requests/catalog_item.py b/src/square/requests/catalog_item.py index 73a681fa..e9b7407e 100644 --- a/src/square/requests/catalog_item.py +++ b/src/square/requests/catalog_item.py @@ -112,12 +112,12 @@ class CatalogItemParams(typing_extensions.TypedDict): ecom_uri: typing_extensions.NotRequired[typing.Optional[str]] """ - Deprecated; see go/ecomUriUseCases. A URI pointing to a published e-commerce product page for the Item. + Deprecated. A URI pointing to a published e-commerce product page for the Item. """ ecom_image_uris: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] """ - Deprecated; see go/ecomUriUseCases. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item. + Deprecated. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item. """ image_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] diff --git a/src/square/requests/catalog_item_modifier_list_info.py b/src/square/requests/catalog_item_modifier_list_info.py index d2b61d26..8adf0b38 100644 --- a/src/square/requests/catalog_item_modifier_list_info.py +++ b/src/square/requests/catalog_item_modifier_list_info.py @@ -8,8 +8,8 @@ class CatalogItemModifierListInfoParams(typing_extensions.TypedDict): """ - References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance - and specifies supported behaviors of the application. + Controls how a modifier list is applied to a specific item. This object allows for item-specific customization of modifier list behavior + and provides the ability to override global modifier list settings. """ modifier_list_id: str @@ -19,35 +19,31 @@ class CatalogItemModifierListInfoParams(typing_extensions.TypedDict): modifier_overrides: typing_extensions.NotRequired[typing.Optional[typing.Sequence[CatalogModifierOverrideParams]]] """ - A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default. + A set of `CatalogModifierOverride` objects that override default modifier settings for this item. """ min_selected_modifiers: typing_extensions.NotRequired[typing.Optional[int]] """ - If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`. - The default value is `-1`. + The minimum number of modifiers that must be selected from this modifier list. + Values: - When `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of - the `CatalogModifierList` can be selected from the `CatalogModifierList`. - - When the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in - and can be selected from the `CatalogModifierList` + - 0: No selection is required. + - -1: Default value, the attribute was not set by the client. When `max_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`. + - >0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no selection required. """ max_selected_modifiers: typing_extensions.NotRequired[typing.Optional[int]] """ - If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`. - The default value is `-1`. - - When `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of - the `CatalogModifierList` can be selected from the `CatalogModifierList`. + The maximum number of modifiers that can be selected. + Values: - When the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in - and can be selected from the `CatalogModifierList` + - 0: No maximum limit. + - -1: Default value, the attribute was not set by the client. When `min_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`. + - >0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no maximum limit. """ enabled: typing_extensions.NotRequired[typing.Optional[bool]] @@ -60,3 +56,7 @@ class CatalogItemModifierListInfoParams(typing_extensions.TypedDict): The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied to a `CatalogItem` instance. """ + + allow_quantities: typing_extensions.NotRequired[typing.Optional[typing.Any]] + is_conversational: typing_extensions.NotRequired[typing.Optional[typing.Any]] + hidden_from_customer_override: typing_extensions.NotRequired[typing.Optional[typing.Any]] diff --git a/src/square/requests/catalog_modifier.py b/src/square/requests/catalog_modifier.py index 342171b0..e2f85572 100644 --- a/src/square/requests/catalog_modifier.py +++ b/src/square/requests/catalog_modifier.py @@ -9,7 +9,7 @@ class CatalogModifierParams(typing_extensions.TypedDict): """ - A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item. + A modifier that can be applied to items at the time of sale. For example, a cheese modifier for a burger, or a flavor modifier for a serving of ice cream. """ name: typing_extensions.NotRequired[typing.Optional[str]] @@ -22,6 +22,12 @@ class CatalogModifierParams(typing_extensions.TypedDict): The modifier price. """ + on_by_default: typing_extensions.NotRequired[typing.Optional[bool]] + """ + When `true`, this modifier is selected by default when displaying the modifier list. + This setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`. + """ + ordinal: typing_extensions.NotRequired[typing.Optional[int]] """ Determines where this `CatalogModifier` appears in the `CatalogModifierList`. @@ -42,3 +48,8 @@ class CatalogModifierParams(typing_extensions.TypedDict): The ID of the image associated with this `CatalogModifier` instance. Currently this image is not displayed by Square, but is free to be displayed in 3rd party applications. """ + + hidden_online: typing_extensions.NotRequired[typing.Optional[bool]] + """ + When `true`, this modifier is hidden from online ordering channels. This setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`. + """ diff --git a/src/square/requests/catalog_modifier_list.py b/src/square/requests/catalog_modifier_list.py index d5248bd2..d7d16801 100644 --- a/src/square/requests/catalog_modifier_list.py +++ b/src/square/requests/catalog_modifier_list.py @@ -14,18 +14,11 @@ class CatalogModifierListParams(typing_extensions.TypedDict): """ - For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. - For example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied - text string to be selected for the T-shirt at the time of sale. - - For non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items - at the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. - For example, a "Condiments" modifier list applicable to a "Hot Dog" item - may contain "Ketchup", "Mustard", and "Relish" modifiers. - - A non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field - is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item - only once and the `selection_type` field is always set to `SINGLE`. + A container for a list of modifiers, or a text-based modifier. + For text-based modifiers, this represents text configuration for an item. (For example, custom text to print on a t-shirt). + For non text-based modifiers, this represents a list of modifiers that can be applied to items at the time of sale. + (For example, a list of condiments for a hot dog, or a list of ice cream flavors). + Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. """ name: typing_extensions.NotRequired[typing.Optional[str]] @@ -41,10 +34,8 @@ class CatalogModifierListParams(typing_extensions.TypedDict): selection_type: typing_extensions.NotRequired[CatalogModifierListSelectionType] """ - Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list - can be applied to a single `CatalogItem`. - - For text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored. + __Deprecated__: Indicates whether a single (`SINGLE`) modifier or multiple (`MULTIPLE`) modifiers can be selected. Use + `min_selected_modifiers` and `max_selected_modifiers` instead. See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values """ @@ -68,6 +59,16 @@ class CatalogModifierListParams(typing_extensions.TypedDict): Currently these images are not displayed on Square products, but may be displayed in 3rd-party applications. """ + allow_quantities: typing_extensions.NotRequired[typing.Optional[bool]] + """ + When `true`, allows multiple quantities of the same modifier to be selected. + """ + + is_conversational: typing_extensions.NotRequired[typing.Optional[bool]] + """ + True if modifiers belonging to this list can be used conversationally. + """ + modifier_type: typing_extensions.NotRequired[CatalogModifierListModifierType] """ The type of the modifier. @@ -100,3 +101,33 @@ class CatalogModifierListParams(typing_extensions.TypedDict): For non text-based modifiers, this `internal_name` attribute can be used to include SKUs, internal codes, or supplemental descriptions for internal use. """ + + min_selected_modifiers: typing_extensions.NotRequired[typing.Optional[int]] + """ + The minimum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`. + + Values: + + - 0: No selection is required. + - -1: Default value, the attribute was not set by the client. Treated as no selection required. + - >0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no selection required. + """ + + max_selected_modifiers: typing_extensions.NotRequired[typing.Optional[int]] + """ + The maximum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`. + + Values: + + - 0: No maximum limit. + - -1: Default value, the attribute was not set by the client. Treated as no maximum limit. + - >0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no maximum limit. + """ + + hidden_from_customer: typing_extensions.NotRequired[typing.Optional[bool]] + """ + If `true`, modifiers from this list are hidden from customer receipts. The default value is `false`. + This setting can be overridden with `CatalogItemModifierListInfo.hidden_from_customer_override`. + """ diff --git a/src/square/requests/catalog_modifier_override.py b/src/square/requests/catalog_modifier_override.py index 168a8c79..70fc8525 100644 --- a/src/square/requests/catalog_modifier_override.py +++ b/src/square/requests/catalog_modifier_override.py @@ -17,5 +17,8 @@ class CatalogModifierOverrideParams(typing_extensions.TypedDict): on_by_default: typing_extensions.NotRequired[typing.Optional[bool]] """ - If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`. + __Deprecated__: Use `on_by_default_override` instead. """ + + hidden_online_override: typing_extensions.NotRequired[typing.Optional[typing.Any]] + on_by_default_override: typing_extensions.NotRequired[typing.Optional[typing.Any]] diff --git a/src/square/requests/create_scheduled_shift_response.py b/src/square/requests/create_scheduled_shift_response.py new file mode 100644 index 00000000..fc8f1f4f --- /dev/null +++ b/src/square/requests/create_scheduled_shift_response.py @@ -0,0 +1,26 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift import ScheduledShiftParams +import typing +from .error import ErrorParams + + +class CreateScheduledShiftResponseParams(typing_extensions.TypedDict): + """ + Represents a [CreateScheduledShift](api-endpoint:Labor-CreateScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing_extensions.NotRequired[ScheduledShiftParams] + """ + The new scheduled shift. To make the shift public, call + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/create_timecard_response.py b/src/square/requests/create_timecard_response.py new file mode 100644 index 00000000..d044a8dd --- /dev/null +++ b/src/square/requests/create_timecard_response.py @@ -0,0 +1,25 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .timecard import TimecardParams +import typing +from .error import ErrorParams + + +class CreateTimecardResponseParams(typing_extensions.TypedDict): + """ + The response to a request to create a `Timecard`. The response contains + the created `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing_extensions.NotRequired[TimecardParams] + """ + The `Timecard` that was created on the request. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/delete_timecard_response.py b/src/square/requests/delete_timecard_response.py new file mode 100644 index 00000000..70f84b1f --- /dev/null +++ b/src/square/requests/delete_timecard_response.py @@ -0,0 +1,18 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .error import ErrorParams + + +class DeleteTimecardResponseParams(typing_extensions.TypedDict): + """ + The response to a request to delete a `Timecard`. The response might contain a set of + `Error` objects if the request resulted in errors. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/publish_scheduled_shift_response.py b/src/square/requests/publish_scheduled_shift_response.py new file mode 100644 index 00000000..f0c40497 --- /dev/null +++ b/src/square/requests/publish_scheduled_shift_response.py @@ -0,0 +1,24 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift import ScheduledShiftParams +import typing +from .error import ErrorParams + + +class PublishScheduledShiftResponseParams(typing_extensions.TypedDict): + """ + Represents a [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing_extensions.NotRequired[ScheduledShiftParams] + """ + The published scheduled shift. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/retrieve_scheduled_shift_response.py b/src/square/requests/retrieve_scheduled_shift_response.py new file mode 100644 index 00000000..55802966 --- /dev/null +++ b/src/square/requests/retrieve_scheduled_shift_response.py @@ -0,0 +1,24 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift import ScheduledShiftParams +import typing +from .error import ErrorParams + + +class RetrieveScheduledShiftResponseParams(typing_extensions.TypedDict): + """ + Represents a [RetrieveScheduledShift](api-endpoint:Labor-RetrieveScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing_extensions.NotRequired[ScheduledShiftParams] + """ + The requested scheduled shift. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/retrieve_timecard_response.py b/src/square/requests/retrieve_timecard_response.py new file mode 100644 index 00000000..c67d22fc --- /dev/null +++ b/src/square/requests/retrieve_timecard_response.py @@ -0,0 +1,25 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .timecard import TimecardParams +import typing +from .error import ErrorParams + + +class RetrieveTimecardResponseParams(typing_extensions.TypedDict): + """ + A response to a request to get a `Timecard`. The response contains + the requested `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing_extensions.NotRequired[TimecardParams] + """ + The requested `Timecard`. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/scheduled_shift.py b/src/square/requests/scheduled_shift.py new file mode 100644 index 00000000..3760247c --- /dev/null +++ b/src/square/requests/scheduled_shift.py @@ -0,0 +1,47 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift_details import ScheduledShiftDetailsParams + + +class ScheduledShiftParams(typing_extensions.TypedDict): + """ + Represents a specific time slot in a work schedule. This object is used to manage the + lifecycle of a scheduled shift from the draft to published state. A scheduled shift contains + the latest draft shift details and current published shift details. + """ + + id: typing_extensions.NotRequired[str] + """ + **Read only** The Square-issued ID of the scheduled shift. + """ + + draft_shift_details: typing_extensions.NotRequired[ScheduledShiftDetailsParams] + """ + The latest draft shift details for the scheduled shift. Draft shift details are used to + stage and manage shifts before publishing. This field is always present. + """ + + published_shift_details: typing_extensions.NotRequired[ScheduledShiftDetailsParams] + """ + The current published (public) shift details for the scheduled shift. This field is + present only if the shift was published. + """ + + version: typing_extensions.NotRequired[int] + """ + **Read only** The current version of the scheduled shift, which is incremented with each update. + This field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control to ensure that requests don't overwrite data from another request. + """ + + created_at: typing_extensions.NotRequired[str] + """ + The timestamp of when the scheduled shift was created, in RFC 3339 format presented as UTC. + """ + + updated_at: typing_extensions.NotRequired[str] + """ + The timestamp of when the scheduled shift was last updated, in RFC 3339 format presented as UTC. + """ diff --git a/src/square/requests/scheduled_shift_details.py b/src/square/requests/scheduled_shift_details.py new file mode 100644 index 00000000..7ad70b97 --- /dev/null +++ b/src/square/requests/scheduled_shift_details.py @@ -0,0 +1,59 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing + + +class ScheduledShiftDetailsParams(typing_extensions.TypedDict): + """ + Represents shift details for draft and published versions of a [scheduled shift](entity:ScheduledShift), + such as job ID, team member assignment, and start and end times. + """ + + team_member_id: typing_extensions.NotRequired[typing.Optional[str]] + """ + The ID of the [team member](entity:TeamMember) scheduled for the shift. + """ + + location_id: typing_extensions.NotRequired[typing.Optional[str]] + """ + The ID of the [location](entity:Location) the shift is scheduled for. + """ + + job_id: typing_extensions.NotRequired[typing.Optional[str]] + """ + The ID of the [job](entity:Job) the shift is scheduled for. + """ + + start_at: typing_extensions.NotRequired[typing.Optional[str]] + """ + The start time of the shift, in RFC 3339 format in the time zone + + offset of the shift location specified in `location_id`. Precision up to the minute + is respected; seconds are truncated. + """ + + end_at: typing_extensions.NotRequired[typing.Optional[str]] + """ + The end time for the shift, in RFC 3339 format in the time zone + + offset of the shift location specified in `location_id`. Precision up to the minute + is respected; seconds are truncated. + """ + + notes: typing_extensions.NotRequired[typing.Optional[str]] + """ + Optional notes for the shift. + """ + + is_deleted: typing_extensions.NotRequired[typing.Optional[bool]] + """ + Indicates whether the draft shift version is deleted. If set to `true` when the shift + is published, the entire scheduled shift (including the published shift) is deleted and + cannot be accessed using any endpoint. + """ + + timezone: typing_extensions.NotRequired[str] + """ + The time zone of the shift location, calculated based on the `location_id`. This field + is provided for convenience. + """ diff --git a/src/square/requests/scheduled_shift_filter.py b/src/square/requests/scheduled_shift_filter.py new file mode 100644 index 00000000..a3d89445 --- /dev/null +++ b/src/square/requests/scheduled_shift_filter.py @@ -0,0 +1,73 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .time_range import TimeRangeParams +from .scheduled_shift_workday import ScheduledShiftWorkdayParams +from ..types.scheduled_shift_filter_assignment_status import ScheduledShiftFilterAssignmentStatus +from ..types.scheduled_shift_filter_scheduled_shift_status import ScheduledShiftFilterScheduledShiftStatus + + +class ScheduledShiftFilterParams(typing_extensions.TypedDict): + """ + Defines filter criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + request. Multiple filters in a query are combined as an `AND` operation. + """ + + location_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] + """ + Return shifts for the specified locations. When omitted, shifts for all + locations are returned. If needed, call [ListLocations](api-endpoint:Locations-ListLocations) + to get location IDs. + """ + + start: typing_extensions.NotRequired[TimeRangeParams] + """ + Return shifts whose `start_at` time is within the specified + time range (inclusive). + """ + + end: typing_extensions.NotRequired[TimeRangeParams] + """ + Return shifts whose `end_at` time is within the specified + time range (inclusive). + """ + + workday: typing_extensions.NotRequired[ScheduledShiftWorkdayParams] + """ + Return shifts based on a workday date range. + """ + + team_member_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] + """ + Return shifts assigned to specified team members. If needed, call + [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get team member IDs. + + To return only the shifts assigned to the specified team members, include the + `assignment_status` filter in the query. Otherwise, all unassigned shifts are + returned along with shifts assigned to the specified team members. + """ + + assignment_status: typing_extensions.NotRequired[ScheduledShiftFilterAssignmentStatus] + """ + Return shifts based on whether a team member is assigned. A shift is + assigned if the `team_member_id` field is populated in the `draft_shift_details` + or `published_shift details` field of the shift. + + To return only draft or published shifts, include the `scheduled_shift_statuses` + filter in the query. + See [ScheduledShiftFilterAssignmentStatus](#type-scheduledshiftfilterassignmentstatus) for possible values + """ + + scheduled_shift_statuses: typing_extensions.NotRequired[ + typing.Optional[typing.Sequence[ScheduledShiftFilterScheduledShiftStatus]] + ] + """ + Return shifts based on the draft or published status of the shift. + A shift is published if the `published_shift_details` field is present. + + Note that shifts with `draft_shift_details.is_deleted` set to `true` are ignored + with the `DRAFT` filter. + See [ScheduledShiftFilterScheduledShiftStatus](#type-scheduledshiftfilterscheduledshiftstatus) for possible values + """ diff --git a/src/square/requests/scheduled_shift_query.py b/src/square/requests/scheduled_shift_query.py new file mode 100644 index 00000000..45a79375 --- /dev/null +++ b/src/square/requests/scheduled_shift_query.py @@ -0,0 +1,23 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift_filter import ScheduledShiftFilterParams +from .scheduled_shift_sort import ScheduledShiftSortParams + + +class ScheduledShiftQueryParams(typing_extensions.TypedDict): + """ + Represents filter and sort criteria for the `query` field in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + """ + + filter: typing_extensions.NotRequired[ScheduledShiftFilterParams] + """ + Filtering options for the query. + """ + + sort: typing_extensions.NotRequired[ScheduledShiftSortParams] + """ + Sorting options for the query. + """ diff --git a/src/square/requests/scheduled_shift_sort.py b/src/square/requests/scheduled_shift_sort.py new file mode 100644 index 00000000..0f8df45b --- /dev/null +++ b/src/square/requests/scheduled_shift_sort.py @@ -0,0 +1,25 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from ..types.scheduled_shift_sort_field import ScheduledShiftSortField +from ..types.sort_order import SortOrder + + +class ScheduledShiftSortParams(typing_extensions.TypedDict): + """ + Defines sort criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + request. + """ + + field: typing_extensions.NotRequired[ScheduledShiftSortField] + """ + The field to sort on. The default value is `START_AT`. + See [ScheduledShiftSortField](#type-scheduledshiftsortfield) for possible values + """ + + order: typing_extensions.NotRequired[SortOrder] + """ + The order in which results are returned. The default value is `ASC`. + See [SortOrder](#type-sortorder) for possible values + """ diff --git a/src/square/requests/scheduled_shift_workday.py b/src/square/requests/scheduled_shift_workday.py new file mode 100644 index 00000000..720473f2 --- /dev/null +++ b/src/square/requests/scheduled_shift_workday.py @@ -0,0 +1,33 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .date_range import DateRangeParams +from ..types.scheduled_shift_workday_matcher import ScheduledShiftWorkdayMatcher +import typing + + +class ScheduledShiftWorkdayParams(typing_extensions.TypedDict): + """ + A `ScheduledShift` search query filter parameter that sets a range of days that + a `Shift` must start or end in before passing the filter condition. + """ + + date_range: typing_extensions.NotRequired[DateRangeParams] + """ + Dates for fetching the scheduled shifts. + """ + + match_scheduled_shifts_by: typing_extensions.NotRequired[ScheduledShiftWorkdayMatcher] + """ + The strategy on which the dates are applied. + See [ScheduledShiftWorkdayMatcher](#type-scheduledshiftworkdaymatcher) for possible values + """ + + default_timezone: typing_extensions.NotRequired[typing.Optional[str]] + """ + Location-specific timezones convert workdays to datetime filters. + Every location included in the query must have a timezone or this field + must be provided as a fallback. Format: the IANA timezone database + identifier for the relevant timezone. + """ diff --git a/src/square/requests/search_scheduled_shifts_response.py b/src/square/requests/search_scheduled_shifts_response.py new file mode 100644 index 00000000..9e39b534 --- /dev/null +++ b/src/square/requests/search_scheduled_shifts_response.py @@ -0,0 +1,30 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .scheduled_shift import ScheduledShiftParams +from .error import ErrorParams + + +class SearchScheduledShiftsResponseParams(typing_extensions.TypedDict): + """ + Represents a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) response. + Either `scheduled_shifts` or `errors` is present in the response. + """ + + scheduled_shifts: typing_extensions.NotRequired[typing.Sequence[ScheduledShiftParams]] + """ + A paginated list of scheduled shifts that match the query conditions. + """ + + cursor: typing_extensions.NotRequired[str] + """ + The pagination cursor used to retrieve the next page of results. This field is present + only if additional results are available. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/search_timecards_response.py b/src/square/requests/search_timecards_response.py new file mode 100644 index 00000000..aaba9b36 --- /dev/null +++ b/src/square/requests/search_timecards_response.py @@ -0,0 +1,30 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .timecard import TimecardParams +from .error import ErrorParams + + +class SearchTimecardsResponseParams(typing_extensions.TypedDict): + """ + The response to a request for `Timecard` objects. The response contains + the requested `Timecard` objects and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecards: typing_extensions.NotRequired[typing.Sequence[TimecardParams]] + """ + Timecards. + """ + + cursor: typing_extensions.NotRequired[str] + """ + An opaque cursor for fetching the next page. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/shift.py b/src/square/requests/shift.py index c8f0dea5..5001354c 100644 --- a/src/square/requests/shift.py +++ b/src/square/requests/shift.py @@ -14,6 +14,9 @@ class ShiftParams(typing_extensions.TypedDict): A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift. + + Deprecated at Square API version 2025-05-21. Replaced by [Timecard](entity:Timecard). + See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ id: typing_extensions.NotRequired[str] diff --git a/src/square/requests/shift_filter.py b/src/square/requests/shift_filter.py index 89effaab..d6839b8d 100644 --- a/src/square/requests/shift_filter.py +++ b/src/square/requests/shift_filter.py @@ -12,6 +12,8 @@ class ShiftFilterParams(typing_extensions.TypedDict): """ Defines a filter used in a search for `Shift` records. `AND` logic is used by Square's servers to apply each filter property specified. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ location_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] diff --git a/src/square/requests/shift_query.py b/src/square/requests/shift_query.py index 7d35a903..b008241d 100644 --- a/src/square/requests/shift_query.py +++ b/src/square/requests/shift_query.py @@ -9,6 +9,8 @@ class ShiftQueryParams(typing_extensions.TypedDict): """ The parameters of a `Shift` search query, which includes filter and sort options. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ filter: typing_extensions.NotRequired[ShiftFilterParams] diff --git a/src/square/requests/shift_sort.py b/src/square/requests/shift_sort.py index fecd99c0..aaba9888 100644 --- a/src/square/requests/shift_sort.py +++ b/src/square/requests/shift_sort.py @@ -9,6 +9,8 @@ class ShiftSortParams(typing_extensions.TypedDict): """ Sets the sort order of search results. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ field: typing_extensions.NotRequired[ShiftSortField] diff --git a/src/square/requests/shift_wage.py b/src/square/requests/shift_wage.py index 0aaf7feb..90949121 100644 --- a/src/square/requests/shift_wage.py +++ b/src/square/requests/shift_wage.py @@ -9,6 +9,8 @@ class ShiftWageParams(typing_extensions.TypedDict): """ The hourly wage rate used to compensate an employee for this shift. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ title: typing_extensions.NotRequired[typing.Optional[str]] @@ -25,7 +27,7 @@ class ShiftWageParams(typing_extensions.TypedDict): job_id: typing_extensions.NotRequired[str] """ The id of the job performed during this shift. Square - labor-reporting UIs might group shifts together by id. This cannot be used to retrieve the job. + labor-reporting UIs might group shifts together by id. """ tip_eligible: typing_extensions.NotRequired[typing.Optional[bool]] diff --git a/src/square/requests/shift_workday.py b/src/square/requests/shift_workday.py index bda678d3..e52fae32 100644 --- a/src/square/requests/shift_workday.py +++ b/src/square/requests/shift_workday.py @@ -11,6 +11,8 @@ class ShiftWorkdayParams(typing_extensions.TypedDict): """ A `Shift` search query filter parameter that sets a range of days that a `Shift` must start or end in before passing the filter condition. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ date_range: typing_extensions.NotRequired[DateRangeParams] diff --git a/src/square/requests/team_member_wage.py b/src/square/requests/team_member_wage.py index a088bf14..72a1a796 100644 --- a/src/square/requests/team_member_wage.py +++ b/src/square/requests/team_member_wage.py @@ -8,8 +8,9 @@ class TeamMemberWageParams(typing_extensions.TypedDict): """ - The hourly wage rate that a team member earns on a `Shift` for doing the job - specified by the `title` property of this object. + Job and wage information for a [team member](entity:TeamMember). + This convenience object provides details needed to specify the `wage` + field for a [timecard](entity:Timecard). """ id: typing_extensions.NotRequired[str] @@ -35,8 +36,7 @@ class TeamMemberWageParams(typing_extensions.TypedDict): job_id: typing_extensions.NotRequired[typing.Optional[str]] """ - An identifier for the job that this wage relates to. This cannot be - used to retrieve the job. + An identifier for the [job](entity:Job) that this wage relates to. """ tip_eligible: typing_extensions.NotRequired[typing.Optional[bool]] diff --git a/src/square/requests/timecard.py b/src/square/requests/timecard.py new file mode 100644 index 00000000..b128f6a6 --- /dev/null +++ b/src/square/requests/timecard.py @@ -0,0 +1,92 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .timecard_wage import TimecardWageParams +from .break_ import BreakParams +from ..types.timecard_status import TimecardStatus +from .money import MoneyParams + + +class TimecardParams(typing_extensions.TypedDict): + """ + A record of the hourly rate, start time, and end time of a single timecard (shift) + for a team member. This might include a record of the start and end times of breaks + taken during the shift. + """ + + id: typing_extensions.NotRequired[str] + """ + **Read only** The Square-issued UUID for this object. + """ + + location_id: str + """ + The ID of the [location](entity:Location) for this timecard. The location should be based on + where the team member clocked in. + """ + + timezone: typing_extensions.NotRequired[typing.Optional[str]] + """ + **Read only** The time zone calculated from the location based on the `location_id`, + provided as a convenience value. Format: the IANA time zone database identifier for the + location time zone. + """ + + start_at: str + """ + The start time of the timecard, in RFC 3339 format and shifted to the location + timezone + offset. Precision up to the minute is respected; seconds are truncated. + """ + + end_at: typing_extensions.NotRequired[typing.Optional[str]] + """ + The end time of the timecard, in RFC 3339 format and shifted to the location + timezone + offset. Precision up to the minute is respected; seconds are truncated. + """ + + wage: typing_extensions.NotRequired[TimecardWageParams] + """ + Job and pay related information. If the wage is not set on create, it defaults to a wage + of zero. If the title is not set on create, it defaults to the name of the role the team member + is assigned to, if any. + """ + + breaks: typing_extensions.NotRequired[typing.Optional[typing.Sequence[BreakParams]]] + """ + A list of all the paid or unpaid breaks that were taken during this timecard. + """ + + status: typing_extensions.NotRequired[TimecardStatus] + """ + Describes the working state of the timecard. + See [TimecardStatus](#type-timecardstatus) for possible values + """ + + version: typing_extensions.NotRequired[int] + """ + **Read only** The current version of the timecard, which is incremented with each update. + This field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control to ensure that requests don't overwrite data from another request. + """ + + created_at: typing_extensions.NotRequired[str] + """ + The timestamp of when the timecard was created, in RFC 3339 format presented as UTC. + """ + + updated_at: typing_extensions.NotRequired[str] + """ + The timestamp of when the timecard was last updated, in RFC 3339 format presented as UTC. + """ + + team_member_id: str + """ + The ID of the [team member](entity:TeamMember) this timecard belongs to. + """ + + declared_cash_tip_money: typing_extensions.NotRequired[MoneyParams] + """ + The cash tips declared by the team member for this timecard. + """ diff --git a/src/square/requests/timecard_filter.py b/src/square/requests/timecard_filter.py new file mode 100644 index 00000000..833a5f74 --- /dev/null +++ b/src/square/requests/timecard_filter.py @@ -0,0 +1,46 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from ..types.timecard_filter_status import TimecardFilterStatus +from .time_range import TimeRangeParams +from .timecard_workday import TimecardWorkdayParams + + +class TimecardFilterParams(typing_extensions.TypedDict): + """ + Defines a filter used in a search for `Timecard` records. `AND` logic is + used by Square's servers to apply each filter property specified. + """ + + location_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] + """ + Fetch timecards for the specified location. + """ + + status: typing_extensions.NotRequired[TimecardFilterStatus] + """ + Fetch a `Timecard` instance by `Timecard.status`. + See [TimecardFilterStatus](#type-timecardfilterstatus) for possible values + """ + + start: typing_extensions.NotRequired[TimeRangeParams] + """ + Fetch `Timecard` instances that start in the time range - Inclusive. + """ + + end: typing_extensions.NotRequired[TimeRangeParams] + """ + Fetch the `Timecard` instances that end in the time range - Inclusive. + """ + + workday: typing_extensions.NotRequired[TimecardWorkdayParams] + """ + Fetch the `Timecard` instances based on the workday date range. + """ + + team_member_ids: typing_extensions.NotRequired[typing.Optional[typing.Sequence[str]]] + """ + Fetch timecards for the specified team members. + """ diff --git a/src/square/requests/timecard_query.py b/src/square/requests/timecard_query.py new file mode 100644 index 00000000..b7fd7dd6 --- /dev/null +++ b/src/square/requests/timecard_query.py @@ -0,0 +1,22 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .timecard_filter import TimecardFilterParams +from .timecard_sort import TimecardSortParams + + +class TimecardQueryParams(typing_extensions.TypedDict): + """ + The parameters of a `Timecard` search query, which includes filter and sort options. + """ + + filter: typing_extensions.NotRequired[TimecardFilterParams] + """ + Query filter options. + """ + + sort: typing_extensions.NotRequired[TimecardSortParams] + """ + Sort order details. + """ diff --git a/src/square/requests/timecard_sort.py b/src/square/requests/timecard_sort.py new file mode 100644 index 00000000..d2702590 --- /dev/null +++ b/src/square/requests/timecard_sort.py @@ -0,0 +1,24 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from ..types.timecard_sort_field import TimecardSortField +from ..types.sort_order import SortOrder + + +class TimecardSortParams(typing_extensions.TypedDict): + """ + Sets the sort order of search results. + """ + + field: typing_extensions.NotRequired[TimecardSortField] + """ + The field to sort on. + See [TimecardSortField](#type-timecardsortfield) for possible values + """ + + order: typing_extensions.NotRequired[SortOrder] + """ + The order in which results are returned. Defaults to DESC. + See [SortOrder](#type-sortorder) for possible values + """ diff --git a/src/square/requests/timecard_wage.py b/src/square/requests/timecard_wage.py new file mode 100644 index 00000000..c7d1bee3 --- /dev/null +++ b/src/square/requests/timecard_wage.py @@ -0,0 +1,34 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +import typing +from .money import MoneyParams + + +class TimecardWageParams(typing_extensions.TypedDict): + """ + The hourly wage rate used to compensate a team member for a [timecard](entity:Timecard). + """ + + title: typing_extensions.NotRequired[typing.Optional[str]] + """ + The name of the job performed during this timecard. + """ + + hourly_rate: typing_extensions.NotRequired[MoneyParams] + """ + Can be a custom-set hourly wage or the calculated effective hourly + wage based on the annual wage and hours worked per week. + """ + + job_id: typing_extensions.NotRequired[str] + """ + The ID of the [job](entity:Job) performed for this timecard. Square + labor-reporting UIs might group timecards together by ID. + """ + + tip_eligible: typing_extensions.NotRequired[typing.Optional[bool]] + """ + Whether team members are eligible for tips when working this job. + """ diff --git a/src/square/requests/timecard_workday.py b/src/square/requests/timecard_workday.py new file mode 100644 index 00000000..c3f710a1 --- /dev/null +++ b/src/square/requests/timecard_workday.py @@ -0,0 +1,33 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .date_range import DateRangeParams +from ..types.timecard_workday_matcher import TimecardWorkdayMatcher +import typing + + +class TimecardWorkdayParams(typing_extensions.TypedDict): + """ + A `Timecard` search query filter parameter that sets a range of days that + a `Timecard` must start or end in before passing the filter condition. + """ + + date_range: typing_extensions.NotRequired[DateRangeParams] + """ + Dates for fetching the timecards. + """ + + match_timecards_by: typing_extensions.NotRequired[TimecardWorkdayMatcher] + """ + The strategy on which the dates are applied. + See [TimecardWorkdayMatcher](#type-timecardworkdaymatcher) for possible values + """ + + default_timezone: typing_extensions.NotRequired[typing.Optional[str]] + """ + Location-specific timezones convert workdays to datetime filters. + Every location included in the query must have a timezone or this field + must be provided as a fallback. Format: the IANA timezone database + identifier for the relevant timezone. + """ diff --git a/src/square/requests/update_scheduled_shift_response.py b/src/square/requests/update_scheduled_shift_response.py new file mode 100644 index 00000000..fcc21e63 --- /dev/null +++ b/src/square/requests/update_scheduled_shift_response.py @@ -0,0 +1,26 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .scheduled_shift import ScheduledShiftParams +import typing +from .error import ErrorParams + + +class UpdateScheduledShiftResponseParams(typing_extensions.TypedDict): + """ + Represents an [UpdateScheduledShift](api-endpoint:Labor-UpdateScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing_extensions.NotRequired[ScheduledShiftParams] + """ + The updated scheduled shift. To make the changes public, call + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/requests/update_timecard_response.py b/src/square/requests/update_timecard_response.py new file mode 100644 index 00000000..ead80da7 --- /dev/null +++ b/src/square/requests/update_timecard_response.py @@ -0,0 +1,25 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing_extensions +import typing_extensions +from .timecard import TimecardParams +import typing +from .error import ErrorParams + + +class UpdateTimecardResponseParams(typing_extensions.TypedDict): + """ + The response to a request to update a `Timecard`. The response contains + the updated `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing_extensions.NotRequired[TimecardParams] + """ + The updated `Timecard`. + """ + + errors: typing_extensions.NotRequired[typing.Sequence[ErrorParams]] + """ + Any errors that occurred during the request. + """ diff --git a/src/square/types/break_.py b/src/square/types/break_.py index 3dca5691..069c59bd 100644 --- a/src/square/types/break_.py +++ b/src/square/types/break_.py @@ -8,7 +8,7 @@ class Break(UncheckedBaseModel): """ - A record of an employee's break during a shift. + A record of a team member's break on a [timecard](entity:Timecard). """ id: typing.Optional[str] = pydantic.Field(default=None) @@ -18,19 +18,19 @@ class Break(UncheckedBaseModel): start_at: str = pydantic.Field() """ - RFC 3339; follows the same timezone information as `Shift`. Precision up to + RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. """ end_at: typing.Optional[str] = pydantic.Field(default=None) """ - RFC 3339; follows the same timezone information as `Shift`. Precision up to + RFC 3339; follows the same timezone information as the [timecard](entity:Timecard). Precision up to the minute is respected; seconds are truncated. """ break_type_id: str = pydantic.Field() """ - The `BreakType` that this `Break` was templated on. + The [BreakType](entity:BreakType) that this break was templated on. """ name: str = pydantic.Field() @@ -42,6 +42,8 @@ class Break(UncheckedBaseModel): """ Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of the break. + + Example for break expected duration of 15 minutes: PT15M """ is_paid: bool = pydantic.Field() diff --git a/src/square/types/break_type.py b/src/square/types/break_type.py index ef2033d4..2678da22 100644 --- a/src/square/types/break_type.py +++ b/src/square/types/break_type.py @@ -8,8 +8,8 @@ class BreakType(UncheckedBaseModel): """ - A defined break template that sets an expectation for possible `Break` - instances on a `Shift`. + A template for a type of [break](entity:Break) that can be added to a + [timecard](entity:Timecard), including the expected duration and paid status. """ id: typing.Optional[str] = pydantic.Field(default=None) @@ -25,7 +25,7 @@ class BreakType(UncheckedBaseModel): break_name: str = pydantic.Field() """ A human-readable name for this type of break. The name is displayed to - employees in Square products. + team members in Square products. """ expected_duration: str = pydantic.Field() @@ -33,7 +33,7 @@ class BreakType(UncheckedBaseModel): Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of this break. Precision less than minutes is truncated. - Example for break expected duration of 15 minutes: T15M + Example for break expected duration of 15 minutes: PT15M """ is_paid: bool = pydantic.Field() diff --git a/src/square/types/bulk_publish_scheduled_shifts_data.py b/src/square/types/bulk_publish_scheduled_shifts_data.py new file mode 100644 index 00000000..c2d5a27d --- /dev/null +++ b/src/square/types/bulk_publish_scheduled_shifts_data.py @@ -0,0 +1,30 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class BulkPublishScheduledShiftsData(UncheckedBaseModel): + """ + Represents options for an individual publish request in a + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) + operation, provided as the value in a key-value pair. + """ + + version: typing.Optional[int] = pydantic.Field(default=None) + """ + The current version of the scheduled shift, used to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control. If the provided version doesn't match the server version, the request fails. + If omitted, Square executes a blind write, potentially overwriting data from another publish request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/bulk_publish_scheduled_shifts_response.py b/src/square/types/bulk_publish_scheduled_shifts_response.py new file mode 100644 index 00000000..0cead3cb --- /dev/null +++ b/src/square/types/bulk_publish_scheduled_shifts_response.py @@ -0,0 +1,40 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .publish_scheduled_shift_response import PublishScheduledShiftResponse +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class BulkPublishScheduledShiftsResponse(UncheckedBaseModel): + """ + Represents a [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts) response. + Either `scheduled_shifts` or `errors` is present in the response. + """ + + responses: typing.Optional[typing.Dict[str, PublishScheduledShiftResponse]] = pydantic.Field(default=None) + """ + A map of key-value pairs that represent responses for individual publish requests. + The order of responses might differ from the order in which the requests were provided. + + - Each key is the scheduled shift ID that was specified for a publish request. + - Each value is the corresponding response. If the request succeeds, the value is the + published scheduled shift. If the request fails, the value is an `errors` array containing + any errors that occurred while processing the request. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any top-level errors that prevented the bulk operation from succeeding. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/catalog_item.py b/src/square/types/catalog_item.py index e46c06ce..0d3a66cc 100644 --- a/src/square/types/catalog_item.py +++ b/src/square/types/catalog_item.py @@ -109,12 +109,12 @@ class CatalogItem(UncheckedBaseModel): ecom_uri: typing.Optional[str] = pydantic.Field(default=None) """ - Deprecated; see go/ecomUriUseCases. A URI pointing to a published e-commerce product page for the Item. + Deprecated. A URI pointing to a published e-commerce product page for the Item. """ ecom_image_uris: typing.Optional[typing.List[str]] = pydantic.Field(default=None) """ - Deprecated; see go/ecomUriUseCases. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item. + Deprecated. A comma-separated list of encoded URIs pointing to a set of published e-commerce images for the Item. """ image_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) diff --git a/src/square/types/catalog_item_modifier_list_info.py b/src/square/types/catalog_item_modifier_list_info.py index 6120c518..ea039797 100644 --- a/src/square/types/catalog_item_modifier_list_info.py +++ b/src/square/types/catalog_item_modifier_list_info.py @@ -9,8 +9,8 @@ class CatalogItemModifierListInfo(UncheckedBaseModel): """ - References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance - and specifies supported behaviors of the application. + Controls how a modifier list is applied to a specific item. This object allows for item-specific customization of modifier list behavior + and provides the ability to override global modifier list settings. """ modifier_list_id: str = pydantic.Field() @@ -20,35 +20,31 @@ class CatalogItemModifierListInfo(UncheckedBaseModel): modifier_overrides: typing.Optional[typing.List[CatalogModifierOverride]] = pydantic.Field(default=None) """ - A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default. + A set of `CatalogModifierOverride` objects that override default modifier settings for this item. """ min_selected_modifiers: typing.Optional[int] = pydantic.Field(default=None) """ - If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`. - The default value is `-1`. + The minimum number of modifiers that must be selected from this modifier list. + Values: - When `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of - the `CatalogModifierList` can be selected from the `CatalogModifierList`. - - When the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in - and can be selected from the `CatalogModifierList` + - 0: No selection is required. + - -1: Default value, the attribute was not set by the client. When `max_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`. + - >0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no selection required. """ max_selected_modifiers: typing.Optional[int] = pydantic.Field(default=None) """ - If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`. - The default value is `-1`. - - When `CatalogModifierList.selection_type` is `MULTIPLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that from zero to the maximum number of modifiers of - the `CatalogModifierList` can be selected from the `CatalogModifierList`. + The maximum number of modifiers that can be selected. + Values: - When the `CatalogModifierList.selection_type` is `SINGLE`, `CatalogModifierListInfo.min_selected_modifiers=-1` - and `CatalogModifierListInfo.max_selected_modifier=-1` means that exactly one modifier must be present in - and can be selected from the `CatalogModifierList` + - 0: No maximum limit. + - -1: Default value, the attribute was not set by the client. When `min_selected_modifiers` is + also -1, use the minimum and maximum selection values set on the `CatalogItemModifierList`. + - >0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no maximum limit. """ enabled: typing.Optional[bool] = pydantic.Field(default=None) @@ -62,6 +58,10 @@ class CatalogItemModifierListInfo(UncheckedBaseModel): to a `CatalogItem` instance. """ + allow_quantities: typing.Optional[typing.Optional[typing.Any]] = None + is_conversational: typing.Optional[typing.Optional[typing.Any]] = None + hidden_from_customer_override: typing.Optional[typing.Optional[typing.Any]] = None + if IS_PYDANTIC_V2: model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 else: diff --git a/src/square/types/catalog_modifier.py b/src/square/types/catalog_modifier.py index e43e6fb4..692abcc7 100644 --- a/src/square/types/catalog_modifier.py +++ b/src/square/types/catalog_modifier.py @@ -10,7 +10,7 @@ class CatalogModifier(UncheckedBaseModel): """ - A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item. + A modifier that can be applied to items at the time of sale. For example, a cheese modifier for a burger, or a flavor modifier for a serving of ice cream. """ name: typing.Optional[str] = pydantic.Field(default=None) @@ -23,6 +23,12 @@ class CatalogModifier(UncheckedBaseModel): The modifier price. """ + on_by_default: typing.Optional[bool] = pydantic.Field(default=None) + """ + When `true`, this modifier is selected by default when displaying the modifier list. + This setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`. + """ + ordinal: typing.Optional[int] = pydantic.Field(default=None) """ Determines where this `CatalogModifier` appears in the `CatalogModifierList`. @@ -44,6 +50,11 @@ class CatalogModifier(UncheckedBaseModel): Currently this image is not displayed by Square, but is free to be displayed in 3rd party applications. """ + hidden_online: typing.Optional[bool] = pydantic.Field(default=None) + """ + When `true`, this modifier is hidden from online ordering channels. This setting can be overridden at the item level using `CatalogModifierListInfo.modifier_overrides`. + """ + if IS_PYDANTIC_V2: model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 else: diff --git a/src/square/types/catalog_modifier_list.py b/src/square/types/catalog_modifier_list.py index cd9bfc1c..1ad14452 100644 --- a/src/square/types/catalog_modifier_list.py +++ b/src/square/types/catalog_modifier_list.py @@ -14,18 +14,11 @@ class CatalogModifierList(UncheckedBaseModel): """ - For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. - For example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied - text string to be selected for the T-shirt at the time of sale. - - For non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items - at the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. - For example, a "Condiments" modifier list applicable to a "Hot Dog" item - may contain "Ketchup", "Mustard", and "Relish" modifiers. - - A non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field - is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item - only once and the `selection_type` field is always set to `SINGLE`. + A container for a list of modifiers, or a text-based modifier. + For text-based modifiers, this represents text configuration for an item. (For example, custom text to print on a t-shirt). + For non text-based modifiers, this represents a list of modifiers that can be applied to items at the time of sale. + (For example, a list of condiments for a hot dog, or a list of ice cream flavors). + Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. """ name: typing.Optional[str] = pydantic.Field(default=None) @@ -41,10 +34,8 @@ class CatalogModifierList(UncheckedBaseModel): selection_type: typing.Optional[CatalogModifierListSelectionType] = pydantic.Field(default=None) """ - Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`) modifiers from the list - can be applied to a single `CatalogItem`. - - For text-based modifiers, the `selection_type` attribute is always `SINGLE`. The other value is ignored. + __Deprecated__: Indicates whether a single (`SINGLE`) modifier or multiple (`MULTIPLE`) modifiers can be selected. Use + `min_selected_modifiers` and `max_selected_modifiers` instead. See [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype) for possible values """ @@ -68,6 +59,16 @@ class CatalogModifierList(UncheckedBaseModel): Currently these images are not displayed on Square products, but may be displayed in 3rd-party applications. """ + allow_quantities: typing.Optional[bool] = pydantic.Field(default=None) + """ + When `true`, allows multiple quantities of the same modifier to be selected. + """ + + is_conversational: typing.Optional[bool] = pydantic.Field(default=None) + """ + True if modifiers belonging to this list can be used conversationally. + """ + modifier_type: typing.Optional[CatalogModifierListModifierType] = pydantic.Field(default=None) """ The type of the modifier. @@ -101,6 +102,36 @@ class CatalogModifierList(UncheckedBaseModel): used to include SKUs, internal codes, or supplemental descriptions for internal use. """ + min_selected_modifiers: typing.Optional[int] = pydantic.Field(default=None) + """ + The minimum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`. + + Values: + + - 0: No selection is required. + - -1: Default value, the attribute was not set by the client. Treated as no selection required. + - >0: The required minimum modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no selection required. + """ + + max_selected_modifiers: typing.Optional[int] = pydantic.Field(default=None) + """ + The maximum number of modifiers that must be selected from this list. The value can be overridden with `CatalogItemModifierListInfo`. + + Values: + + - 0: No maximum limit. + - -1: Default value, the attribute was not set by the client. Treated as no maximum limit. + - >0: The maximum total modifier selections. This can be larger than the total `CatalogModifiers` when `allow_quantities` is enabled. + - < -1: Invalid. Treated as no maximum limit. + """ + + hidden_from_customer: typing.Optional[bool] = pydantic.Field(default=None) + """ + If `true`, modifiers from this list are hidden from customer receipts. The default value is `false`. + This setting can be overridden with `CatalogItemModifierListInfo.hidden_from_customer_override`. + """ + if IS_PYDANTIC_V2: model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 else: diff --git a/src/square/types/catalog_modifier_override.py b/src/square/types/catalog_modifier_override.py index 43bdba1e..c45f0601 100644 --- a/src/square/types/catalog_modifier_override.py +++ b/src/square/types/catalog_modifier_override.py @@ -18,9 +18,12 @@ class CatalogModifierOverride(UncheckedBaseModel): on_by_default: typing.Optional[bool] = pydantic.Field(default=None) """ - If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`. + __Deprecated__: Use `on_by_default_override` instead. """ + hidden_online_override: typing.Optional[typing.Optional[typing.Any]] = None + on_by_default_override: typing.Optional[typing.Optional[typing.Any]] = None + if IS_PYDANTIC_V2: model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 else: diff --git a/src/square/types/create_scheduled_shift_response.py b/src/square/types/create_scheduled_shift_response.py new file mode 100644 index 00000000..ade68fe5 --- /dev/null +++ b/src/square/types/create_scheduled_shift_response.py @@ -0,0 +1,36 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift import ScheduledShift +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class CreateScheduledShiftResponse(UncheckedBaseModel): + """ + Represents a [CreateScheduledShift](api-endpoint:Labor-CreateScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing.Optional[ScheduledShift] = pydantic.Field(default=None) + """ + The new scheduled shift. To make the shift public, call + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/create_timecard_response.py b/src/square/types/create_timecard_response.py new file mode 100644 index 00000000..f7b2fb9a --- /dev/null +++ b/src/square/types/create_timecard_response.py @@ -0,0 +1,35 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard import Timecard +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class CreateTimecardResponse(UncheckedBaseModel): + """ + The response to a request to create a `Timecard`. The response contains + the created `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing.Optional[Timecard] = pydantic.Field(default=None) + """ + The `Timecard` that was created on the request. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/delete_timecard_response.py b/src/square/types/delete_timecard_response.py new file mode 100644 index 00000000..9cc10b30 --- /dev/null +++ b/src/square/types/delete_timecard_response.py @@ -0,0 +1,28 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .error import Error +import pydantic +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class DeleteTimecardResponse(UncheckedBaseModel): + """ + The response to a request to delete a `Timecard`. The response might contain a set of + `Error` objects if the request resulted in errors. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/publish_scheduled_shift_response.py b/src/square/types/publish_scheduled_shift_response.py new file mode 100644 index 00000000..01dfdd04 --- /dev/null +++ b/src/square/types/publish_scheduled_shift_response.py @@ -0,0 +1,34 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift import ScheduledShift +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class PublishScheduledShiftResponse(UncheckedBaseModel): + """ + Represents a [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing.Optional[ScheduledShift] = pydantic.Field(default=None) + """ + The published scheduled shift. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/retrieve_scheduled_shift_response.py b/src/square/types/retrieve_scheduled_shift_response.py new file mode 100644 index 00000000..af04b22d --- /dev/null +++ b/src/square/types/retrieve_scheduled_shift_response.py @@ -0,0 +1,34 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift import ScheduledShift +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class RetrieveScheduledShiftResponse(UncheckedBaseModel): + """ + Represents a [RetrieveScheduledShift](api-endpoint:Labor-RetrieveScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing.Optional[ScheduledShift] = pydantic.Field(default=None) + """ + The requested scheduled shift. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/retrieve_timecard_response.py b/src/square/types/retrieve_timecard_response.py new file mode 100644 index 00000000..f9491bf7 --- /dev/null +++ b/src/square/types/retrieve_timecard_response.py @@ -0,0 +1,35 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard import Timecard +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class RetrieveTimecardResponse(UncheckedBaseModel): + """ + A response to a request to get a `Timecard`. The response contains + the requested `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing.Optional[Timecard] = pydantic.Field(default=None) + """ + The requested `Timecard`. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift.py b/src/square/types/scheduled_shift.py new file mode 100644 index 00000000..f5df0727 --- /dev/null +++ b/src/square/types/scheduled_shift.py @@ -0,0 +1,58 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from .scheduled_shift_details import ScheduledShiftDetails +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShift(UncheckedBaseModel): + """ + Represents a specific time slot in a work schedule. This object is used to manage the + lifecycle of a scheduled shift from the draft to published state. A scheduled shift contains + the latest draft shift details and current published shift details. + """ + + id: typing.Optional[str] = pydantic.Field(default=None) + """ + **Read only** The Square-issued ID of the scheduled shift. + """ + + draft_shift_details: typing.Optional[ScheduledShiftDetails] = pydantic.Field(default=None) + """ + The latest draft shift details for the scheduled shift. Draft shift details are used to + stage and manage shifts before publishing. This field is always present. + """ + + published_shift_details: typing.Optional[ScheduledShiftDetails] = pydantic.Field(default=None) + """ + The current published (public) shift details for the scheduled shift. This field is + present only if the shift was published. + """ + + version: typing.Optional[int] = pydantic.Field(default=None) + """ + **Read only** The current version of the scheduled shift, which is incremented with each update. + This field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control to ensure that requests don't overwrite data from another request. + """ + + created_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The timestamp of when the scheduled shift was created, in RFC 3339 format presented as UTC. + """ + + updated_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The timestamp of when the scheduled shift was last updated, in RFC 3339 format presented as UTC. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_details.py b/src/square/types/scheduled_shift_details.py new file mode 100644 index 00000000..24d19b63 --- /dev/null +++ b/src/square/types/scheduled_shift_details.py @@ -0,0 +1,69 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShiftDetails(UncheckedBaseModel): + """ + Represents shift details for draft and published versions of a [scheduled shift](entity:ScheduledShift), + such as job ID, team member assignment, and start and end times. + """ + + team_member_id: typing.Optional[str] = pydantic.Field(default=None) + """ + The ID of the [team member](entity:TeamMember) scheduled for the shift. + """ + + location_id: typing.Optional[str] = pydantic.Field(default=None) + """ + The ID of the [location](entity:Location) the shift is scheduled for. + """ + + job_id: typing.Optional[str] = pydantic.Field(default=None) + """ + The ID of the [job](entity:Job) the shift is scheduled for. + """ + + start_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The start time of the shift, in RFC 3339 format in the time zone + + offset of the shift location specified in `location_id`. Precision up to the minute + is respected; seconds are truncated. + """ + + end_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The end time for the shift, in RFC 3339 format in the time zone + + offset of the shift location specified in `location_id`. Precision up to the minute + is respected; seconds are truncated. + """ + + notes: typing.Optional[str] = pydantic.Field(default=None) + """ + Optional notes for the shift. + """ + + is_deleted: typing.Optional[bool] = pydantic.Field(default=None) + """ + Indicates whether the draft shift version is deleted. If set to `true` when the shift + is published, the entire scheduled shift (including the published shift) is deleted and + cannot be accessed using any endpoint. + """ + + timezone: typing.Optional[str] = pydantic.Field(default=None) + """ + The time zone of the shift location, calculated based on the `location_id`. This field + is provided for convenience. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_filter.py b/src/square/types/scheduled_shift_filter.py new file mode 100644 index 00000000..f1319355 --- /dev/null +++ b/src/square/types/scheduled_shift_filter.py @@ -0,0 +1,83 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from .time_range import TimeRange +from .scheduled_shift_workday import ScheduledShiftWorkday +from .scheduled_shift_filter_assignment_status import ScheduledShiftFilterAssignmentStatus +from .scheduled_shift_filter_scheduled_shift_status import ScheduledShiftFilterScheduledShiftStatus +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShiftFilter(UncheckedBaseModel): + """ + Defines filter criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + request. Multiple filters in a query are combined as an `AND` operation. + """ + + location_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) + """ + Return shifts for the specified locations. When omitted, shifts for all + locations are returned. If needed, call [ListLocations](api-endpoint:Locations-ListLocations) + to get location IDs. + """ + + start: typing.Optional[TimeRange] = pydantic.Field(default=None) + """ + Return shifts whose `start_at` time is within the specified + time range (inclusive). + """ + + end: typing.Optional[TimeRange] = pydantic.Field(default=None) + """ + Return shifts whose `end_at` time is within the specified + time range (inclusive). + """ + + workday: typing.Optional[ScheduledShiftWorkday] = pydantic.Field(default=None) + """ + Return shifts based on a workday date range. + """ + + team_member_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) + """ + Return shifts assigned to specified team members. If needed, call + [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get team member IDs. + + To return only the shifts assigned to the specified team members, include the + `assignment_status` filter in the query. Otherwise, all unassigned shifts are + returned along with shifts assigned to the specified team members. + """ + + assignment_status: typing.Optional[ScheduledShiftFilterAssignmentStatus] = pydantic.Field(default=None) + """ + Return shifts based on whether a team member is assigned. A shift is + assigned if the `team_member_id` field is populated in the `draft_shift_details` + or `published_shift details` field of the shift. + + To return only draft or published shifts, include the `scheduled_shift_statuses` + filter in the query. + See [ScheduledShiftFilterAssignmentStatus](#type-scheduledshiftfilterassignmentstatus) for possible values + """ + + scheduled_shift_statuses: typing.Optional[typing.List[ScheduledShiftFilterScheduledShiftStatus]] = pydantic.Field( + default=None + ) + """ + Return shifts based on the draft or published status of the shift. + A shift is published if the `published_shift_details` field is present. + + Note that shifts with `draft_shift_details.is_deleted` set to `true` are ignored + with the `DRAFT` filter. + See [ScheduledShiftFilterScheduledShiftStatus](#type-scheduledshiftfilterscheduledshiftstatus) for possible values + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_filter_assignment_status.py b/src/square/types/scheduled_shift_filter_assignment_status.py new file mode 100644 index 00000000..975795e2 --- /dev/null +++ b/src/square/types/scheduled_shift_filter_assignment_status.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +ScheduledShiftFilterAssignmentStatus = typing.Union[typing.Literal["ASSIGNED", "UNASSIGNED"], typing.Any] diff --git a/src/square/types/scheduled_shift_filter_scheduled_shift_status.py b/src/square/types/scheduled_shift_filter_scheduled_shift_status.py new file mode 100644 index 00000000..ee721b58 --- /dev/null +++ b/src/square/types/scheduled_shift_filter_scheduled_shift_status.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +ScheduledShiftFilterScheduledShiftStatus = typing.Union[typing.Literal["DRAFT", "PUBLISHED"], typing.Any] diff --git a/src/square/types/scheduled_shift_notification_audience.py b/src/square/types/scheduled_shift_notification_audience.py new file mode 100644 index 00000000..9ee4eaa3 --- /dev/null +++ b/src/square/types/scheduled_shift_notification_audience.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +ScheduledShiftNotificationAudience = typing.Union[typing.Literal["ALL", "AFFECTED", "NONE"], typing.Any] diff --git a/src/square/types/scheduled_shift_query.py b/src/square/types/scheduled_shift_query.py new file mode 100644 index 00000000..6c0f0166 --- /dev/null +++ b/src/square/types/scheduled_shift_query.py @@ -0,0 +1,34 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift_filter import ScheduledShiftFilter +import pydantic +from .scheduled_shift_sort import ScheduledShiftSort +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShiftQuery(UncheckedBaseModel): + """ + Represents filter and sort criteria for the `query` field in a + [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. + """ + + filter: typing.Optional[ScheduledShiftFilter] = pydantic.Field(default=None) + """ + Filtering options for the query. + """ + + sort: typing.Optional[ScheduledShiftSort] = pydantic.Field(default=None) + """ + Sorting options for the query. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_sort.py b/src/square/types/scheduled_shift_sort.py new file mode 100644 index 00000000..a4cd8c9c --- /dev/null +++ b/src/square/types/scheduled_shift_sort.py @@ -0,0 +1,36 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift_sort_field import ScheduledShiftSortField +import pydantic +from .sort_order import SortOrder +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShiftSort(UncheckedBaseModel): + """ + Defines sort criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) + request. + """ + + field: typing.Optional[ScheduledShiftSortField] = pydantic.Field(default=None) + """ + The field to sort on. The default value is `START_AT`. + See [ScheduledShiftSortField](#type-scheduledshiftsortfield) for possible values + """ + + order: typing.Optional[SortOrder] = pydantic.Field(default=None) + """ + The order in which results are returned. The default value is `ASC`. + See [SortOrder](#type-sortorder) for possible values + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_sort_field.py b/src/square/types/scheduled_shift_sort_field.py new file mode 100644 index 00000000..2abcf87a --- /dev/null +++ b/src/square/types/scheduled_shift_sort_field.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +ScheduledShiftSortField = typing.Union[typing.Literal["START_AT", "END_AT", "CREATED_AT", "UPDATED_AT"], typing.Any] diff --git a/src/square/types/scheduled_shift_workday.py b/src/square/types/scheduled_shift_workday.py new file mode 100644 index 00000000..d5ef0dff --- /dev/null +++ b/src/square/types/scheduled_shift_workday.py @@ -0,0 +1,43 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .date_range import DateRange +import pydantic +from .scheduled_shift_workday_matcher import ScheduledShiftWorkdayMatcher +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class ScheduledShiftWorkday(UncheckedBaseModel): + """ + A `ScheduledShift` search query filter parameter that sets a range of days that + a `Shift` must start or end in before passing the filter condition. + """ + + date_range: typing.Optional[DateRange] = pydantic.Field(default=None) + """ + Dates for fetching the scheduled shifts. + """ + + match_scheduled_shifts_by: typing.Optional[ScheduledShiftWorkdayMatcher] = pydantic.Field(default=None) + """ + The strategy on which the dates are applied. + See [ScheduledShiftWorkdayMatcher](#type-scheduledshiftworkdaymatcher) for possible values + """ + + default_timezone: typing.Optional[str] = pydantic.Field(default=None) + """ + Location-specific timezones convert workdays to datetime filters. + Every location included in the query must have a timezone or this field + must be provided as a fallback. Format: the IANA timezone database + identifier for the relevant timezone. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/scheduled_shift_workday_matcher.py b/src/square/types/scheduled_shift_workday_matcher.py new file mode 100644 index 00000000..2f541c7f --- /dev/null +++ b/src/square/types/scheduled_shift_workday_matcher.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +ScheduledShiftWorkdayMatcher = typing.Union[typing.Literal["START_AT", "END_AT", "INTERSECTION"], typing.Any] diff --git a/src/square/types/search_scheduled_shifts_response.py b/src/square/types/search_scheduled_shifts_response.py new file mode 100644 index 00000000..7f0cbca4 --- /dev/null +++ b/src/square/types/search_scheduled_shifts_response.py @@ -0,0 +1,40 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift import ScheduledShift +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class SearchScheduledShiftsResponse(UncheckedBaseModel): + """ + Represents a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) response. + Either `scheduled_shifts` or `errors` is present in the response. + """ + + scheduled_shifts: typing.Optional[typing.List[ScheduledShift]] = pydantic.Field(default=None) + """ + A paginated list of scheduled shifts that match the query conditions. + """ + + cursor: typing.Optional[str] = pydantic.Field(default=None) + """ + The pagination cursor used to retrieve the next page of results. This field is present + only if additional results are available. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/search_timecards_response.py b/src/square/types/search_timecards_response.py new file mode 100644 index 00000000..af79bc9c --- /dev/null +++ b/src/square/types/search_timecards_response.py @@ -0,0 +1,40 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard import Timecard +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class SearchTimecardsResponse(UncheckedBaseModel): + """ + The response to a request for `Timecard` objects. The response contains + the requested `Timecard` objects and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecards: typing.Optional[typing.List[Timecard]] = pydantic.Field(default=None) + """ + Timecards. + """ + + cursor: typing.Optional[str] = pydantic.Field(default=None) + """ + An opaque cursor for fetching the next page. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/shift.py b/src/square/types/shift.py index 88fed858..d11dd1d3 100644 --- a/src/square/types/shift.py +++ b/src/square/types/shift.py @@ -15,6 +15,9 @@ class Shift(UncheckedBaseModel): A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift. + + Deprecated at Square API version 2025-05-21. Replaced by [Timecard](entity:Timecard). + See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ id: typing.Optional[str] = pydantic.Field(default=None) diff --git a/src/square/types/shift_filter.py b/src/square/types/shift_filter.py index 1bacf8a0..2d482e62 100644 --- a/src/square/types/shift_filter.py +++ b/src/square/types/shift_filter.py @@ -13,6 +13,8 @@ class ShiftFilter(UncheckedBaseModel): """ Defines a filter used in a search for `Shift` records. `AND` logic is used by Square's servers to apply each filter property specified. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ location_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) diff --git a/src/square/types/shift_query.py b/src/square/types/shift_query.py index 9dbcb41b..4a15e652 100644 --- a/src/square/types/shift_query.py +++ b/src/square/types/shift_query.py @@ -11,6 +11,8 @@ class ShiftQuery(UncheckedBaseModel): """ The parameters of a `Shift` search query, which includes filter and sort options. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ filter: typing.Optional[ShiftFilter] = pydantic.Field(default=None) diff --git a/src/square/types/shift_sort.py b/src/square/types/shift_sort.py index d2f2c307..98a7fece 100644 --- a/src/square/types/shift_sort.py +++ b/src/square/types/shift_sort.py @@ -11,6 +11,8 @@ class ShiftSort(UncheckedBaseModel): """ Sets the sort order of search results. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ field: typing.Optional[ShiftSortField] = pydantic.Field(default=None) diff --git a/src/square/types/shift_wage.py b/src/square/types/shift_wage.py index 7faba684..f93a2ad7 100644 --- a/src/square/types/shift_wage.py +++ b/src/square/types/shift_wage.py @@ -10,6 +10,8 @@ class ShiftWage(UncheckedBaseModel): """ The hourly wage rate used to compensate an employee for this shift. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ title: typing.Optional[str] = pydantic.Field(default=None) @@ -26,7 +28,7 @@ class ShiftWage(UncheckedBaseModel): job_id: typing.Optional[str] = pydantic.Field(default=None) """ The id of the job performed during this shift. Square - labor-reporting UIs might group shifts together by id. This cannot be used to retrieve the job. + labor-reporting UIs might group shifts together by id. """ tip_eligible: typing.Optional[bool] = pydantic.Field(default=None) diff --git a/src/square/types/shift_workday.py b/src/square/types/shift_workday.py index 558fdbb3..23d6607c 100644 --- a/src/square/types/shift_workday.py +++ b/src/square/types/shift_workday.py @@ -12,6 +12,8 @@ class ShiftWorkday(UncheckedBaseModel): """ A `Shift` search query filter parameter that sets a range of days that a `Shift` must start or end in before passing the filter condition. + + Deprecated at Square API version 2025-05-21. See the [migration notes](https://developer.squareup.com/docs/labor-api/what-it-does#migration-notes). """ date_range: typing.Optional[DateRange] = pydantic.Field(default=None) diff --git a/src/square/types/team_member_wage.py b/src/square/types/team_member_wage.py index 9bf3e7c3..bcdca03f 100644 --- a/src/square/types/team_member_wage.py +++ b/src/square/types/team_member_wage.py @@ -9,8 +9,9 @@ class TeamMemberWage(UncheckedBaseModel): """ - The hourly wage rate that a team member earns on a `Shift` for doing the job - specified by the `title` property of this object. + Job and wage information for a [team member](entity:TeamMember). + This convenience object provides details needed to specify the `wage` + field for a [timecard](entity:Timecard). """ id: typing.Optional[str] = pydantic.Field(default=None) @@ -36,8 +37,7 @@ class TeamMemberWage(UncheckedBaseModel): job_id: typing.Optional[str] = pydantic.Field(default=None) """ - An identifier for the job that this wage relates to. This cannot be - used to retrieve the job. + An identifier for the [job](entity:Job) that this wage relates to. """ tip_eligible: typing.Optional[bool] = pydantic.Field(default=None) diff --git a/src/square/types/timecard.py b/src/square/types/timecard.py new file mode 100644 index 00000000..403b0fef --- /dev/null +++ b/src/square/types/timecard.py @@ -0,0 +1,102 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from .timecard_wage import TimecardWage +from .break_ import Break +from .timecard_status import TimecardStatus +from .money import Money +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class Timecard(UncheckedBaseModel): + """ + A record of the hourly rate, start time, and end time of a single timecard (shift) + for a team member. This might include a record of the start and end times of breaks + taken during the shift. + """ + + id: typing.Optional[str] = pydantic.Field(default=None) + """ + **Read only** The Square-issued UUID for this object. + """ + + location_id: str = pydantic.Field() + """ + The ID of the [location](entity:Location) for this timecard. The location should be based on + where the team member clocked in. + """ + + timezone: typing.Optional[str] = pydantic.Field(default=None) + """ + **Read only** The time zone calculated from the location based on the `location_id`, + provided as a convenience value. Format: the IANA time zone database identifier for the + location time zone. + """ + + start_at: str = pydantic.Field() + """ + The start time of the timecard, in RFC 3339 format and shifted to the location + timezone + offset. Precision up to the minute is respected; seconds are truncated. + """ + + end_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The end time of the timecard, in RFC 3339 format and shifted to the location + timezone + offset. Precision up to the minute is respected; seconds are truncated. + """ + + wage: typing.Optional[TimecardWage] = pydantic.Field(default=None) + """ + Job and pay related information. If the wage is not set on create, it defaults to a wage + of zero. If the title is not set on create, it defaults to the name of the role the team member + is assigned to, if any. + """ + + breaks: typing.Optional[typing.List[Break]] = pydantic.Field(default=None) + """ + A list of all the paid or unpaid breaks that were taken during this timecard. + """ + + status: typing.Optional[TimecardStatus] = pydantic.Field(default=None) + """ + Describes the working state of the timecard. + See [TimecardStatus](#type-timecardstatus) for possible values + """ + + version: typing.Optional[int] = pydantic.Field(default=None) + """ + **Read only** The current version of the timecard, which is incremented with each update. + This field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) + control to ensure that requests don't overwrite data from another request. + """ + + created_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The timestamp of when the timecard was created, in RFC 3339 format presented as UTC. + """ + + updated_at: typing.Optional[str] = pydantic.Field(default=None) + """ + The timestamp of when the timecard was last updated, in RFC 3339 format presented as UTC. + """ + + team_member_id: str = pydantic.Field() + """ + The ID of the [team member](entity:TeamMember) this timecard belongs to. + """ + + declared_cash_tip_money: typing.Optional[Money] = pydantic.Field(default=None) + """ + The cash tips declared by the team member for this timecard. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_filter.py b/src/square/types/timecard_filter.py new file mode 100644 index 00000000..e09e1999 --- /dev/null +++ b/src/square/types/timecard_filter.py @@ -0,0 +1,56 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from .timecard_filter_status import TimecardFilterStatus +from .time_range import TimeRange +from .timecard_workday import TimecardWorkday +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class TimecardFilter(UncheckedBaseModel): + """ + Defines a filter used in a search for `Timecard` records. `AND` logic is + used by Square's servers to apply each filter property specified. + """ + + location_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) + """ + Fetch timecards for the specified location. + """ + + status: typing.Optional[TimecardFilterStatus] = pydantic.Field(default=None) + """ + Fetch a `Timecard` instance by `Timecard.status`. + See [TimecardFilterStatus](#type-timecardfilterstatus) for possible values + """ + + start: typing.Optional[TimeRange] = pydantic.Field(default=None) + """ + Fetch `Timecard` instances that start in the time range - Inclusive. + """ + + end: typing.Optional[TimeRange] = pydantic.Field(default=None) + """ + Fetch the `Timecard` instances that end in the time range - Inclusive. + """ + + workday: typing.Optional[TimecardWorkday] = pydantic.Field(default=None) + """ + Fetch the `Timecard` instances based on the workday date range. + """ + + team_member_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) + """ + Fetch timecards for the specified team members. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_filter_status.py b/src/square/types/timecard_filter_status.py new file mode 100644 index 00000000..c46d8ebd --- /dev/null +++ b/src/square/types/timecard_filter_status.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +TimecardFilterStatus = typing.Union[typing.Literal["OPEN", "CLOSED"], typing.Any] diff --git a/src/square/types/timecard_query.py b/src/square/types/timecard_query.py new file mode 100644 index 00000000..52be4db0 --- /dev/null +++ b/src/square/types/timecard_query.py @@ -0,0 +1,33 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard_filter import TimecardFilter +import pydantic +from .timecard_sort import TimecardSort +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class TimecardQuery(UncheckedBaseModel): + """ + The parameters of a `Timecard` search query, which includes filter and sort options. + """ + + filter: typing.Optional[TimecardFilter] = pydantic.Field(default=None) + """ + Query filter options. + """ + + sort: typing.Optional[TimecardSort] = pydantic.Field(default=None) + """ + Sort order details. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_sort.py b/src/square/types/timecard_sort.py new file mode 100644 index 00000000..f78e9ff4 --- /dev/null +++ b/src/square/types/timecard_sort.py @@ -0,0 +1,35 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard_sort_field import TimecardSortField +import pydantic +from .sort_order import SortOrder +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class TimecardSort(UncheckedBaseModel): + """ + Sets the sort order of search results. + """ + + field: typing.Optional[TimecardSortField] = pydantic.Field(default=None) + """ + The field to sort on. + See [TimecardSortField](#type-timecardsortfield) for possible values + """ + + order: typing.Optional[SortOrder] = pydantic.Field(default=None) + """ + The order in which results are returned. Defaults to DESC. + See [SortOrder](#type-sortorder) for possible values + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_sort_field.py b/src/square/types/timecard_sort_field.py new file mode 100644 index 00000000..d7bed199 --- /dev/null +++ b/src/square/types/timecard_sort_field.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +TimecardSortField = typing.Union[typing.Literal["START_AT", "END_AT", "CREATED_AT", "UPDATED_AT"], typing.Any] diff --git a/src/square/types/timecard_status.py b/src/square/types/timecard_status.py new file mode 100644 index 00000000..67e30818 --- /dev/null +++ b/src/square/types/timecard_status.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +TimecardStatus = typing.Union[typing.Literal["OPEN", "CLOSED"], typing.Any] diff --git a/src/square/types/timecard_wage.py b/src/square/types/timecard_wage.py new file mode 100644 index 00000000..0490688a --- /dev/null +++ b/src/square/types/timecard_wage.py @@ -0,0 +1,44 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +import pydantic +from .money import Money +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class TimecardWage(UncheckedBaseModel): + """ + The hourly wage rate used to compensate a team member for a [timecard](entity:Timecard). + """ + + title: typing.Optional[str] = pydantic.Field(default=None) + """ + The name of the job performed during this timecard. + """ + + hourly_rate: typing.Optional[Money] = pydantic.Field(default=None) + """ + Can be a custom-set hourly wage or the calculated effective hourly + wage based on the annual wage and hours worked per week. + """ + + job_id: typing.Optional[str] = pydantic.Field(default=None) + """ + The ID of the [job](entity:Job) performed for this timecard. Square + labor-reporting UIs might group timecards together by ID. + """ + + tip_eligible: typing.Optional[bool] = pydantic.Field(default=None) + """ + Whether team members are eligible for tips when working this job. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_workday.py b/src/square/types/timecard_workday.py new file mode 100644 index 00000000..07cea638 --- /dev/null +++ b/src/square/types/timecard_workday.py @@ -0,0 +1,43 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .date_range import DateRange +import pydantic +from .timecard_workday_matcher import TimecardWorkdayMatcher +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class TimecardWorkday(UncheckedBaseModel): + """ + A `Timecard` search query filter parameter that sets a range of days that + a `Timecard` must start or end in before passing the filter condition. + """ + + date_range: typing.Optional[DateRange] = pydantic.Field(default=None) + """ + Dates for fetching the timecards. + """ + + match_timecards_by: typing.Optional[TimecardWorkdayMatcher] = pydantic.Field(default=None) + """ + The strategy on which the dates are applied. + See [TimecardWorkdayMatcher](#type-timecardworkdaymatcher) for possible values + """ + + default_timezone: typing.Optional[str] = pydantic.Field(default=None) + """ + Location-specific timezones convert workdays to datetime filters. + Every location included in the query must have a timezone or this field + must be provided as a fallback. Format: the IANA timezone database + identifier for the relevant timezone. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/timecard_workday_matcher.py b/src/square/types/timecard_workday_matcher.py new file mode 100644 index 00000000..870898eb --- /dev/null +++ b/src/square/types/timecard_workday_matcher.py @@ -0,0 +1,5 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +TimecardWorkdayMatcher = typing.Union[typing.Literal["START_AT", "END_AT", "INTERSECTION"], typing.Any] diff --git a/src/square/types/update_scheduled_shift_response.py b/src/square/types/update_scheduled_shift_response.py new file mode 100644 index 00000000..61f5f2c9 --- /dev/null +++ b/src/square/types/update_scheduled_shift_response.py @@ -0,0 +1,36 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .scheduled_shift import ScheduledShift +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class UpdateScheduledShiftResponse(UncheckedBaseModel): + """ + Represents an [UpdateScheduledShift](api-endpoint:Labor-UpdateScheduledShift) response. + Either `scheduled_shift` or `errors` is present in the response. + """ + + scheduled_shift: typing.Optional[ScheduledShift] = pydantic.Field(default=None) + """ + The updated scheduled shift. To make the changes public, call + [PublishScheduledShift](api-endpoint:Labor-PublishScheduledShift) or + [BulkPublishScheduledShifts](api-endpoint:Labor-BulkPublishScheduledShifts). + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/square/types/update_timecard_response.py b/src/square/types/update_timecard_response.py new file mode 100644 index 00000000..08428265 --- /dev/null +++ b/src/square/types/update_timecard_response.py @@ -0,0 +1,35 @@ +# This file was auto-generated by Fern from our API Definition. + +from ..core.unchecked_base_model import UncheckedBaseModel +import typing +from .timecard import Timecard +import pydantic +from .error import Error +from ..core.pydantic_utilities import IS_PYDANTIC_V2 + + +class UpdateTimecardResponse(UncheckedBaseModel): + """ + The response to a request to update a `Timecard`. The response contains + the updated `Timecard` object and might contain a set of `Error` objects if + the request resulted in errors. + """ + + timecard: typing.Optional[Timecard] = pydantic.Field(default=None) + """ + The updated `Timecard`. + """ + + errors: typing.Optional[typing.List[Error]] = pydantic.Field(default=None) + """ + Any errors that occurred during the request. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow