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

Generated PR for Release: 2024-12-18

Author: mikekono

doc/api/payments.md

@@ -41,7 +41,10 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
     final Integer limit,
     final Boolean isOfflinePayment,
     final String offlineBeginTime,
-    final String offlineEndTime)
+    final String offlineEndTime,
+    final String updatedAtBeginTime,
+    final String updatedAtEndTime,
+    final String sortField)
 ```
 
 ## Parameters
@@ -50,7 +53,7 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
 |  --- | --- | --- | --- |
 | `beginTime` | `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. |
 | `endTime` | `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. |
-| `sortOrder` | `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). |
+| `sortOrder` | `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). |
 | `locationId` | `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` | `Long` | Query, Optional | The exact amount in the `total_money` for a payment. |
@@ -60,6 +63,9 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
 | `isOfflinePayment` | `Boolean` | Query, Optional | Whether the payment was taken offline or not.<br>**Default**: `false` |
 | `offlineBeginTime` | `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. |
 | `offlineEndTime` | `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. |
+| `updatedAtBeginTime` | `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. |
+| `updatedAtEndTime` | `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. |
+| `sortField` | [`String`](../../doc/models/payment-sort-field.md) | Query, Optional | The field used to sort results by. The default is `CREATED_AT`. |
 
 ## Response Type
 
@@ -70,7 +76,7 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
 ```java
 Boolean isOfflinePayment = false;
 
-paymentsApi.listPaymentsAsync(null, null, null, null, null, null, null, null, null, isOfflinePayment, null, null).thenAccept(result -> {
+paymentsApi.listPaymentsAsync(null, null, null, null, null, null, null, null, null, isOfflinePayment, null, null, null, null, null).thenAccept(result -> {
     // TODO success callback handler
     System.out.println(result);
 }).exceptionally(exception -> {

doc/api/team.md

@@ -13,6 +13,10 @@ TeamApi teamApi = client.getTeamApi();
 * [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)
@@ -64,6 +68,30 @@ CreateTeamMemberRequest body = new CreateTeamMemberRequest.Builder()
                 "GA2Y9HSJ8KRYT"
             ))
             .build())
+        .wageSetting(new WageSetting.Builder()
+            .jobAssignments(Arrays.asList(
+                new JobAssignment.Builder(
+                    "SALARY"
+                )
+                .annualRate(new Money.Builder()
+                        .amount(3000000L)
+                        .currency("USD")
+                        .build())
+                .weeklyHours(40)
+                .jobId("FjS8x95cqHiMenw4f1NAUH4P")
+                .build(),
+                new JobAssignment.Builder(
+                    "HOURLY"
+                )
+                .hourlyRate(new Money.Builder()
+                        .amount(2000L)
+                        .currency("USD")
+                        .build())
+                .jobId("VDNpRv8da51NU8qZFC5zDWpF")
+                .build()
+            ))
+            .isOvertimeExempt(true)
+            .build())
         .build())
     .build();
 
@@ -223,13 +251,168 @@ teamApi.bulkUpdateTeamMembersAsync(body).thenAccept(result -> {
 ```
 
 
+# List Jobs
+
+Lists jobs in a seller account. Results are sorted by title in ascending order.
+
+```java
+CompletableFuture<ListJobsResponse> listJobsAsync(
+    final String cursor)
+```
+
+## 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
+
+[`ListJobsResponse`](../../doc/models/list-jobs-response.md)
+
+## Example Usage
+
+```java
+teamApi.listJobsAsync(null).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
+});
+```
+
+
+# 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.
+
+```java
+CompletableFuture<CreateJobResponse> createJobAsync(
+    final CreateJobRequest body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`CreateJobRequest`](../../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
+
+[`CreateJobResponse`](../../doc/models/create-job-response.md)
+
+## Example Usage
+
+```java
+CreateJobRequest body = new CreateJobRequest.Builder(
+    new Job.Builder()
+        .title("Cashier")
+        .isTipEligible(true)
+        .build(),
+    "idempotency-key-0"
+)
+.build();
+
+teamApi.createJobAsync(body).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
+});
+```
+
+
+# Retrieve Job
+
+Retrieves a specified job.
+
+```java
+CompletableFuture<RetrieveJobResponse> retrieveJobAsync(
+    final String jobId)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `jobId` | `String` | Template, Required | The ID of the job to retrieve. |
+
+## Response Type
+
+[`RetrieveJobResponse`](../../doc/models/retrieve-job-response.md)
+
+## Example Usage
+
+```java
+String jobId = "job_id2";
+
+teamApi.retrieveJobAsync(jobId).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
+});
+```
+
+
+# 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.
+
+```java
+CompletableFuture<UpdateJobResponse> updateJobAsync(
+    final String jobId,
+    final UpdateJobRequest body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `jobId` | `String` | Template, Required | The ID of the job to update. |
+| `body` | [`UpdateJobRequest`](../../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
+
+[`UpdateJobResponse`](../../doc/models/update-job-response.md)
+
+## Example Usage
+
+```java
+String jobId = "job_id2";
+UpdateJobRequest body = new UpdateJobRequest.Builder(
+    new Job.Builder()
+        .title("Cashier 1")
+        .isTipEligible(true)
+        .build()
+)
+.build();
+
+teamApi.updateJobAsync(jobId, body).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
+});
+```
+
+
 # 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.
 
 ```java
 CompletableFuture<SearchTeamMembersResponse> searchTeamMembersAsync(
@@ -366,8 +549,11 @@ teamApi.updateTeamMemberAsync(teamMemberId, body).thenAccept(result -> {
 # 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.
 
 ```java
 CompletableFuture<RetrieveWageSettingResponse> retrieveWageSettingAsync(
@@ -403,10 +589,13 @@ teamApi.retrieveWageSettingAsync(teamMemberId).thenAccept(result -> {
 # 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.
 
 ```java
 CompletableFuture<UpdateWageSettingResponse> updateWageSettingAsync(
@@ -433,21 +622,21 @@ UpdateWageSettingRequest body = new UpdateWageSettingRequest.Builder(
     new WageSetting.Builder()
         .jobAssignments(Arrays.asList(
             new JobAssignment.Builder(
-                "Manager",
                 "SALARY"
             )
+            .jobTitle("Manager")
             .annualRate(new Money.Builder()
                     .amount(3000000L)
                     .currency("USD")
                     .build())
             .weeklyHours(40)
             .build(),
             new JobAssignment.Builder(
-                "Cashier",
                 "HOURLY"
             )
+            .jobTitle("Cashier")
             .hourlyRate(new Money.Builder()
-                    .amount(1200L)
+                    .amount(2000L)
                     .currency("USD")
                     .build())
             .build()

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2024-11-20"` |
+| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2024-12-18"` |
 | `customUrl` | `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`** |
 | `httpClientConfig` | [`Consumer<HttpClientConfiguration.Builder>`](http-client-configuration-builder.md) | Set up Http Client Configuration instance. |
@@ -19,7 +19,7 @@ The API client can be initialized as follows:
 SquareClient client = new SquareClient.Builder()
     .httpClientConfig(configBuilder -> configBuilder
             .timeout(0))
-    .squareVersion("2024-11-20")
+    .squareVersion("2024-12-18")
     .bearerAuthCredentials(new BearerAuthModel.Builder(
             "AccessToken"
         )
@@ -45,7 +45,7 @@ public class Program {
         SquareClient client = new SquareClient.Builder()
             .httpClientConfig(configBuilder -> configBuilder
                     .timeout(0))
-            .squareVersion("2024-11-20")
+            .squareVersion("2024-12-18")
             .bearerAuthCredentials(new BearerAuthModel.Builder(
                     "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 | Getter |
 |  --- | --- | --- | --- | --- |
-| `TeamMembers` | [`Map<String, CreateTeamMemberRequest>`](../../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. | Map<String, CreateTeamMemberRequest> getTeamMembers() |
+| `TeamMembers` | [`Map<String, CreateTeamMemberRequest>`](../../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). | Map<String, CreateTeamMemberRequest> getTeamMembers() |
 
 ## Example (as JSON)