Merge pull request #87 from square/release/24.0.0.20220921

Author: joanc-sq

README.md

@@ -8,6 +8,14 @@
 
 Use this library to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.
 
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Quickstart](#quickstart)
+* [Usage](#usage)
+* [Tests](#tests)
+* [SDK Reference](#sdk-reference)
+* [Deprecated APIs](#deprecated-apis)
+
 ## Requirements
 
 Use of the Square Java SDK requires:
@@ -109,16 +117,17 @@ mvn test
 * [Sites]
 * [Snippets]
 
-### Authorization APIs
+### Authorization
 * [Mobile Authorization]
 * [OAuth]
 
-### Deprecated APIs
-* [Employees]
-* [V1 Employees]
-* [V1 Transactions]
-* [V1 Items]
-* [Transactions]
+## Deprecated APIs
+
+The following Square APIs are [deprecated](https://developer.squareup.com/docs/build-basics/api-lifecycle):
+ 
+* [Employees] - replaced by the [Team] API. For more information, see [Migrate from the Employees API](https://developer.squareup.com/docs/team/migrate-from-v2-employees).
+ 
+* [Transactions] - replaced by the [Orders] and [Payments] APIs.  For more information, see [Migrate from the Transactions API](https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api).
 
 #### Usage Notes for V1 Transactions
 
@@ -150,7 +159,6 @@ You'll also need to provide logic to handle paginated results.  For more informa
 [Catalog]: doc/api/catalog.md
 [Customers]: doc/api/customers.md
 [Customer Custom Attributes]: doc/api/customer-custom-attributes.md
-[Employees]: doc/api/employees.md
 [Inventory]: doc/api/inventory.md
 [Labor]: doc/api/labor.md
 [Loyalty]: doc/api/loyalty.md
@@ -164,14 +172,12 @@ You'll also need to provide logic to handle paginated results.  For more informa
 [Subscriptions]: doc/api/subscriptions.md
 [Mobile Authorization]: doc/api/mobile-authorization.md
 [OAuth]: doc/api/o-auth.md
-[V1 Employees]: doc/api/v1-employees.md
-[V1 Transactions]: doc/api/v1-transactions.md
-[V1 Items]: doc/api/v1-items.md
 [Team]: doc/api/team.md
-[Transactions]: doc/api/transactions.md
 [Sites]: doc/api/sites.md
 [Snippets]: doc/api/snippets.md
 [Cards]: doc/api/cards.md
 [Payouts]: doc/api/payouts.md
 [Gift Cards]: doc/api/gift-cards.md
 [Gift Card Activities]: doc/api/gift-card-activities.md
+[Employees]: doc/api/employees.md
+[Transactions]: doc/api/transactions.md

doc/api/apple-pay.md

@@ -18,8 +18,10 @@ an Apple Pay enabled domain.
 This endpoint provides an easy way for platform developers to bulk activate
 Apple Pay on the Web with Square for merchants using their platform.
 
-To learn more about Web Apple Pay, see
-[Add the Apple Pay on the Web Button](https://developer.squareup.com/docs/payment-form/add-digital-wallets/apple-pay).
+Note: The SqPaymentForm library is deprecated as of May 13, 2021, and will only receive critical security updates until it is retired on October 31, 2022.
+You must migrate your payment form code to the Web Payments SDK to continue using your domain for Apple Pay. For more information on migrating to the Web Payments SDK, see [Migrate to the Web Payments SDK](https://developer.squareup.com/docs/web-payments/migrate).
+
+To learn more about the Web Payments SDK and how to add Apple Pay, see [Take an Apple Pay Payment](https://developer.squareup.com/docs/web-payments/apple-pay).
 
 ```java
 CompletableFuture<RegisterDomainResponse> registerDomainAsync(

doc/api/invoices.md

@@ -141,6 +141,7 @@ Invoice invoice = new Invoice.Builder()
     .acceptedPaymentMethods(invoiceAcceptedPaymentMethods)
     .customFields(invoiceCustomFields)
     .saleOrServiceDate("2030-01-24")
+    .storePaymentMethodEnabled(false)
     .build();
 CreateInvoiceRequest body = new CreateInvoiceRequest.Builder(
         invoice)

doc/api/loyalty.md

@@ -170,7 +170,8 @@ Adds points earned from a purchase to a [loyalty account](../../doc/models/loyal
 - If you are not using the Orders API to manage orders, provide `points` with the number of points to add.
   You must first perform a client-side computation of the points earned from the loyalty program and
   loyalty promotion. For spend-based and visit-based programs, you can call [CalculateLoyaltyPoints](../../doc/api/loyalty.md#calculate-loyalty-points)
-  to compute the points earned from the loyalty program (but not points earned from a loyalty promotion).
+  to compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see
+  [Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).
 
 ```java
 CompletableFuture<AccumulateLoyaltyPointsResponse> accumulateLoyaltyPointsAsync(

doc/api/v1-transactions.md

@@ -10,25 +10,25 @@ V1TransactionsApi v1TransactionsApi = client.getV1TransactionsApi();
 
 ## Methods
 
-* [List Orders](../../doc/api/v1-transactions.md#list-orders)
-* [Retrieve Order](../../doc/api/v1-transactions.md#retrieve-order)
-* [Update Order](../../doc/api/v1-transactions.md#update-order)
-* [List Payments](../../doc/api/v1-transactions.md#list-payments)
-* [Retrieve Payment](../../doc/api/v1-transactions.md#retrieve-payment)
-* [List Refunds](../../doc/api/v1-transactions.md#list-refunds)
-* [Create Refund](../../doc/api/v1-transactions.md#create-refund)
-* [List Settlements](../../doc/api/v1-transactions.md#list-settlements)
-* [Retrieve Settlement](../../doc/api/v1-transactions.md#retrieve-settlement)
+* [V1 List Orders](../../doc/api/v1-transactions.md#v1-list-orders)
+* [V1 Retrieve Order](../../doc/api/v1-transactions.md#v1-retrieve-order)
+* [V1 Update Order](../../doc/api/v1-transactions.md#v1-update-order)
+* [V1 List Payments](../../doc/api/v1-transactions.md#v1-list-payments)
+* [V1 Retrieve Payment](../../doc/api/v1-transactions.md#v1-retrieve-payment)
+* [V1 List Refunds](../../doc/api/v1-transactions.md#v1-list-refunds)
+* [V1 Create Refund](../../doc/api/v1-transactions.md#v1-create-refund)
+* [V1 List Settlements](../../doc/api/v1-transactions.md#v1-list-settlements)
+* [V1 Retrieve Settlement](../../doc/api/v1-transactions.md#v1-retrieve-settlement)
 
 
-# List Orders
+# V1 List Orders
 
 **This endpoint is deprecated.**
 
 Provides summary information for a merchant's online store orders.
 
 ```java
-CompletableFuture<List<V1Order>> listOrdersAsync(
+CompletableFuture<List<V1Order>> v1ListOrdersAsync(
     final String locationId,
     final String order,
     final Integer limit,
@@ -53,7 +53,7 @@ CompletableFuture<List<V1Order>> listOrdersAsync(
 ```java
 String locationId = "location_id4";
 
-v1TransactionsApi.listOrdersAsync(locationId, null, null, null).thenAccept(result -> {
+v1TransactionsApi.v1ListOrdersAsync(locationId, null, null, null).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -62,14 +62,14 @@ v1TransactionsApi.listOrdersAsync(locationId, null, null, null).thenAccept(resul
 ```
 
 
-# Retrieve Order
+# V1 Retrieve Order
 
 **This endpoint is deprecated.**
 
 Provides comprehensive information for a single online store order, including the order's history.
 
 ```java
-CompletableFuture<V1Order> retrieveOrderAsync(
+CompletableFuture<V1Order> v1RetrieveOrderAsync(
     final String locationId,
     final String orderId)
 ```
@@ -91,7 +91,7 @@ CompletableFuture<V1Order> retrieveOrderAsync(
 String locationId = "location_id4";
 String orderId = "order_id6";
 
-v1TransactionsApi.retrieveOrderAsync(locationId, orderId).thenAccept(result -> {
+v1TransactionsApi.v1RetrieveOrderAsync(locationId, orderId).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -100,14 +100,14 @@ v1TransactionsApi.retrieveOrderAsync(locationId, orderId).thenAccept(result -> {
 ```
 
 
-# Update Order
+# V1 Update Order
 
 **This endpoint is deprecated.**
 
 Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:
 
 ```java
-CompletableFuture<V1Order> updateOrderAsync(
+CompletableFuture<V1Order> v1UpdateOrderAsync(
     final String locationId,
     final String orderId,
     final V1UpdateOrderRequest body)
@@ -134,7 +134,7 @@ V1UpdateOrderRequest body = new V1UpdateOrderRequest.Builder(
         "REFUND")
     .build();
 
-v1TransactionsApi.updateOrderAsync(locationId, orderId, body).thenAccept(result -> {
+v1TransactionsApi.v1UpdateOrderAsync(locationId, orderId, body).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -143,7 +143,7 @@ v1TransactionsApi.updateOrderAsync(locationId, orderId, body).thenAccept(result
 ```
 
 
-# List Payments
+# V1 List Payments
 
 **This endpoint is deprecated.**
 
@@ -160,7 +160,7 @@ list an offline payment chronologically between online payments that
 were seen in a previous request.
 
 ```java
-CompletableFuture<List<V1Payment>> listPaymentsAsync(
+CompletableFuture<List<V1Payment>> v1ListPaymentsAsync(
     final String locationId,
     final String order,
     final String beginTime,
@@ -192,7 +192,7 @@ CompletableFuture<List<V1Payment>> listPaymentsAsync(
 String locationId = "location_id4";
 Boolean includePartial = false;
 
-v1TransactionsApi.listPaymentsAsync(locationId, null, null, null, null, null, includePartial).thenAccept(result -> {
+v1TransactionsApi.v1ListPaymentsAsync(locationId, null, null, null, null, null, includePartial).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -201,14 +201,14 @@ v1TransactionsApi.listPaymentsAsync(locationId, null, null, null, null, null, in
 ```
 
 
-# Retrieve Payment
+# V1 Retrieve Payment
 
 **This endpoint is deprecated.**
 
 Provides comprehensive information for a single payment.
 
 ```java
-CompletableFuture<V1Payment> retrievePaymentAsync(
+CompletableFuture<V1Payment> v1RetrievePaymentAsync(
     final String locationId,
     final String paymentId)
 ```
@@ -230,7 +230,7 @@ CompletableFuture<V1Payment> retrievePaymentAsync(
 String locationId = "location_id4";
 String paymentId = "payment_id0";
 
-v1TransactionsApi.retrievePaymentAsync(locationId, paymentId).thenAccept(result -> {
+v1TransactionsApi.v1RetrievePaymentAsync(locationId, paymentId).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -239,14 +239,14 @@ v1TransactionsApi.retrievePaymentAsync(locationId, paymentId).thenAccept(result
 ```
 
 
-# List Refunds
+# V1 List Refunds
 
 **This endpoint is deprecated.**
 
 Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.
 
 ```java
-CompletableFuture<List<V1Refund>> listRefundsAsync(
+CompletableFuture<List<V1Refund>> v1ListRefundsAsync(
     final String locationId,
     final String order,
     final String beginTime,
@@ -275,7 +275,7 @@ CompletableFuture<List<V1Refund>> listRefundsAsync(
 ```java
 String locationId = "location_id4";
 
-v1TransactionsApi.listRefundsAsync(locationId, null, null, null, null, null).thenAccept(result -> {
+v1TransactionsApi.v1ListRefundsAsync(locationId, null, null, null, null, null).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -284,7 +284,7 @@ v1TransactionsApi.listRefundsAsync(locationId, null, null, null, null, null).the
 ```
 
 
-# Create Refund
+# V1 Create Refund
 
 **This endpoint is deprecated.**
 
@@ -302,7 +302,7 @@ purposes, you can create fake cash payments in Square Point of Sale and
 refund them.
 
 ```java
-CompletableFuture<V1Refund> createRefundAsync(
+CompletableFuture<V1Refund> v1CreateRefundAsync(
     final String locationId,
     final V1CreateRefundRequest body)
 ```
@@ -328,7 +328,7 @@ V1CreateRefundRequest body = new V1CreateRefundRequest.Builder(
         "reason8")
     .build();
 
-v1TransactionsApi.createRefundAsync(locationId, body).thenAccept(result -> {
+v1TransactionsApi.v1CreateRefundAsync(locationId, body).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -337,7 +337,7 @@ v1TransactionsApi.createRefundAsync(locationId, body).thenAccept(result -> {
 ```
 
 
-# List Settlements
+# V1 List Settlements
 
 **This endpoint is deprecated.**
 
@@ -349,7 +349,7 @@ ranges cannot exceed one year in length.
 information.
 
 ```java
-CompletableFuture<List<V1Settlement>> listSettlementsAsync(
+CompletableFuture<List<V1Settlement>> v1ListSettlementsAsync(
     final String locationId,
     final String order,
     final String beginTime,
@@ -380,7 +380,7 @@ CompletableFuture<List<V1Settlement>> listSettlementsAsync(
 ```java
 String locationId = "location_id4";
 
-v1TransactionsApi.listSettlementsAsync(locationId, null, null, null, null, null, null).thenAccept(result -> {
+v1TransactionsApi.v1ListSettlementsAsync(locationId, null, null, null, null, null, null).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler
@@ -389,7 +389,7 @@ v1TransactionsApi.listSettlementsAsync(locationId, null, null, null, null, null,
 ```
 
 
-# Retrieve Settlement
+# V1 Retrieve Settlement
 
 **This endpoint is deprecated.**
 
@@ -412,7 +412,7 @@ a bank account within 3 business days, but in exceptional cases it may
 take longer.
 
 ```java
-CompletableFuture<V1Settlement> retrieveSettlementAsync(
+CompletableFuture<V1Settlement> v1RetrieveSettlementAsync(
     final String locationId,
     final String settlementId)
 ```
@@ -434,7 +434,7 @@ CompletableFuture<V1Settlement> retrieveSettlementAsync(
 String locationId = "location_id4";
 String settlementId = "settlement_id0";
 
-v1TransactionsApi.retrieveSettlementAsync(locationId, settlementId).thenAccept(result -> {
+v1TransactionsApi.v1RetrieveSettlementAsync(locationId, settlementId).thenAccept(result -> {
     // TODO success callback handler
 }).exceptionally(exception -> {
     // TODO failure callback handler

doc/api/webhook-subscriptions.md

@@ -70,7 +70,7 @@ CompletableFuture<ListWebhookSubscriptionsResponse> listWebhookSubscriptionsAsyn
 | `cursor` | `String` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for your original query.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). |
 | `includeDisabled` | `Boolean` | Query, Optional | Includes disabled [Subscription](../../doc/models/webhook-subscription.md)s.<br>By default, all enabled [Subscription](../../doc/models/webhook-subscription.md)s are returned.<br>**Default**: `false` |
 | `sortOrder` | [`String`](../../doc/models/sort-order.md) | Query, Optional | Sorts the returned list by when the [Subscription](../../doc/models/webhook-subscription.md) was created with the specified order.<br>This field defaults to ASC. |
-| `limit` | `Integer` | Query, Optional | The maximum number of results to be returned in a single page.<br>It is possible to receive fewer results than the specified limit on a given page.<br>The default value of 100 is also the maximum allowed value. If the provided value is greater<br>than 100, it is ignored and the default value is used instead.<br><br>Default: 100 |
+| `limit` | `Integer` | Query, Optional | The maximum number of results to be returned in a single page.<br>It is possible to receive fewer results than the specified limit on a given page.<br>The default value of 100 is also the maximum allowed value.<br><br>Default: 100 |
 
 ## Response Type
 

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*: `"2022-08-23"` |
+| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2022-09-21"` |
 | `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` | `ReadonlyHttpClientConfiguration` | 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("2022-08-23")
+    .squareVersion("2022-09-21")
     .accessToken("AccessToken")
     .environment(Environment.PRODUCTION)
     .customUrl("https://connect.squareup.com")
@@ -45,7 +45,7 @@ public class Program {
         SquareClient client = new SquareClient.Builder()
             .httpClientConfig(configBuilder -> configBuilder
                     .timeout(0))
-            .squareVersion("2022-08-23")
+            .squareVersion("2022-09-21")
             .accessToken("AccessToken")
             .build();
 

doc/models/accumulate-loyalty-points-response.md

@@ -13,7 +13,7 @@ Represents an [AccumulateLoyaltyPoints](../../doc/api/loyalty.md#accumulate-loya
 |  --- | --- | --- | --- | --- |
 | `Errors` | [`List<Error>`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | List<Error> getErrors() |
 | `Event` | [`LoyaltyEvent`](../../doc/models/loyalty-event.md) | Optional | Provides information about a loyalty event.<br>For more information, see [Search for Balance-Changing Loyalty Events](https://developer.squareup.com/docs/loyalty-api/loyalty-events). | LoyaltyEvent getEvent() |
-| `Events` | [`List<LoyaltyEvent>`](../../doc/models/loyalty-event.md) | Optional | The resulting loyalty events. The `ACCUMULATE_POINTS` event is always included.<br>When using the Orders API, the `ACCUMULATE_PROMOTION_POINTS` event is included<br>if the purchase also qualifies for a loyalty promotion. | List<LoyaltyEvent> getEvents() |
+| `Events` | [`List<LoyaltyEvent>`](../../doc/models/loyalty-event.md) | Optional | The resulting loyalty events. If the purchase qualifies for points, the `ACCUMULATE_POINTS` event<br>is always included. When using the Orders API, the `ACCUMULATE_PROMOTION_POINTS` event is included<br>if the purchase also qualifies for a loyalty promotion. | List<LoyaltyEvent> getEvents() |
 
 ## Example (as JSON)