Merge pull request #82 from square/release/17.1.0.20220120

Generated PR for Release: 17.1.0.20220120

Author: jguze

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
 

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

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
 ```
 

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,

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'] = []
 

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,

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,

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

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()

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)