Skip to content

Commit bea143b

Browse files
mikekonomikekono
authored
Merge pull request #139 from square/release/2024-12-18
Generated PR for Release: 2024-12-18
2 parents 4d75295 + df5fe25 commit bea143b

40 files changed

+1180
-277
lines changed

‎doc/api/payments.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,10 @@ def list_payments(self,
4141
limit=None,
4242
is_offline_payment=False,
4343
offline_begin_time=None,
44-
offline_end_time=None)
44+
offline_end_time=None,
45+
updated_at_begin_time=None,
46+
updated_at_end_time=None,
47+
sort_field=None)
4548
```
4649

4750
## Parameters
@@ -50,7 +53,7 @@ def list_payments(self,
5053
| --- | --- | --- | --- |
5154
| `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. |
5255
| `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. |
53-
| `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). |
56+
| `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). |
5457
| `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). |
5558
| `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. |
5659
| `total` | `long\|int` | Query, Optional | The exact amount in the `total_money` for a payment. |
@@ -60,6 +63,9 @@ def list_payments(self,
6063
| `is_offline_payment` | `bool` | Query, Optional | Whether the payment was taken offline or not.<br>**Default**: `False` |
6164
| `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. |
6265
| `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. |
66+
| `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. |
67+
| `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. |
68+
| `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`. |
6369

6470
## Response Type
6571

‎doc/api/team.md

Lines changed: 193 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ team_api = client.team
1313
* [Create Team Member](../../doc/api/team.md#create-team-member)
1414
* [Bulk Create Team Members](../../doc/api/team.md#bulk-create-team-members)
1515
* [Bulk Update Team Members](../../doc/api/team.md#bulk-update-team-members)
16+
* [List Jobs](../../doc/api/team.md#list-jobs)
17+
* [Create Job](../../doc/api/team.md#create-job)
18+
* [Retrieve Job](../../doc/api/team.md#retrieve-job)
19+
* [Update Job](../../doc/api/team.md#update-job)
1620
* [Search Team Members](../../doc/api/team.md#search-team-members)
1721
* [Retrieve Team Member](../../doc/api/team.md#retrieve-team-member)
1822
* [Update Team Member](../../doc/api/team.md#update-team-member)
@@ -63,6 +67,28 @@ body = {
6367
'YSGH2WBKG94QZ',
6468
'GA2Y9HSJ8KRYT'
6569
]
70+
},
71+
'wage_setting': {
72+
'job_assignments': [
73+
{
74+
'pay_type': 'SALARY',
75+
'annual_rate': {
76+
'amount': 3000000,
77+
'currency': 'USD'
78+
},
79+
'weekly_hours': 40,
80+
'job_id': 'FjS8x95cqHiMenw4f1NAUH4P'
81+
},
82+
{
83+
'pay_type': 'HOURLY',
84+
'hourly_rate': {
85+
'amount': 2000,
86+
'currency': 'USD'
87+
},
88+
'job_id': 'VDNpRv8da51NU8qZFC5zDWpF'
89+
}
90+
],
91+
'is_overtime_exempt': True
6692
}
6793
}
6894
}
@@ -215,13 +241,162 @@ elif result.is_error():
215241
```
216242

217243

244+
# List Jobs
245+
246+
Lists jobs in a seller account. Results are sorted by title in ascending order.
247+
248+
```python
249+
def list_jobs(self,
250+
cursor=None)
251+
```
252+
253+
## Parameters
254+
255+
| Parameter | Type | Tags | Description |
256+
| --- | --- | --- | --- |
257+
| `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). |
258+
259+
## Response Type
260+
261+
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).
262+
263+
## Example Usage
264+
265+
```python
266+
result = team_api.list_jobs()
267+
268+
if result.is_success():
269+
print(result.body)
270+
elif result.is_error():
271+
print(result.errors)
272+
```
273+
274+
275+
# Create Job
276+
277+
Creates a job in a seller account. A job defines a title and tip eligibility. Note that
278+
compensation is defined in a [job assignment](../../doc/models/job-assignment.md) in a team member's wage setting.
279+
280+
```python
281+
def create_job(self,
282+
body)
283+
```
284+
285+
## Parameters
286+
287+
| Parameter | Type | Tags | Description |
288+
| --- | --- | --- | --- |
289+
| `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. |
290+
291+
## Response Type
292+
293+
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).
294+
295+
## Example Usage
296+
297+
```python
298+
body = {
299+
'job': {
300+
'title': 'Cashier',
301+
'is_tip_eligible': True
302+
},
303+
'idempotency_key': 'idempotency-key-0'
304+
}
305+
306+
result = team_api.create_job(body)
307+
308+
if result.is_success():
309+
print(result.body)
310+
elif result.is_error():
311+
print(result.errors)
312+
```
313+
314+
315+
# Retrieve Job
316+
317+
Retrieves a specified job.
318+
319+
```python
320+
def retrieve_job(self,
321+
job_id)
322+
```
323+
324+
## Parameters
325+
326+
| Parameter | Type | Tags | Description |
327+
| --- | --- | --- | --- |
328+
| `job_id` | `str` | Template, Required | The ID of the job to retrieve. |
329+
330+
## Response Type
331+
332+
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).
333+
334+
## Example Usage
335+
336+
```python
337+
job_id = 'job_id2'
338+
339+
result = team_api.retrieve_job(job_id)
340+
341+
if result.is_success():
342+
print(result.body)
343+
elif result.is_error():
344+
print(result.errors)
345+
```
346+
347+
348+
# Update Job
349+
350+
Updates the title or tip eligibility of a job. Changes to the title propagate to all
351+
`JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference the job ID. Changes to
352+
tip eligibility propagate to all `TeamMemberWage` objects that reference the job ID.
353+
354+
```python
355+
def update_job(self,
356+
job_id,
357+
body)
358+
```
359+
360+
## Parameters
361+
362+
| Parameter | Type | Tags | Description |
363+
| --- | --- | --- | --- |
364+
| `job_id` | `str` | Template, Required | The ID of the job to update. |
365+
| `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. |
366+
367+
## Response Type
368+
369+
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).
370+
371+
## Example Usage
372+
373+
```python
374+
job_id = 'job_id2'
375+
376+
body = {
377+
'job': {
378+
'title': 'Cashier 1',
379+
'is_tip_eligible': True
380+
}
381+
}
382+
383+
result = team_api.update_job(
384+
job_id,
385+
body
386+
)
387+
388+
if result.is_success():
389+
print(result.body)
390+
elif result.is_error():
391+
print(result.errors)
392+
```
393+
394+
218395
# Search Team Members
219396

220397
Returns a paginated list of `TeamMember` objects for a business.
221-
The list can be filtered by the following:
222-
223-
- location IDs
224-
- `status`
398+
The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` status, or whether
399+
the team member is the Square account owner.
225400

226401
```python
227402
def search_team_members(self,
@@ -356,8 +531,11 @@ elif result.is_error():
356531
# Retrieve Wage Setting
357532

358533
Retrieves a `WageSetting` object for a team member specified
359-
by `TeamMember.id`.
360-
Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).
534+
by `TeamMember.id`. For more information, see
535+
[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).
536+
537+
Square recommends using [RetrieveTeamMember](../../doc/api/team.md#retrieve-team-member) or [SearchTeamMembers](../../doc/api/team.md#search-team-members)
538+
to get this information directly from the `TeamMember.wage_setting` field.
361539

362540
```python
363541
def retrieve_wage_setting(self,
@@ -391,10 +569,13 @@ elif result.is_error():
391569
# Update Wage Setting
392570

393571
Creates or updates a `WageSetting` object. The object is created if a
394-
`WageSetting` with the specified `team_member_id` does not exist. Otherwise,
572+
`WageSetting` with the specified `team_member_id` doesn't exist. Otherwise,
395573
it fully replaces the `WageSetting` object for the team member.
396-
The `WageSetting` is returned on a successful update.
397-
Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).
574+
The `WageSetting` is returned on a successful update. For more information, see
575+
[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).
576+
577+
Square recommends using [CreateTeamMember](../../doc/api/team.md#create-team-member) or [UpdateTeamMember](../../doc/api/team.md#update-team-member)
578+
to manage the `TeamMember.wage_setting` field directly.
398579

399580
```python
400581
def update_wage_setting(self,
@@ -422,19 +603,19 @@ body = {
422603
'wage_setting': {
423604
'job_assignments': [
424605
{
425-
'job_title': 'Manager',
426606
'pay_type': 'SALARY',
607+
'job_title': 'Manager',
427608
'annual_rate': {
428609
'amount': 3000000,
429610
'currency': 'USD'
430611
},
431612
'weekly_hours': 40
432613
},
433614
{
434-
'job_title': 'Cashier',
435615
'pay_type': 'HOURLY',
616+
'job_title': 'Cashier',
436617
'hourly_rate': {
437-
'amount': 1200,
618+
'amount': 2000,
438619
'currency': 'USD'
439620
}
440621
}

‎doc/client.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
55

66
| Parameter | Type | Description |
77
| --- | --- | --- |
8-
| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2024-11-20'` |
8+
| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2024-12-18'` |
99
| `custom_url` | `str` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `'https://connect.squareup.com'` |
1010
| `environment` | `string` | The API environment. <br> **Default: `production`** |
1111
| `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:
2424

2525
```python
2626
client = Client(
27-
square_version='2024-11-20',
27+
square_version='2024-12-18',
2828
bearer_auth_credentials=BearerAuthCredentials(
2929
access_token='AccessToken'
3030
),
@@ -53,7 +53,7 @@ from square.http.auth.o_auth_2 import BearerAuthCredentials
5353
from square.client import Client
5454

5555
client = Client(
56-
square_version='2024-11-20',
56+
square_version='2024-12-18',
5757
bearer_auth_credentials=BearerAuthCredentials(
5858
access_token='AccessToken'
5959
),

‎doc/models/bulk-create-team-members-request.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Represents a bulk create request for `TeamMember` objects.
1111

1212
| Name | Type | Tags | Description |
1313
| --- | --- | --- | --- |
14-
| `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. |
14+
| `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). |
1515

1616
## Example (as JSON)
1717

0 commit comments

Comments
 (0)