Merge pull request #139 from square/release/2024-12-18

Generated PR for Release: 2024-12-18
square · Dec 18, 2024 · bea143b · bea143b
2 parents 4d75295 + df5fe25
commit bea143b
Show file tree

Hide file tree

Showing 40 changed files with 1,180 additions and 277 deletions.
diff --git a/doc/api/payments.md b/doc/api/payments.md
@@ -41,7 +41,10 @@ def list_payments(self,
                  limit=None,
                  is_offline_payment=False,
                  offline_begin_time=None,
-                 offline_end_time=None)
+                 offline_end_time=None,
+                 updated_at_begin_time=None,
+                 updated_at_end_time=None,
+                 sort_field=None)
 ```
 
 ## Parameters
@@ -50,7 +53,7 @@ def list_payments(self,
 |  --- | --- | --- | --- |
 | `begin_time` | `str` | 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. |
 | `end_time` | `str` | 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. |
-| `sort_order` | `str` | 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). |
+| `sort_order` | `str` | 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` | `str` | 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). |
 | `location_id` | `str` | 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\|int` | Query, Optional | The exact amount in the `total_money` for a payment. |
@@ -60,6 +63,9 @@ def list_payments(self,
 | `is_offline_payment` | `bool` | Query, Optional | Whether the payment was taken offline or not.<br>**Default**: `False` |
 | `offline_begin_time` | `str` | 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. |
 | `offline_end_time` | `str` | 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. |
+| `updated_at_begin_time` | `str` | 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. |
+| `updated_at_end_time` | `str` | 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. |
+| `sort_field` | [`str (Payment Sort Field)`](../../doc/models/payment-sort-field.md) | Query, Optional | The field used to sort results by. The default is `CREATED_AT`. |
 
 ## Response Type
 

diff --git a/doc/api/team.md b/doc/api/team.md
@@ -13,6 +13,10 @@ team_api = client.team
 * [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)
@@ -63,6 +67,28 @@ body = {
                 'YSGH2WBKG94QZ',
                 'GA2Y9HSJ8KRYT'
             ]
+        },
+        'wage_setting': {
+            'job_assignments': [
+                {
+                    'pay_type': 'SALARY',
+                    'annual_rate': {
+                        'amount': 3000000,
+                        'currency': 'USD'
+                    },
+                    'weekly_hours': 40,
+                    'job_id': 'FjS8x95cqHiMenw4f1NAUH4P'
+                },
+                {
+                    'pay_type': 'HOURLY',
+                    'hourly_rate': {
+                        'amount': 2000,
+                        'currency': 'USD'
+                    },
+                    'job_id': 'VDNpRv8da51NU8qZFC5zDWpF'
+                }
+            ],
+            'is_overtime_exempt': True
         }
     }
 }
@@ -215,13 +241,162 @@ elif result.is_error():
 ```
 
 
+# List Jobs
+
+Lists jobs in a seller account. Results are sorted by title in ascending order.
+
+```python
+def list_jobs(self,
+             cursor=None)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `cursor` | `str` | 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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`List Jobs Response`](../../doc/models/list-jobs-response.md).
+
+## Example Usage
+
+```python
+result = team_api.list_jobs()
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# 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.
+
+```python
+def create_job(self,
+              body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Create Job Request`](../../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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Create Job Response`](../../doc/models/create-job-response.md).
+
+## Example Usage
+
+```python
+body = {
+    'job': {
+        'title': 'Cashier',
+        'is_tip_eligible': True
+    },
+    'idempotency_key': 'idempotency-key-0'
+}
+
+result = team_api.create_job(body)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# Retrieve Job
+
+Retrieves a specified job.
+
+```python
+def retrieve_job(self,
+                job_id)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `job_id` | `str` | Template, Required | The ID of the job to retrieve. |
+
+## Response Type
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Retrieve Job Response`](../../doc/models/retrieve-job-response.md).
+
+## Example Usage
+
+```python
+job_id = 'job_id2'
+
+result = team_api.retrieve_job(job_id)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# 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.
+
+```python
+def update_job(self,
+              job_id,
+              body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `job_id` | `str` | Template, Required | The ID of the job to update. |
+| `body` | [`Update Job Request`](../../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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Update Job Response`](../../doc/models/update-job-response.md).
+
+## Example Usage
+
+```python
+job_id = 'job_id2'
+
+body = {
+    'job': {
+        'title': 'Cashier 1',
+        'is_tip_eligible': True
+    }
+}
+
+result = team_api.update_job(
+    job_id,
+    body
+)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
 # 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.
 
 ```python
 def search_team_members(self,
@@ -356,8 +531,11 @@ elif result.is_error():
 # 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.
 
 ```python
 def retrieve_wage_setting(self,
@@ -391,10 +569,13 @@ elif result.is_error():
 # 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.
 
 ```python
 def update_wage_setting(self,
@@ -422,19 +603,19 @@ body = {
     'wage_setting': {
         'job_assignments': [
             {
-                'job_title': 'Manager',
                 'pay_type': 'SALARY',
+                'job_title': 'Manager',
                 'annual_rate': {
                     'amount': 3000000,
                     'currency': 'USD'
                 },
                 'weekly_hours': 40
             },
             {
-                'job_title': 'Cashier',
                 'pay_type': 'HOURLY',
+                'job_title': 'Cashier',
                 'hourly_rate': {
-                    'amount': 1200,
+                    'amount': 2000,
                     'currency': 'USD'
                 }
             }

diff --git a/doc/client.md b/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*: `'2024-11-20'` |
+| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2024-12-18'` |
 | `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='2024-11-20',
+    square_version='2024-12-18',
     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='2024-11-20',
+    square_version='2024-12-18',
     bearer_auth_credentials=BearerAuthCredentials(
         access_token='AccessToken'
     ),

diff --git a/doc/models/bulk-create-team-members-request.md b/doc/models/bulk-create-team-members-request.md
@@ -11,7 +11,7 @@ Represents a bulk create request for `TeamMember` objects.
 
 | Name | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `team_members` | [`Dict Str Create Team Member Request`](../../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. |
+| `team_members` | [`Dict Str Create Team Member Request`](../../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). |
 
 ## Example (as JSON)