Merge pull request #139 from square/release/2024-12-18

Generated PR for Release: 2024-12-18

Author: mikekono

doc/api/payments.md

@@ -40,7 +40,10 @@ def list_payments(begin_time: nil,
                   limit: nil,
                   is_offline_payment: false,
                   offline_begin_time: nil,
-                  offline_end_time: nil)
+                  offline_end_time: nil,
+                  updated_at_begin_time: nil,
+                  updated_at_end_time: nil,
+                  sort_field: nil)
 ```
 
 ## Parameters
@@ -49,7 +52,7 @@ def list_payments(begin_time: nil,
 |  --- | --- | --- | --- |
 | `begin_time` | `String` | Query, Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format.  <br>The range is determined using the `created_at` field for each Payment.<br>Inclusive. Default: The current time minus one year. |
 | `end_time` | `String` | Query, Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The<br>range is determined using the `created_at` field for each Payment.<br><br>Default: The current time. |
-| `sort_order` | `String` | Query, Optional | The order in which results are listed by `Payment.created_at`:<br><br>- `ASC` - Oldest to newest.<br>- `DESC` - Newest to oldest (default). |
+| `sort_order` | `String` | Query, Optional | The order in which results are listed by `ListPaymentsRequest.sort_field`:<br><br>- `ASC` - Oldest to newest.<br>- `DESC` - Newest to oldest (default). |
 | `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this cursor to retrieve the next set of results for the original query.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
 | `location_id` | `String` | Query, Optional | Limit results to the location supplied. By default, results are returned<br>for the default (main) location associated with the seller. |
 | `total` | `Integer` | Query, Optional | The exact amount in the `total_money` for a payment. |
@@ -59,6 +62,9 @@ def list_payments(begin_time: nil,
 | `is_offline_payment` | `TrueClass \| FalseClass` | Query, Optional | Whether the payment was taken offline or not.<br>**Default**: `false` |
 | `offline_begin_time` | `String` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
 | `offline_end_time` | `String` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
+| `updated_at_begin_time` | `String` | Query, Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format.  The<br>range is determined using the `updated_at` field for each Payment. |
+| `updated_at_end_time` | `String` | Query, Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format.  The<br>range is determined using the `updated_at` field for each Payment. |
+| `sort_field` | [`String (Payment Sort Field)`](../../doc/models/payment-sort-field.md) | Query, Optional | The field used to sort results by. The default is `CREATED_AT`. |
 
 ## Response Type
 

doc/api/team.md

@@ -13,6 +13,10 @@ team_api = client.team
 * [Create Team Member](../../doc/api/team.md#create-team-member)
 * [Bulk Create Team Members](../../doc/api/team.md#bulk-create-team-members)
 * [Bulk Update Team Members](../../doc/api/team.md#bulk-update-team-members)
+* [List Jobs](../../doc/api/team.md#list-jobs)
+* [Create Job](../../doc/api/team.md#create-job)
+* [Retrieve Job](../../doc/api/team.md#retrieve-job)
+* [Update Job](../../doc/api/team.md#update-job)
 * [Search Team Members](../../doc/api/team.md#search-team-members)
 * [Retrieve Team Member](../../doc/api/team.md#retrieve-team-member)
 * [Update Team Member](../../doc/api/team.md#update-team-member)
@@ -62,6 +66,28 @@ body = {
         'YSGH2WBKG94QZ',
         'GA2Y9HSJ8KRYT'
       ]
+    },
+    :wage_setting => {
+      :job_assignments => [
+        {
+          :pay_type => 'SALARY',
+          :annual_rate => {
+            :amount => 3000000,
+            :currency => 'USD'
+          },
+          :weekly_hours => 40,
+          :job_id => 'FjS8x95cqHiMenw4f1NAUH4P'
+        },
+        {
+          :pay_type => 'HOURLY',
+          :hourly_rate => {
+            :amount => 2000,
+            :currency => 'USD'
+          },
+          :job_id => 'VDNpRv8da51NU8qZFC5zDWpF'
+        }
+      ],
+      :is_overtime_exempt => true
     }
   }
 }
@@ -218,13 +244,165 @@ end
 ```
 
 
+# List Jobs
+
+Lists jobs in a seller account. Results are sorted by title in ascending order.
+
+```ruby
+def list_jobs(cursor: nil)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `cursor` | `String` | Query, Optional | The pagination cursor returned by the previous call to this endpoint. Provide this<br>cursor to retrieve the next page of results for your original request. For more information,<br>see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
+
+## Response Type
+
+This method returns a `ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`List Jobs Response Hash`](../../doc/models/list-jobs-response.md).
+
+## Example Usage
+
+```ruby
+result = team_api.list_jobs
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# Create Job
+
+Creates a job in a seller account. A job defines a title and tip eligibility. Note that
+compensation is defined in a [job assignment](../../doc/models/job-assignment.md) in a team member's wage setting.
+
+```ruby
+def create_job(body:)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Create Job Request Hash`](../../doc/models/create-job-request.md) | Body, Required | An object containing the fields to POST for the request.<br><br>See the corresponding object definition for field details. |
+
+## Response Type
+
+This method returns a `ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Create Job Response Hash`](../../doc/models/create-job-response.md).
+
+## Example Usage
+
+```ruby
+body = {
+  :job => {
+    :title => 'Cashier',
+    :is_tip_eligible => true
+  },
+  :idempotency_key => 'idempotency-key-0'
+}
+
+
+result = team_api.create_job(body: body)
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# Retrieve Job
+
+Retrieves a specified job.
+
+```ruby
+def retrieve_job(job_id:)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `job_id` | `String` | Template, Required | The ID of the job to retrieve. |
+
+## Response Type
+
+This method returns a `ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Retrieve Job Response Hash`](../../doc/models/retrieve-job-response.md).
+
+## Example Usage
+
+```ruby
+job_id = 'job_id2'
+
+
+result = team_api.retrieve_job(job_id: job_id)
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# Update Job
+
+Updates the title or tip eligibility of a job. Changes to the title propagate to all
+`JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference the job ID. Changes to
+tip eligibility propagate to all `TeamMemberWage` objects that reference the job ID.
+
+```ruby
+def update_job(job_id:,
+               body:)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `job_id` | `String` | Template, Required | The ID of the job to update. |
+| `body` | [`Update Job Request Hash`](../../doc/models/update-job-request.md) | Body, Required | An object containing the fields to POST for the request.<br><br>See the corresponding object definition for field details. |
+
+## Response Type
+
+This method returns a `ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Update Job Response Hash`](../../doc/models/update-job-response.md).
+
+## Example Usage
+
+```ruby
+job_id = 'job_id2'
+
+body = {
+  :job => {
+    :title => 'Cashier 1',
+    :is_tip_eligible => true
+  }
+}
+
+
+result = team_api.update_job(
+  job_id: job_id,
+  body: body
+)
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
 # Search Team Members
 
 Returns a paginated list of `TeamMember` objects for a business.
-The list can be filtered by the following:
-
-- location IDs
-- `status`
+The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` status, or whether
+the team member is the Square account owner.
 
 ```ruby
 def search_team_members(body:)
@@ -362,8 +540,11 @@ end
 # Retrieve Wage Setting
 
 Retrieves a `WageSetting` object for a team member specified
-by `TeamMember.id`.
-Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).
+by `TeamMember.id`. For more information, see
+[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).
+
+Square recommends using [RetrieveTeamMember](../../doc/api/team.md#retrieve-team-member) or [SearchTeamMembers](../../doc/api/team.md#search-team-members)
+to get this information directly from the `TeamMember.wage_setting` field.
 
 ```ruby
 def retrieve_wage_setting(team_member_id:)
@@ -398,10 +579,13 @@ end
 # Update Wage Setting
 
 Creates or updates a `WageSetting` object. The object is created if a
-`WageSetting` with the specified `team_member_id` does not exist. Otherwise,
+`WageSetting` with the specified `team_member_id` doesn't exist. Otherwise,
 it fully replaces the `WageSetting` object for the team member.
-The `WageSetting` is returned on a successful update.
-Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).
+The `WageSetting` is returned on a successful update. For more information, see
+[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).
+
+Square recommends using [CreateTeamMember](../../doc/api/team.md#create-team-member) or [UpdateTeamMember](../../doc/api/team.md#update-team-member)
+to manage the `TeamMember.wage_setting` field directly.
 
 ```ruby
 def update_wage_setting(team_member_id:,
@@ -428,19 +612,19 @@ body = {
   :wage_setting => {
     :job_assignments => [
       {
-        :job_title => 'Manager',
         :pay_type => 'SALARY',
+        :job_title => 'Manager',
         :annual_rate => {
           :amount => 3000000,
           :currency => 'USD'
         },
         :weekly_hours => 40
       },
       {
-        :job_title => 'Cashier',
         :pay_type => 'HOURLY',
+        :job_title => 'Cashier',
         :hourly_rate => {
-          :amount => 1200,
+          :amount => 2000,
           :currency => 'USD'
         }
       }

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2024-11-20'` |
+| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2024-12-18'` |
 | `custom_url` | `String` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `'https://connect.squareup.com'` |
 | `environment` | `string` | The API environment. <br> **Default: `production`** |
 | `connection` | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests |
@@ -25,7 +25,7 @@ The API client can be initialized as follows:
 
 ```ruby
 client = Square::Client.new(
-  square_version: '2024-11-20',
+  square_version: '2024-12-18',
   bearer_auth_credentials: BearerAuthCredentials.new(
     access_token: 'AccessToken'
   ),
@@ -55,7 +55,7 @@ require 'square'
 include Square
 
 client = Square::Client.new(
-  square_version: '2024-11-20',
+  square_version: '2024-12-18',
   bearer_auth_credentials: BearerAuthCredentials.new(
     access_token: 'AccessToken'
   ),

doc/models/bulk-create-team-members-request.md

@@ -11,7 +11,7 @@ Represents a bulk create request for `TeamMember` objects.
 
 | Name | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `team_members` | [`Hash String Create Team Member Request Hash`](../../doc/models/create-team-member-request.md) | Required | The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`. The maximum number of create objects is 25. |
+| `team_members` | [`Hash String Create Team Member Request Hash`](../../doc/models/create-team-member-request.md) | Required | The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`.<br>The maximum number of create objects is 25.<br><br>If you include a team member's `wage_setting`, you must provide `job_id` for each job assignment. To get job IDs,<br>call [ListJobs](api-endpoint:Team-ListJobs). |
 
 ## Example (as JSON)