square · jguze · Jan 20, 2022 · Jan 20, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,7 @@
 # Change Log
 
+For general API and SDK changelogs, see  [Square APIs and SDKs Release Notes](https://developer.squareup.com/docs/changelog/connect).
+
 ## Version 17.0.0.20211215 (2021-12-15)
 ### API updates
 

diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright 2021 Square, Inc.
+Copyright 2022 Square, Inc.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ python setup.py install --user
 In Python 2, you can install via pip:
 
 ```sh
-pip install -r requirement.txt
+pip install -r requirements.txt
 pip install -r test-requirements.txt
 ```
 

diff --git a/doc/api/bookings.md b/doc/api/bookings.md
@@ -25,6 +25,9 @@ bookings_api = client.bookings
 
 Retrieve a collection of bookings.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+
 ```python
 def list_bookings(self,
                  limit=None,
@@ -73,6 +76,9 @@ elif result.is_error():
 
 Creates a booking.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+
 ```python
 def create_booking(self,
                   body)
@@ -113,6 +119,9 @@ elif result.is_error():
 
 Searches for availabilities for booking.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+
 ```python
 def search_availability(self,
                        body)
@@ -206,8 +215,8 @@ def list_team_member_booking_profiles(self,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `bookable_only` | `bool` | Query, Optional | Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`).<br>**Default**: `False` |
-| `limit` | `int` | Query, Optional | The maximum number of results to return. |
-| `cursor` | `string` | Query, Optional | The cursor for paginating through the results. |
+| `limit` | `int` | Query, Optional | The maximum number of results 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. |
 | `location_id` | `string` | Query, Optional | Indicates whether to include only team members enabled at the given location in the returned result. |
 
 ## Response Type
@@ -268,6 +277,9 @@ elif result.is_error():
 
 Retrieves a booking.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+
 ```python
 def retrieve_booking(self,
                     booking_id)
@@ -301,6 +313,9 @@ elif result.is_error():
 
 Updates a booking.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+
 ```python
 def update_booking(self,
                   booking_id,
@@ -344,6 +359,9 @@ elif result.is_error():
 
 Cancels an existing booking.
 
+To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.  
+To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+
 ```python
 def cancel_booking(self,
                   booking_id,

diff --git a/doc/api/checkout.md b/doc/api/checkout.md
@@ -160,8 +160,6 @@ body['pre_populate_shipping_address']['sublocality'] = 'sublocality0'
 body['pre_populate_shipping_address']['administrative_district_level_1'] = 'CA'
 body['pre_populate_shipping_address']['postal_code'] = '94103'
 body['pre_populate_shipping_address']['country'] = 'US'
-body['pre_populate_shipping_address']['first_name'] = 'Jane'
-body['pre_populate_shipping_address']['last_name'] = 'Doe'
 body['redirect_url'] = 'https://merchant.website.com/order-confirm'
 body['additional_recipients'] = []
 

diff --git a/doc/api/locations.md b/doc/api/locations.md
@@ -18,7 +18,7 @@ locations_api = client.locations
 
 # List Locations
 
-Provides details about all of the seller's locations,
+Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api),
 including those with an inactive status.
 
 ```python
@@ -131,7 +131,7 @@ elif result.is_error():
 
 # Update Location
 
-Updates a location.
+Updates a [location](https://developer.squareup.com/docs/locations-api).
 
 ```python
 def update_location(self,

diff --git a/doc/api/loyalty.md b/doc/api/loyalty.md
@@ -164,9 +164,6 @@ Adds points to a loyalty account.
   [CalculateLoyaltyPoints](/doc/api/loyalty.md#calculate-loyalty-points) to compute the points  
   that you provide to this endpoint.
 
-__Note:__ The country of the seller's Square account determines whether tax is included in the purchase amount when accruing points for spend-based and visit-based programs.
-For more information, see [Availability of Square Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-market-availability).
-
 ```python
 def accumulate_loyalty_points(self,
                              account_id,
@@ -374,16 +371,15 @@ elif result.is_error():
 
 Calculates the points a purchase earns.
 
-- If you are using the Orders API to manage orders, you provide `order_id` in the request. The
+- If you are using the Orders API to manage orders, you provide the `order_id` in the request. The
   endpoint calculates the points by reading the order.
 - If you are not using the Orders API to manage orders, you provide the purchase amount in
   the request for the endpoint to calculate the points.
 
 An application might call this endpoint to show the points that a buyer can earn with the
 specific purchase.
 
-__Note:__ The country of the seller's Square account determines whether tax is included in the purchase amount when accruing points for spend-based and visit-based programs.
-For more information, see [Availability of Square Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-market-availability).
+For spend-based and visit-based programs, the `tax_mode` setting of the accrual rule indicates how taxes should be treated for loyalty points accrual.
 
 ```python
 def calculate_loyalty_points(self,

diff --git a/doc/api/refunds.md b/doc/api/refunds.md
@@ -46,7 +46,7 @@ def list_payment_refunds(self,
 | `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><br>For more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). |
 | `location_id` | `string` | Query, Optional | Limit results to the location supplied. By default, results are returned<br>for all locations associated with the seller. |
 | `status` | `string` | Query, Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](/doc/models/payment-refund.md).<br><br>Default: If omitted, refunds are returned regardless of their status. |
-| `source_type` | `string` | Query, Optional | If provided, only refunds with the given source type are returned.<br><br>- `CARD` - List refunds only for payments where `CARD` was specified as the payment<br>  source.<br><br>Default: If omitted, refunds are returned regardless of the source type. |
+| `source_type` | `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` | `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 |
 
 ## Response Type

diff --git a/doc/client.md b/doc/client.md
@@ -5,8 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `string` | Square Connect API versions<br>*Default*: `'2021-12-15'` |
-| `access_token` | `string` | The OAuth 2.0 Access Token to use for API requests. |
+| `square_version` | `string` | Square Connect API versions<br>*Default*: `'2022-01-20'` |
 | `custom_url` | `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`** |
 | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests |
@@ -25,8 +24,7 @@ The API client can be initialized as follows:
 from square.client import Client
 
 client = Client(
-    square_version='2021-12-15',
-    access_token='AccessToken',
+    square_version='2022-01-20',
     environment='production',
     custom_url = 'https://connect.squareup.com',)
 ```
@@ -50,8 +48,7 @@ API calls return an `ApiResponse` object that includes the following fields:
 from square.client import Client
 
 client = Client(
-    square_version='2021-12-15',
-    access_token='AccessToken',)
+    square_version='2022-01-20',)
 
 locations_api = client.locations
 result = locations_api.list_locations()

diff --git a/doc/models/address.md b/doc/models/address.md
@@ -1,34 +1,8 @@
 
 # Address
 
-Represents a postal address in a country. The address format is based
-on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
-see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
-This format has dedicated fields for four address components: postal code,
-locality (city), administrative district (state, prefecture, or province), and
-sublocality (town or village). These components have dedicated fields in the
-`Address` object because software sometimes behaves differently based on them.
-For example, sales tax software may charge different amounts of sales tax
-based on the postal code, and some software is only available in
-certain states due to compliance reasons.
-
-For the remaining address components, the `Address` type provides the
-`address_line_1` and `address_line_2` fields for free-form data entry.
-These fields are free-form because the remaining address components have
-too many variations around the world and typical software does not parse
-these components. These fields enable users to enter anything they want.
-
-Note that, in the current implementation, all other `Address` type fields are blank.
-These include `address_line_3`, `sublocality_2`, `sublocality_3`,
-`administrative_district_level_2`, `administrative_district_level_3`,
-`first_name`, `last_name`, and `organization`.
-
-When it comes to localization, the seller's language preferences
-(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
-are ignored for addresses. Even though Square products (such as Square Point of Sale
-and the Seller Dashboard) mostly use a seller's language preference in
-communication, when it comes to addresses, they will use English for a US address,
-Japanese for an address in Japan, and so on.
+Represents a postal address in a country.
+For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
 
 ## Structure
 
@@ -41,18 +15,11 @@ Japanese for an address in Japan, and so on.
 | `address_line_1` | `string` | Optional | The first line of the address.<br><br>Fields that start with `address_line` provide the address's most specific<br>details, like street number, street name, and building name. They do *not*<br>provide less specific details like city, state/province, or country (these<br>details are provided in other fields). |
 | `address_line_2` | `string` | Optional | The second line of the address, if any. |
 | `address_line_3` | `string` | Optional | The third line of the address, if any. |
-| `locality` | `string` | Optional | The city or town of the address. |
+| `locality` | `string` | Optional | The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). |
 | `sublocality` | `string` | Optional | A civil region within the address's `locality`, if any. |
-| `sublocality_2` | `string` | Optional | A civil region within the address's `sublocality`, if any. |
-| `sublocality_3` | `string` | Optional | A civil region within the address's `sublocality_2`, if any. |
-| `administrative_district_level_1` | `string` | Optional | A civil entity within the address's country. In the US, this<br>is the state. |
-| `administrative_district_level_2` | `string` | Optional | A civil entity within the address's `administrative_district_level_1`.<br>In the US, this is the county. |
-| `administrative_district_level_3` | `string` | Optional | A civil entity within the address's `administrative_district_level_2`,<br>if any. |
-| `postal_code` | `string` | Optional | The address's postal code. |
+| `administrative_district_level_1` | `string` | Optional | A civil entity within the address's country. In the US, this<br>is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). |
+| `postal_code` | `string` | Optional | The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). |
 | `country` | [`str (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.<br>Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). |
-| `first_name` | `string` | Optional | Optional first name when it's representing recipient. |
-| `last_name` | `string` | Optional | Optional last name when it's representing recipient. |
-| `organization` | `string` | Optional | Optional organization name when it's representing recipient. |
 
 ## Example (as JSON)
 

diff --git a/doc/models/appointment-segment.md b/doc/models/appointment-segment.md
@@ -15,6 +15,9 @@ Defines an appointment segment of a booking.
 | `service_variation_id` | `string` | Required | The ID of the [CatalogItemVariation](/doc/models/catalog-item-variation.md) object representing the service booked in this segment.<br>**Constraints**: *Minimum Length*: `1` |
 | `team_member_id` | `string` | Required | The ID of the [TeamMember](/doc/models/team-member.md) object representing the team member booked in this segment.<br>**Constraints**: *Minimum Length*: `1` |
 | `service_variation_version` | `long\|int` | Required | The current version of the item variation representing the service booked in this segment. |
+| `intermission_minutes` | `int` | Optional | Time between the end of this segment and the beginning of the subsequent segment. |
+| `any_team_member` | `bool` | Optional | Whether the customer accepts any team member, instead of a specific one, to serve this segment. |
+| `resource_ids` | `List of string` | Optional | The IDs of the seller-accessible resources used for this appointment segment. |
 
 ## Example (as JSON)
 
@@ -23,7 +26,13 @@ Defines an appointment segment of a booking.
   "duration_minutes": 144,
   "service_variation_id": "service_variation_id6",
   "team_member_id": "team_member_id0",
-  "service_variation_version": 56
+  "service_variation_version": 56,
+  "intermission_minutes": 62,
+  "any_team_member": false,
+  "resource_ids": [
+    "resource_ids0",
+    "resource_ids1"
+  ]
 }
 ```
 
diff --git a/doc/models/availability.md b/doc/models/availability.md
@@ -1,7 +1,7 @@
 
 # Availability
 
-Describes a slot available for booking, encapsulating appointment segments, the location and starting time.
+Defines an appointment slot that encapsulates the appointment segments, location and  starting time avaialable for booking.
 
 ## Structure
 
@@ -26,7 +26,13 @@ Describes a slot available for booking, encapsulating appointment segments, the
       "duration_minutes": 4,
       "service_variation_id": "service_variation_id4",
       "team_member_id": "team_member_id0",
-      "service_variation_version": 172
+      "service_variation_version": 172,
+      "intermission_minutes": 178,
+      "any_team_member": false,
+      "resource_ids": [
+        "resource_ids0",
+        "resource_ids1"
+      ]
     }
   ]
 }

diff --git a/doc/models/bank-account.md b/doc/models/bank-account.md
@@ -1,10 +1,6 @@
 
 # Bank Account
 
-Represents a bank account. For more information about
-linking a bank account to a Square account, see
-[Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api).
-
 ## Structure
 
 `Bank Account`

diff --git a/doc/models/booking-booking-source.md b/doc/models/booking-booking-source.md
@@ -0,0 +1,18 @@
+
+# Booking Booking Source
+
+Supported sources a booking was created from.
+
+## Enumeration
+
+`Booking Booking Source`
+
+## Fields
+
+| Name | Description |
+|  --- | --- |
+| `FIRST_PARTY_MERCHANT` | The booking was created by a seller from a Square Appointments application, such as the Square Appointments Dashboard or a Square Appointments mobile app. |
+| `FIRST_PARTY_BUYER` | The booking was created by a buyer from a Square Appointments application, such as Square Online Booking Site. |
+| `THIRD_PARTY_BUYER` | The booking was created by a buyer created from a third-party application. |
+| `API` | The booking was created by a seller or a buyer from the Square Bookings API. |
+
diff --git a/doc/models/booking-creator-details-creator-type.md b/doc/models/booking-creator-details-creator-type.md
@@ -0,0 +1,16 @@
+
+# Booking Creator Details Creator Type
+
+Supported types of a booking creator.
+
+## Enumeration
+
+`Booking Creator Details Creator Type`
+
+## Fields
+
+| Name | Description |
+|  --- | --- |
+| `TEAM_MEMBER` | The creator is of the seller type. |
+| `CUSTOMER` | The creator is of the buyer type. |
+
diff --git a/doc/models/booking-creator-details.md b/doc/models/booking-creator-details.md
@@ -0,0 +1,27 @@
+
+# Booking Creator Details
+
+Information about a booking creator.
+
+## Structure
+
+`Booking Creator Details`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `creator_type` | [`str (Booking Creator Details Creator Type)`](/doc/models/booking-creator-details-creator-type.md) | Optional | Supported types of a booking creator. |
+| `team_member_id` | `string` | Optional | The ID of the team member who created the booking, when the booking creator is of the `TEAM_MEMBER` type.<br>Access to this field requires seller-level permissions. |
+| `customer_id` | `string` | Optional | The ID of the customer who created the booking, when the booking creator is of the `CUSTOMER` type.<br>Access to this field requires seller-level permissions. |
+
+## Example (as JSON)
+
+```json
+{
+  "creator_type": "TEAM_MEMBER",
+  "team_member_id": "team_member_id0",
+  "customer_id": "customer_id8"
+}
+```
+