Skip to content

Commit

Permalink
Release 2024-12-18
Browse files Browse the repository at this point in the history
  • Loading branch information
autobot committed Dec 18, 2024
1 parent f591cd5 commit 0456b5c
Show file tree
Hide file tree
Showing 57 changed files with 3,114 additions and 386 deletions.
12 changes: 9 additions & 3 deletions doc/api/payments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |
Expand All @@ -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

Expand All @@ -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 -> {
Expand Down
213 changes: 201 additions & 12 deletions doc/api/team.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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();

Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand All @@ -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()
Expand Down
6 changes: 3 additions & 3 deletions doc/client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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"
)
Expand All @@ -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"
)
Expand Down
2 changes: 1 addition & 1 deletion doc/models/bulk-create-team-members-request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Loading

0 comments on commit 0456b5c

Please sign in to comment.