Merge pull request #143 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

@@ -33,7 +33,10 @@ def list_payment_refunds(self,
                         location_id=None,
                         status=None,
                         source_type=None,
-                        limit=None)
+                        limit=None,
+                        updated_at_begin_time=None,
+                        updated_at_end_time=None,
+                        sort_field=None)
 ```
 
 ## Parameters
@@ -48,6 +51,9 @@ def list_payment_refunds(self,
 | `status` | `str` | 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. |
 | `source_type` | `str` | 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` | `int` | 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 |
+| `updated_at_begin_time` | `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 `begin_time`. |
+| `updated_at_end_time` | `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. |
+| `sort_field` | `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
 

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2025-01-23'` |
+| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2025-02-20'` |
 | `custom_url` | `str` | 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`** |
 | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests |
@@ -24,7 +24,7 @@ The API client can be initialized as follows:
 
 ```python
 client = Client(
-    square_version='2025-01-23',
+    square_version='2025-02-20',
     bearer_auth_credentials=BearerAuthCredentials(
         access_token='AccessToken'
     ),
@@ -53,7 +53,7 @@ from square.http.auth.o_auth_2 import BearerAuthCredentials
 from square.client import Client
 
 client = Client(
-    square_version='2025-01-23',
+    square_version='2025-02-20',
     bearer_auth_credentials=BearerAuthCredentials(
         access_token='AccessToken'
     ),

pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools>=61.0"]
 [project]
 name = "squareup"
 description = "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management."
-version = "40.0.0.220250123"
+version = "40.1.0.220250220"
 readme = "README.md"
 requires-python = ">=3.7"
 authors = [{name = "Square Developer Platform", email = "[email protected]"}]

square/api/base_api.py

@@ -22,7 +22,7 @@ class BaseApi(object):
 
     @staticmethod
     def user_agent():
-        return 'Square-Python-SDK/40.0.0.220250123 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
+        return 'Square-Python-SDK/40.1.0.220250220 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
 
     @staticmethod
     def user_agent_parameters():

square/api/refunds_api.py

@@ -1,13 +1,14 @@
 # -*- coding: utf-8 -*-
 
-from square.api_helper import APIHelper
-from square.http.api_response import ApiResponse
-from square.api.base_api import BaseApi
+from apimatic_core.authentication.multiple.single_auth import Single
 from apimatic_core.request_builder import RequestBuilder
 from apimatic_core.response_handler import ResponseHandler
 from apimatic_core.types.parameter import Parameter
+
+from square.api.base_api import BaseApi
+from square.api_helper import APIHelper
+from square.http.api_response import ApiResponse
 from square.http.http_method_enum import HttpMethodEnum
-from apimatic_core.authentication.multiple.single_auth import Single
 
 
 class RefundsApi(BaseApi):
@@ -24,7 +25,10 @@ def list_payment_refunds(self,
                              location_id=None,
                              status=None,
                              source_type=None,
-                             limit=None):
+                             limit=None,
+                             updated_at_begin_time=None,
+                             updated_at_end_time=None,
+                             sort_field=None):
         """Does a GET request to /v2/refunds.
 
         Retrieves a list of refunds for the account making the request.
@@ -71,6 +75,18 @@ def list_payment_refunds(self,
                 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
+            updated_at_begin_time (str, optional): 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
+                `begin_time`.
+            updated_at_end_time (str, optional): 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.
+            sort_field (str, optional): The field used to sort results by. The default
+                is `CREATED_AT`. Current values include `CREATED_AT` and
+                `UPDATED_AT`.
 
         Returns:
             ApiResponse: An object with the response value as well as other
@@ -112,6 +128,15 @@ def list_payment_refunds(self,
             .query_param(Parameter()
                          .key('limit')
                          .value(limit))
+            .query_param(Parameter()
+                         .key('updated_at_begin_time')
+                         .value(updated_at_begin_time))
+            .query_param(Parameter()
+                         .key('updated_at_end_time')
+                         .value(updated_at_end_time))
+            .query_param(Parameter()
+                         .key('sort_field')
+                         .value(sort_field))
             .header_param(Parameter()
                           .key('accept')
                           .value('application/json'))

square/client.py

@@ -55,11 +55,11 @@
 class Client(object):
     @staticmethod
     def sdk_version():
-        return '40.0.0.220250123'
+        return '40.1.0.220250220'
 
     @staticmethod
     def square_version():
-        return '2025-01-23'
+        return '2025-02-20'
 
     def user_agent_detail(self):
         return self.config.user_agent_detail
@@ -238,7 +238,7 @@ def __init__(self, http_client_instance=None,
                  retry_statuses=None, retry_methods=None,
                  environment='production',
                  custom_url='https://connect.squareup.com', access_token=None,
-                 bearer_auth_credentials=None, square_version='2025-01-23',
+                 bearer_auth_credentials=None, square_version='2025-02-20',
                  additional_headers={}, user_agent_detail='', config=None):
         self.config = config or Configuration(
             http_client_instance=http_client_instance,

square/configuration.py

@@ -45,7 +45,7 @@ def __init__(self, http_client_instance=None,
                  retry_statuses=None, retry_methods=None,
                  environment='production',
                  custom_url='https://connect.squareup.com', access_token=None,
-                 bearer_auth_credentials=None, square_version='2025-01-23',
+                 bearer_auth_credentials=None, square_version='2025-02-20',
                  additional_headers={}, user_agent_detail=''):
         if retry_methods is None:
             retry_methods = ['GET', 'PUT']

tests/api/test_refunds_api.py

@@ -3,6 +3,7 @@
 from tests.test_helper import TestHelper
 from tests.api.api_test_base import ApiTestBase
 
+
 class RefundsApiTests(ApiTestBase):
 
     @classmethod
@@ -23,9 +24,12 @@ def test_test_list_payment_refunds(self):
         location_id = None
         status = None
         source_type = None
+        updated_at_begin_time = None
+        updated_at_end_time = None
+        sort_field = None
 
         # Perform the API call through the SDK function
-        result = self.controller.list_payment_refunds(begin_time, end_time, sort_order, cursor, location_id, status, source_type)
+        result = self.controller.list_payment_refunds(begin_time, end_time, sort_order, cursor, location_id, status, source_type, updated_at_begin_time, updated_at_end_time, sort_field)
 
         # Test response code
         self.assertEquals(self.response_catcher.response.status_code, 200)