Merge pull request #130 from square/eden/update-list-payment-refunds

feat: Add additional `updatedAtBeginTime`, `updatedAtEndTime`, and `sortField` query parameters to `listPaymentRefunds` endpoint.

Author: mikekono

doc/api/refunds.md

@@ -10,18 +10,18 @@ RefundsApi refundsApi = client.getRefundsApi();
 
 ## Methods
 
-* [List Payment Refunds](../../doc/api/refunds.md#list-payment-refunds)
-* [Refund Payment](../../doc/api/refunds.md#refund-payment)
+* [List Payment Refunds](../../doc/api/refunds.md#list-payment-refunds)
+* [Refund Payment](../../doc/api/refunds.md#refund-payment)
 * [Get Payment Refund](../../doc/api/refunds.md#get-payment-refund)
 
 
 # List Payment Refunds
 
-Retrieves a list of refunds for the account making the request.
-
-Results are eventually consistent, and new refunds or changes to refunds might take several
-seconds to appear.
-
+Retrieves a list of refunds for the account making the request.
+
+Results are eventually consistent, and new refunds or changes to refunds might take several
+seconds to appear.
+
 The maximum results per page is 100.
 
 ```java
@@ -33,7 +33,10 @@ CompletableFuture<ListPaymentRefundsResponse> listPaymentRefundsAsync(
     final String locationId,
     final String status,
     final String sourceType,
-    final Integer limit)
+    final Integer limit,
+    final String updatedAtBeginTime,
+    final String updatedAtEndTime,
+    final String sortField)
 ```
 
 ## Parameters
@@ -48,6 +51,9 @@ CompletableFuture<ListPaymentRefundsResponse> listPaymentRefundsAsync(
 | `status` | `String` | Query, Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](entity:PaymentRefund).<br><br>Default: If omitted, refunds are returned regardless of their status. |
 | `sourceType` | `String` | Query, Optional | If provided, only returns refunds whose payments have the indicated source type.<br>Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.<br>For information about these payment source types, see<br>[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).<br><br>Default: If omitted, refunds are returned regardless of the source type. |
 | `limit` | `Integer` | Query, Optional | The maximum number of results to be returned in a single page.<br><br>It is possible to receive fewer results than the specified limit on a given page.<br><br>If the supplied value is greater than 100, no more than 100 results are returned.<br><br>Default: 100 |
+| `updatedAtBeginTime` | `string` | Query, Optional | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: if omitted, the time range starts at `beginTime`. |
+| `updatedAtEndTime` | `string` | Query, Optional | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: The current time. |
+| `sortField` | `string` | Query, Optional | The field used to sort results by. The default is `CREATED_AT`.<br>Current values include `CREATED_AT` and `UPDATED_AT`.<br> |
 
 ## Response Type
 
@@ -56,22 +62,22 @@ CompletableFuture<ListPaymentRefundsResponse> listPaymentRefundsAsync(
 ## Example Usage
 
 ```java
-refundsApi.listPaymentRefundsAsync(null, null, null, null, null, null, null, null).thenAccept(result -> {
-    // TODO success callback handler
-    System.out.println(result);
-}).exceptionally(exception -> {
-    // TODO failure callback handler
-    exception.printStackTrace();
-    return null;
+refundsApi.listPaymentRefundsAsync(null, null, null, null, null, null, null, null, null, null, null).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
 });
 ```
 
 
 # Refund Payment
 
-Refunds a payment. You can refund the entire payment amount or a
-portion of it. You can use this endpoint to refund a card payment or record a
-refund of a cash or external payment. For more information, see
+Refunds a payment. You can refund the entire payment amount or a
+portion of it. You can use this endpoint to refund a card payment or record a
+refund of a cash or external payment. For more information, see
 [Refund Payment](https://developer.squareup.com/docs/payments-api/refund-payments).
 
 ```java
@@ -92,28 +98,28 @@ CompletableFuture<RefundPaymentResponse> refundPaymentAsync(
 ## Example Usage
 
 ```java
-RefundPaymentRequest body = new RefundPaymentRequest.Builder(
-    "9b7f2dcf-49da-4411-b23e-a2d6af21333a",
-    new Money.Builder()
-        .amount(1000L)
-        .currency("USD")
-        .build()
-)
-.appFeeMoney(new Money.Builder()
-        .amount(10L)
-        .currency("USD")
-        .build())
-.paymentId("R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY")
-.reason("Example")
-.build();
-
-refundsApi.refundPaymentAsync(body).thenAccept(result -> {
-    // TODO success callback handler
-    System.out.println(result);
-}).exceptionally(exception -> {
-    // TODO failure callback handler
-    exception.printStackTrace();
-    return null;
+RefundPaymentRequest body = new RefundPaymentRequest.Builder(
+    "9b7f2dcf-49da-4411-b23e-a2d6af21333a",
+    new Money.Builder()
+        .amount(1000L)
+        .currency("USD")
+        .build()
+)
+.appFeeMoney(new Money.Builder()
+        .amount(10L)
+        .currency("USD")
+        .build())
+.paymentId("R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY")
+.reason("Example")
+.build();
+
+refundsApi.refundPaymentAsync(body).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
 });
 ```
 
@@ -140,15 +146,15 @@ CompletableFuture<GetPaymentRefundResponse> getPaymentRefundAsync(
 ## Example Usage
 
 ```java
-String refundId = "refund_id4";
-
-refundsApi.getPaymentRefundAsync(refundId).thenAccept(result -> {
-    // TODO success callback handler
-    System.out.println(result);
-}).exceptionally(exception -> {
-    // TODO failure callback handler
-    exception.printStackTrace();
-    return null;
+String refundId = "refund_id4";
+
+refundsApi.getPaymentRefundAsync(refundId).thenAccept(result -> {
+    // TODO success callback handler
+    System.out.println(result);
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    exception.printStackTrace();
+    return null;
 });
 ```
 

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*: `"2025-01-23"` |
+| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2025-02-20"` |
 | `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("2025-01-23")
+    .squareVersion("2025-02-20")
     .bearerAuthCredentials(new BearerAuthModel.Builder(
             "AccessToken"
         )
@@ -45,7 +45,7 @@ public class Program {
         SquareClient client = new SquareClient.Builder()
             .httpClientConfig(configBuilder -> configBuilder
                     .timeout(0))
-            .squareVersion("2025-01-23")
+            .squareVersion("2025-02-20")
             .bearerAuthCredentials(new BearerAuthModel.Builder(
                     "AccessToken"
                 )

doc/models/list-payment-refunds-request.md

@@ -1,9 +1,9 @@
 
 # List Payment Refunds Request
 
-Describes a request to list refunds using
-[ListPaymentRefunds](../../doc/api/refunds.md#list-payment-refunds).
-
+Describes a request to list refunds using
+[ListPaymentRefunds](../../doc/api/refunds.md#list-payment-refunds).
+
 The maximum results per page is 100.
 
 ## Structure
@@ -22,6 +22,9 @@ The maximum results per page is 100.
 | `Status` | `String` | Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](entity:PaymentRefund).<br><br>Default: If omitted, refunds are returned regardless of their status. | String getStatus() |
 | `SourceType` | `String` | Optional | If provided, only returns refunds whose payments have the indicated source type.<br>Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.<br>For information about these payment source types, see<br>[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).<br><br>Default: If omitted, refunds are returned regardless of the source type. | String getSourceType() |
 | `Limit` | `Integer` | Optional | The maximum number of results to be returned in a single page.<br><br>It is possible to receive fewer results than the specified limit on a given page.<br><br>If the supplied value is greater than 100, no more than 100 results are returned.<br><br>Default: 100 | Integer getLimit() |
+| `UpdatedAtBeginTime` | `string` | Optional | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: if omitted, the time range starts at `beginTime`. |
+| `UpdatedAtEndTime` | `string` | Optional | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: The current time. |
+| `SortField` | `string` | Optional | The field used to sort results by. The default is `CREATED_AT`.<br>Current values include `CREATED_AT` and `UPDATED_AT`.<br> |
 
 ## Example (as JSON)
 

src/main/java/com/squareup/square/SquareClient.java

@@ -157,7 +157,7 @@ public final class SquareClient implements SquareClientInterface {
 
     private static final CompatibilityFactory compatibilityFactory = new CompatibilityFactoryImpl();
 
-    private static String userAgent = "Square-Java-SDK/43.0.0.20250123 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}";
+    private static String userAgent = "Square-Java-SDK/43.1.0.20250220 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}";
 
     /**
      * Current API environment.
@@ -719,7 +719,7 @@ public String getAccessToken() {
      * @return sdkVersion
      */
     public String getSdkVersion() {
-        return "43.0.0.20250123";
+        return "43.1.0.20250220";
     }
 
     /**
@@ -832,7 +832,7 @@ public static class Builder {
 
         private Environment environment = Environment.PRODUCTION;
         private String customUrl = "https://connect.squareup.com";
-        private String squareVersion = "2025-01-23";
+        private String squareVersion = "2025-02-20";
         private HttpClient httpClient;
         private Headers additionalHeaders = new Headers();
         private String userAgentDetail = null;

src/main/java/com/squareup/square/api/DefaultRefundsApi.java

@@ -63,6 +63,14 @@ public DefaultRefundsApi(GlobalConfiguration globalConfig) {
      *         page. It is possible to receive fewer results than the specified limit on a given
      *         page. If the supplied value is greater than 100, no more than 100 results are
      *         returned. Default: 100
+     * @param  updatedAtBeginTime  Optional parameter: Indicates the start of the time range to retrieve each
+     *         `PaymentRefund` for, in RFC 3339 format. The range is determined using the
+     *         `updated_at` field for each `PaymentRefund`. Default: if omitted, the time range starts at `beginTime`.
+     * @param  updatedAtEndTime  Optional parameter: Indicates the end of the time range to retrieve each
+     *         `PaymentRefund` for, in RFC 3339 format. The range is determined using the
+     *         `updated_at` field for each `PaymentRefund`. Default: The current time.
+     * @param  sortField  Optional parameter: The field used to sort results by. The default is `CREATED_AT`.
+     *         Current values include `CREATED_AT` and `UPDATED_AT`.
      * @return    Returns the ListPaymentRefundsResponse response from the API call
      * @throws    ApiException    Represents error response from the server.
      * @throws    IOException    Signals that an I/O exception of some sort has occurred.
@@ -75,9 +83,12 @@ public ListPaymentRefundsResponse listPaymentRefunds(
             final String locationId,
             final String status,
             final String sourceType,
-            final Integer limit) throws ApiException, IOException {
+            final Integer limit,
+            final String updatedAtBeginTime,
+            final String updatedAtEndTime,
+            final String sortField) throws ApiException, IOException {
         return prepareListPaymentRefundsRequest(beginTime, endTime, sortOrder, cursor, locationId,
-                status, sourceType, limit).execute();
+                status, sourceType, limit, updatedAtBeginTime, updatedAtEndTime, sortField).execute();
     }
 
     /**
@@ -113,6 +124,14 @@ public ListPaymentRefundsResponse listPaymentRefunds(
      *         page. It is possible to receive fewer results than the specified limit on a given
      *         page. If the supplied value is greater than 100, no more than 100 results are
      *         returned. Default: 100
+     * @param  updatedAtBeginTime  Optional parameter: Indicates the start of the time range to retrieve each
+     *         `PaymentRefund` for, in RFC 3339 format. The range is determined using the
+     *         `updated_at` field for each `PaymentRefund`. Default: if omitted, the time range starts at `beginTime`.
+     * @param  updatedAtEndTime  Optional parameter: Indicates the end of the time range to retrieve each
+     *         `PaymentRefund` for, in RFC 3339 format. The range is determined using the
+     *         `updated_at` field for each `PaymentRefund`. Default: The current time.
+     * @param  sortField  Optional parameter: The field used to sort results by. The default is `CREATED_AT`.
+     *         Current values include `CREATED_AT` and `UPDATED_AT`.
      * @return    Returns the ListPaymentRefundsResponse response from the API call
      */
     public CompletableFuture<ListPaymentRefundsResponse> listPaymentRefundsAsync(
@@ -123,10 +142,13 @@ public CompletableFuture<ListPaymentRefundsResponse> listPaymentRefundsAsync(
             final String locationId,
             final String status,
             final String sourceType,
-            final Integer limit) {
+            final Integer limit,
+            final String updatedAtBeginTime,
+            final String updatedAtEndTime,
+            final String sortField) {
         try { 
             return prepareListPaymentRefundsRequest(beginTime, endTime, sortOrder, cursor, locationId,
-            status, sourceType, limit).executeAsync(); 
+            status, sourceType, limit, updatedAtBeginTime, updatedAtEndTime, sortField).executeAsync(); 
         } catch (Exception e) {  
             throw new CompletionException(e); 
         }
@@ -143,7 +165,10 @@ private ApiCall<ListPaymentRefundsResponse, ApiException> prepareListPaymentRefu
             final String locationId,
             final String status,
             final String sourceType,
-            final Integer limit) throws IOException {
+            final Integer limit,
+            final String updatedAtBeginTime,
+            final String updatedAtEndTime,
+            final String sortField) throws IOException {
         return new ApiCall.Builder<ListPaymentRefundsResponse, ApiException>()
                 .globalConfig(getGlobalConfiguration())
                 .requestBuilder(requestBuilder -> requestBuilder
@@ -165,6 +190,12 @@ private ApiCall<ListPaymentRefundsResponse, ApiException> prepareListPaymentRefu
                                 .value(sourceType).isRequired(false))
                         .queryParam(param -> param.key("limit")
                                 .value(limit).isRequired(false))
+                        .queryParam(param -> param.key("updated_at_begin_time")
+                                .value(updatedAtBeginTime).isRequired(false))
+                        .queryParam(param -> param.key("updated_at_end_time")
+                                .value(updatedAtEndTime).isRequired(false))
+                        .queryParam(param -> param.key("sort_field")
+                                .value(sortField).isRequired(false))
                         .headerParam(param -> param.key("accept").value("application/json"))
                         .withAuth(auth -> auth
                                 .add("global"))