Merge pull request #68 from square/release/13.1.0.20210818

Generated PR for Release: 13.1.0.20210818

Author: Wolfgang Schuster

CHANGELOG.md

@@ -1,51 +1,33 @@
 # Change Log
 
-## Version 13.0.0.20210721 (2021-07-21)
-## SDK updates
-  * The [Square Python SDK](https://developer.squareup.com/docs/sdks/python) now requires Python 3.7 or later, if Python 3 is used. With Python 2, the minimum version remains at 2.7.
+## Version 13.1.0.20210818 (2021-08-18)
+## API updates 
 
-## API updates
-
-* **Orders  API:** 
-  * [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge) object. Added a new field, `type`. It identifies the service charge type.
-
-  * [OrderQuantityUnit](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderQuantityUnit), 
-    [OrderLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItem), 
-    [OrderLineItemDiscount](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemDiscount), 
-    [OrderLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemModifier), 
-    [OrderLineItemTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemTax), 
-    [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge), 
-    [OrderReturnLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItem), 
-    [OrderReturnLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItemModifier), 
-    [OrderReturnServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnServiceCharge), 
-    [OrderReturnTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnTax), and 
-    [OrderReturnDiscount](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnDiscount) objects. Added a new field, `catalog_version`.
-* **Locations API:**
-  * [Location](https://developer.squareup.com/reference/square_2021-07-21/objects/Location) object. Added a new field `tax_ids` of type `TaxIds`. In the current implementation, sellers in Ireland and France can configure tax IDs during the onboarding process. They can also provide the information later by updating the location information in the Seller Dashboard. These tax IDs appear in this field.
+* **Customers API:**
+  * [Customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) object. The `version` field has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. This field represents the current version of the customer profile and enables optimistic concurrency control. For more information, see [Customer profile versions and optimistic concurrency support.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-profile-versions-and-optimistic-concurrency-support) 
+  * [ListCustomers](https://developer.squareup.com/reference/square_2021-08-18/customers-api/list-customers) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response.
 
-* **Loyalty API:**
-  * As of July 15, 2021, the country in which the seller’s Square account is activated determines whether Square uses pretax or post-tax purchase amounts to calculate accrued points. This change supports consumption tax models, such as value-added tax (VAT). Previously, point accrual was based on pretax purchase amounts only. This change does not affect the existing point balance of loyalty accounts. For more information, see [Availability of Square Loyalty.](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-market-availability)
+* **Customer Groups API:**
+  * [ListCustomerGroups](https://developer.squareup.com/reference/square_2021-08-18/customer-groups-api/list-customer-groups) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response.
 
-* **Payments API:** 
-  * [UpdatePayment](https://developer.squareup.com/reference/square_2021-07-21/payments-api/update-payment). The endpoint has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. Also, you can now update gift card payments (similar to card, cash, and external payments).
+* **Customer Segments API:**
+  * [ListCustomerSegments](https://developer.squareup.com/reference/square_2021-08-18/customer-segments-api/list-customer-segments) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response.
 
-* **Subscriptions API:**
-  * The [Subscriptions API](https://developer.squareup.com/docs/subscriptions-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state.
-  * [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2021-07-21/objects/CatalogSubscriptionPlan) object. The `name` and `price` are now write-once fields. You specify these values at the time  of creating a plan. After the plan is created, these fields cannot be updated. This makes a subscription plan immutable. 
+* **Invoices API:**
+  * Square Invoices Plus is a monthly subscription plan that allows access to premium invoice features. After Invoices Plus is launched in September 2021, a subscription will be required to create invoices with custom fields and installment payments. For more information, including how to handle new errors, see [Premium features available with Invoices Plus.](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)
 
-* **Inventory API:**
-  * [RetrieveInventoryTransfer.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Transfer) This new endpoint is introduced to support the retrieval of inventory transfer.
-  * [RetrieveInventoryChanges.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Changes) This endpoint is deprecated. Its support ends when it is retired in about 12 months.  
-  * The following endpoints have updated URLs to conform to the standard REST API convention. For more information about migrating deprecated URLs to updated URLs in your application, see [Inventory API: Migrate to Updated API Entities.](https://developer.squareup.com/docs/inventory-api/migrate-to-updated-api-entities)
-    * [RetrieveInventoryAdjustment](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Adjustment)
-    * [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Change-Inventory)
-    * [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Changes) 
-    * [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Counts)
-    * [RetrieveInventoryPhysicalCount](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Physical-Count)
+* **Loyalty API:**
+  * [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccount) object. Added a new `expiring_point_deadlines` field that specifies when points in the account balance are scheduled to expire. This field contains a list of [LoyaltyAccountExpiringPointDeadline](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccountExpiringPointDeadline) objects. For more information, see [Expiring points.](https://developer.squareup.com/docs/loyalty-api/overview#expiring-points)
 
 ## Documentation updates
-* **Webhooks.** Revised the steps and descriptions for creating and using webhooks. For more information, see [Webhooks Overview.](https://developer.squareup.com/docs/webhooks/overview)
 
+* [App Marketplace.](https://developer.squareup.com/docs/app-marketplace) Added the following topics:
+  * [How to apply.](https://developer.squareup.com/docs/app-marketplace#how-to-apply) Documented the process to list an application on the Square App Marketplace.
+  * [App Marketplace API Usage Requirements.](https://developer.squareup.com/docs/app-marketplace/requirements) Added a topic that describes a set of API usage requirements and recommendations for partner applications.   
+
+* [Automatic communications from Square about invoices.](https://developer.squareup.com/docs/invoices-api/overview#automatic-communication-from-square-to-customers) Documented the invoice-related communications sent from Square to customers and sellers. 
+
+* [Snippets best practices.](https://developer.squareup.com/docs/snippets-api/overview#best-practices) Documented best practices and additional requirements for snippets and applications that integrate with the Snippets API.
 
 
 ## Version 12.0.0.20210616 (2021-06-16)

README.md

@@ -46,9 +46,6 @@ pip install -r test-requirements.txt
 * [Disputes]
 * [Checkout]
 * [Apple Pay]
-* [Cards]
-
-### Terminal
 * [Terminal]
 
 ### Orders
@@ -72,22 +69,19 @@ pip install -r test-requirements.txt
 ### Loyalty
 * [Loyalty]
 
-### Gift Cards
-* [Gift Cards]
-* [Gift Card Activities]
-
 ### Bookings
 * [Bookings]
 
 ### Business
 * [Merchants]
 * [Locations]
 * [Devices]
-* [Cash Drawers]
 
 ### Team
 * [Team]
+* [Employees]
 * [Labor]
+* [Cash Drawers]
 
 ### Financials
 * [Bank Accounts]
@@ -101,7 +95,6 @@ pip install -r test-requirements.txt
 * [OAuth]
 
 ### Deprecated APIs
-* [Employees]
 * [V1 Employees]
 * [V1 Transactions]
 * [V1 Items]
@@ -416,6 +409,3 @@ You can also use the Square API to create applications or services that work wit
 [OAuth overview]: https://developer.squareup.com/docs/oauth-api/what-it-does
 [Sites]: doc/api/sites.md
 [Snippets]: doc/api/snippets.md
-[Cards]: doc/api/cards.md
-[Gift Cards]: doc/api/gift-cards.md
-[Gift Card Activities]: doc/api/gift-card-activities.md

doc/api/customer-groups.md

@@ -23,14 +23,16 @@ Retrieves the list of customer groups of a business.
 
 ```python
 def list_customer_groups(self,
-                        cursor=None)
+                        cursor=None,
+                        limit=None)
 ```
 
 ## Parameters
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `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 your original query.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `limit` | `int` | Query, Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.<br>The limit is ignored if it is less than 1 or greater than 50. The default value is 50.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
 
 ## Response Type
 
@@ -40,8 +42,9 @@ def list_customer_groups(self,
 
 ```python
 cursor = 'cursor6'
+limit = 172
 
-result = customer_groups_api.list_customer_groups(cursor)
+result = customer_groups_api.list_customer_groups(cursor, limit)
 
 if result.is_success():
     print(result.body)

doc/api/customer-segments.md

@@ -20,14 +20,16 @@ Retrieves the list of customer segments of a business.
 
 ```python
 def list_customer_segments(self,
-                          cursor=None)
+                          cursor=None,
+                          limit=None)
 ```
 
 ## Parameters
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `cursor` | `string` | Query, Optional | A pagination cursor returned by previous calls to `ListCustomerSegments`.<br>This cursor is used to retrieve the next set of query results.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `limit` | `int` | Query, Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.<br>The limit is ignored if it is less than 1 or greater than 50. The default value is 50.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
 
 ## Response Type
 
@@ -37,8 +39,9 @@ def list_customer_segments(self,
 
 ```python
 cursor = 'cursor6'
+limit = 172
 
-result = customer_segments_api.list_customer_segments(cursor)
+result = customer_segments_api.list_customer_segments(cursor, limit)
 
 if result.is_success():
     print(result.body)

doc/api/customers.md

@@ -33,6 +33,7 @@ profiles can take closer to one minute or longer, especially during network inci
 ```python
 def list_customers(self,
                   cursor=None,
+                  limit=None,
                   sort_field=None,
                   sort_order=None)
 ```
@@ -42,8 +43,9 @@ def list_customers(self,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `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 your original query.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
-| `sort_field` | [`str (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Query, Optional | Indicates how customers should be sorted.<br><br>Default: `DEFAULT`. |
-| `sort_order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | Indicates whether customers should be sorted in ascending (`ASC`) or<br>descending (`DESC`) order.<br><br>Default: `ASC`. |
+| `limit` | `int` | Query, Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.<br>The limit is ignored if it is less than 1 or greater than 100. The default value is 100.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `sort_field` | [`str (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Query, Optional | Indicates how customers should be sorted.<br><br>The default value is `DEFAULT`. |
+| `sort_order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | Indicates whether customers should be sorted in ascending (`ASC`) or<br>descending (`DESC`) order.<br><br>The default value is `ASC`. |
 
 ## Response Type
 
@@ -53,10 +55,11 @@ def list_customers(self,
 
 ```python
 cursor = 'cursor6'
+limit = 172
 sort_field = 'DEFAULT'
 sort_order = 'DESC'
 
-result = customers_api.list_customers(cursor, sort_field, sort_order)
+result = customers_api.list_customers(cursor, limit, sort_field, sort_order)
 
 if result.is_success():
     print(result.body)

doc/api/gift-cards.md

@@ -67,8 +67,8 @@ elif result.is_error():
 
 # Create Gift Card
 
-Creates a digital gift card. You must activate the gift card before
-it can be used. For more information, see
+Creates a digital gift card or registers a physical (plastic) gift card. You must activate the gift card before
+it can be used for payment. For more information, see
 [Selling gift cards](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#selling-square-gift-cards).
 
 ```python