Merge pull request #66 from square/release/17.0.0.20211117

Generated PR for Release: 17.0.0.20211117

Author: Xiao Hu

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Change Log
 
+## Version 17.0.0.20211117 (2021-11-17)
+## API updates
+
+* **Cards API.** The [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/card) object and webhook response body for all webhooks are updated updated with fields.
+  * Added the [Card.merchant_id](https://developer.squareup.com/reference/square_2021-11-17/objects/Card#definition__property-merchant_id) field to identify the Square seller that stored the payment card on file. 
+  * Added a [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/Card) object to the response bodies of all [Cards API webhooks](https://developer.squareup.com/docs/webhooks/v2webhook-events-tech-ref#cards-api). The `Card` is added as a child of the `data.object` field in all webhook responses.
+
+* **Bookings API.** The new [ListBookings](https://developer.squareup.com/reference/square_2021-11-17/bookings-api/list-bookings) endpoint supports browsing a collection of bookings of a seller. For more information, see [Use the Bookings API: list bookings.](https://developer.squareup.com/docs/bookings-api/use-the-api#list-bookings) 
+
+* **Subscriptions API.** Introduced the new [actions framework](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) representing scheduled, future changes to subscriptions. 
+  *  The new [PauseSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/pause-subscription) endpoint supports temporarily pausing a subscription. Calling this endpoint schedules a new `PAUSE` action.
+  * The new [SwapPlan](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/swap-plan) endpoint supports changing the subscription plan associated with a single customer. Calling this endpoint schedules a new `SWAP_PLAN` action.
+  * The new [DeleteSubscriptionAction](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/delete-subscription-action) endpoint supports deleting a scheduled action.
+  * The [ResumeSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/resume-subscription) endpoint has been updated to support resuming a paused subscription. Calling this endpoint schedules a new `RESUME` action. 
+  * The [CancelSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/cancel-subscription) endpoint now schedules a new `CANCEL` action.
+  * Added an optional `include` body parameter to the [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/search-subscriptions) endpoint. Include `actions` in the request to return all [actions](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) associated with the subscriptions.
+
+## Documentation Update
+
+* **Migration  Guides.**
+  * [Migrate from the Connect V1 Refunds API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-refunds)  The topic is updated to include information to migrate from  the v1 ListRefunds endpoint to the appropriate Square API counterparts.  
+  * [Migrate from the Connect V1 Payments API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-payments)  The topic provides developers information to migrate from the Connect V1 Payments API to the appropriate Square API counterparts.  
+
+  Code that relies on these V1 API endpoints must be updated to avoid breaking when these APIs reach retirement.
+
+
 ## Version 16.0.0.20211020 (2021-10-20)
 ## API updates
 * **Transactions API.** Three previously deprecated endpoints (`ListRefunds`,  `Charge`, and `CreateRefund`) in the [Transactions API](https://developer.squareup.com/reference/square_2021-10-20/transactions-api) are removed from Square API version 2021-10-20 and later. These endpoints will work if you are using Square API versions prior to 2021-10-20. However, these endpoints will eventually be retired from all Square versions. 

README.md

@@ -33,7 +33,7 @@ Install the client dynamically by adding a dependency to the POM for your projec
 <dependency>
     <groupId>com.squareup</groupId>
     <artifactId>square</artifactId>
-    <version>16.0.0.20211020</version>
+    <version>17.0.0.20211117</version>
 </dependency>
 ```
 
@@ -42,7 +42,7 @@ Install the client dynamically by adding a dependency to the POM for your projec
 Install the client by adding the following dependency to the build file for your project:
 
 ```
-implementation "com.squareup:square:16.0.0.20211020"
+implementation "com.squareup:square:17.0.0.20211117"
 ```
 
 ## API documentation

doc/api/bookings.md

@@ -10,6 +10,7 @@ BookingsApi bookingsApi = client.getBookingsApi();
 
 ## Methods
 
+* [List Bookings](/doc/api/bookings.md#list-bookings)
 * [Create Booking](/doc/api/bookings.md#create-booking)
 * [Search Availability](/doc/api/bookings.md#search-availability)
 * [Retrieve Business Booking Profile](/doc/api/bookings.md#retrieve-business-booking-profile)
@@ -20,6 +21,54 @@ BookingsApi bookingsApi = client.getBookingsApi();
 * [Cancel Booking](/doc/api/bookings.md#cancel-booking)
 
 
+# List Bookings
+
+Retrieve a collection of bookings.
+
+```java
+CompletableFuture<ListBookingsResponse> listBookingsAsync(
+    final Integer limit,
+    final String cursor,
+    final String teamMemberId,
+    final String locationId,
+    final String startAtMin,
+    final String startAtMax)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `limit` | `Integer` | Query, Optional | The maximum number of results per page to return in a paged response. |
+| `cursor` | `String` | Query, Optional | The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results. |
+| `teamMemberId` | `String` | Query, Optional | The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved. |
+| `locationId` | `String` | Query, Optional | The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved. |
+| `startAtMin` | `String` | Query, Optional | The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used. |
+| `startAtMax` | `String` | Query, Optional | The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used. |
+
+## Response Type
+
+[`ListBookingsResponse`](/doc/models/list-bookings-response.md)
+
+## Example Usage
+
+```java
+Integer limit = 172;
+String cursor = "cursor6";
+String teamMemberId = "team_member_id0";
+String locationId = "location_id4";
+String startAtMin = "start_at_min8";
+String startAtMax = "start_at_max8";
+
+bookingsApi.listBookingsAsync(limit, cursor, teamMemberId, locationId, startAtMin, startAtMax).thenAccept(result -> {
+    // TODO success callback handler
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    return null;
+});
+```
+
+
 # Create Booking
 
 Creates a booking.

doc/api/disputes.md

@@ -48,7 +48,7 @@ CompletableFuture<ListDisputesResponse> listDisputesAsync(
 
 ```java
 String cursor = "cursor6";
-String states = "EVIDENCE_REQUIRED";
+String states = "INQUIRY_EVIDENCE_REQUIRED";
 String locationId = "location_id4";
 
 disputesApi.listDisputesAsync(cursor, states, locationId).thenAccept(result -> {

doc/api/gift-card-activities.md

@@ -37,13 +37,13 @@ CompletableFuture<ListGiftCardActivitiesResponse> listGiftCardActivitiesAsync(
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `giftCardId` | `String` | Query, Optional | If you provide a gift card ID, the endpoint returns activities that belong<br>to the specified gift card. Otherwise, the endpoint returns all gift card activities for<br>the seller. |
-| `type` | `String` | Query, Optional | If you provide a type, the endpoint returns gift card activities of this type.<br>Otherwise, the endpoint returns all types of gift card activities. |
-| `locationId` | `String` | Query, Optional | If you provide a location ID, the endpoint returns gift card activities for that location.<br>Otherwise, the endpoint returns gift card activities for all locations. |
-| `beginTime` | `String` | Query, Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.<br>Inclusive. Default: The current time minus one year. |
-| `endTime` | `String` | Query, Optional | The timestamp for the end of the reporting period, in RFC 3339 format.<br>Inclusive. Default: The current time. |
-| `limit` | `Integer` | Query, Optional | If you provide a limit value, the endpoint returns the specified number<br>of results (or less) per page. A maximum value is 100. The default value is 50. |
-| `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>If you do not provide the cursor, the call returns the first page of the results. |
+| `giftCardId` | `String` | Query, Optional | If a gift card ID is provided, the endpoint returns activities related<br>to the specified gift card. Otherwise, the endpoint returns all gift card activities for<br>the seller. |
+| `type` | `String` | Query, Optional | If a [type](/doc/models/gift-card-activity-type.md) is provided, the endpoint returns gift card activities of the specified type.<br>Otherwise, the endpoint returns all types of gift card activities. |
+| `locationId` | `String` | Query, Optional | If a location ID is provided, the endpoint returns gift card activities for the specified location.<br>Otherwise, the endpoint returns gift card activities for all locations. |
+| `beginTime` | `String` | Query, Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.<br>This start time is inclusive. The default value is the current time minus one year. |
+| `endTime` | `String` | Query, Optional | The timestamp for the end of the reporting period, in RFC 3339 format.<br>This end time is inclusive. The default value is the current time. |
+| `limit` | `Integer` | Query, Optional | If a limit is provided, the endpoint returns the specified number<br>of results (or fewer) per page. The maximum value is 100. The default value is 50.<br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `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>If a cursor is not provided, the endpoint returns the first page of the results.<br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
 | `sortOrder` | `String` | Query, Optional | The order in which the endpoint returns the activities, based on `created_at`.<br><br>- `ASC` - Oldest to newest.<br>- `DESC` - Newest to oldest (default). |
 
 ## Response Type

doc/api/gift-cards.md

@@ -37,11 +37,11 @@ CompletableFuture<ListGiftCardsResponse> listGiftCardsAsync(
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `type` | `String` | Query, Optional | If a type is provided, gift cards of this type are returned<br>(see [GiftCardType](/doc/models/gift-card-type.md)).<br>If no type is provided, it returns gift cards of all types. |
-| `state` | `String` | Query, Optional | If the state is provided, it returns the gift cards in the specified state<br>(see [GiftCardStatus](/doc/models/gift-card-status.md)).<br>Otherwise, it returns the gift cards of all states. |
-| `limit` | `Integer` | Query, Optional | If a value is provided, it returns only that number of results per page.<br>The maximum number of results allowed per page is 50. The default value is 30. |
-| `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>If a cursor is not provided, it returns the first page of the results.<br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
-| `customerId` | `String` | Query, Optional | If a value is provided, returns only the gift cards linked to the specified customer |
+| `type` | `String` | Query, Optional | If a [type](/doc/models/gift-card-type.md) is provided, the endpoint returns gift cards of the specified type.<br>Otherwise, the endpoint returns gift cards of all types. |
+| `state` | `String` | Query, Optional | If a [state](/doc/models/gift-card-status.md) is provided, the endpoint returns the gift cards in the specified state.<br>Otherwise, the endpoint returns the gift cards of all states. |
+| `limit` | `Integer` | Query, Optional | If a limit is provided, the endpoint returns only the specified number of results per page.<br>The maximum value is 50. The default value is 30.<br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `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>If a cursor is not provided, the endpoint returns the first page of the results.<br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `customerId` | `String` | Query, Optional | If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. |
 
 ## Response Type
 
@@ -153,7 +153,7 @@ giftCardsApi.retrieveGiftCardFromGANAsync(body).thenAccept(result -> {
 
 # Retrieve Gift Card From Nonce
 
-Retrieves a gift card using a nonce (a secure token) that represents the gift card.
+Retrieves a gift card using a secure payment token that represents the gift card.
 
 ```java
 CompletableFuture<RetrieveGiftCardFromNonceResponse> retrieveGiftCardFromNonceAsync(
@@ -188,7 +188,7 @@ giftCardsApi.retrieveGiftCardFromNonceAsync(body).thenAccept(result -> {
 
 # Link Customer to Gift Card
 
-Links a customer to a gift card
+Links a customer to a gift card, which is also referred to as adding a card on file.
 
 ```java
 CompletableFuture<LinkCustomerToGiftCardResponse> linkCustomerToGiftCardAsync(
@@ -200,7 +200,7 @@ CompletableFuture<LinkCustomerToGiftCardResponse> linkCustomerToGiftCardAsync(
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `giftCardId` | `String` | Template, Required | The ID of the gift card to link. |
+| `giftCardId` | `String` | Template, Required | The ID of the gift card to be linked. |
 | `body` | [`LinkCustomerToGiftCardRequest`](/doc/models/link-customer-to-gift-card-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
@@ -226,7 +226,7 @@ giftCardsApi.linkCustomerToGiftCardAsync(giftCardId, body).thenAccept(result ->
 
 # Unlink Customer From Gift Card
 
-Unlinks a customer from a gift card
+Unlinks a customer from a gift card, which is also referred to as removing a card on file.
 
 ```java
 CompletableFuture<UnlinkCustomerFromGiftCardResponse> unlinkCustomerFromGiftCardAsync(
@@ -238,7 +238,7 @@ CompletableFuture<UnlinkCustomerFromGiftCardResponse> unlinkCustomerFromGiftCard
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `giftCardId` | `String` | Template, Required | - |
+| `giftCardId` | `String` | Template, Required | The ID of the gift card to be unlinked. |
 | `body` | [`UnlinkCustomerFromGiftCardRequest`](/doc/models/unlink-customer-from-gift-card-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

doc/api/refunds.md

@@ -109,9 +109,9 @@ Money bodyAppFeeMoney = new Money.Builder()
     .build();
 RefundPaymentRequest body = new RefundPaymentRequest.Builder(
         "9b7f2dcf-49da-4411-b23e-a2d6af21333a",
-        bodyAmountMoney,
-        "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY")
+        bodyAmountMoney)
     .appFeeMoney(bodyAppFeeMoney)
+    .paymentId("R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY")
     .reason("Example")
     .paymentVersionToken("payment_version_token6")
     .teamMemberId("team_member_id4")

doc/api/sites.md

@@ -11,7 +11,7 @@ SitesApi sitesApi = client.getSitesApi();
 
 # List Sites
 
-Lists the Square Online sites that belong to a seller.
+Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the `created_at` date.
 
 __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).