Merge pull request #81 from square/release/17.0.0.20211215

Generated PR for Release: 17.0.0.20211215

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Change Log
 
+## Version 17.0.0.20211215 (2021-12-15)
+### API updates
+
+* **Invoices API:**
+  * The Invoices API now supports seller accounts in France. For more information, see [International availability and considerations.](https://developer.squareup.com/docs/invoices-api/overview#international-availability-invoices)
+  * France only: [`Invoice`](https://developer.squareup.com/reference/square_2021-12-15/objects/Invoice) object. Added a new `payment_conditions` field, which contains payment terms and conditions that are displayed on the invoice. This field is available only for sellers in France. For more information, see [Payment conditions.](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions)
+
+    Square version 2021-12-15 or higher is required to set this field, but it is returned in `ListInvoices` and `RetrieveInvoice` requests for all Square versions.
+
+* **Cards API**
+  * Added the `CARD_DECLINED_VERIFICATION_REQUIRED` error code to the list of error codes returned by [CreateCard](https://developer.squareup.com/reference/square_2021-12-15/cards-api/CreateCard). 
+* **Catalog API:**
+  * [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/create-catalog-image) endpoint
+    *  Updated to support attaching multiple images to a [Catalogbject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) instance. 
+    *  Added `is_primary` option to let the caller choose to attach an image as the primary image on the object for display with the Square Point of Sale and other first-party Square applications. For more information, see [Upload and Attach Images.](https://developer.squareup.com/docs/catalog-api/upload-and-attach-images)
+  * [CatalogObject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) object
+    * Retired the `image_id` field, used to hold a single image object attached to an image-supporting object of the `ITEM`, `ITEM_VARIATION`, `CATEGORY`, or `MODIFIER_LIST` type, in Square API version 2021-12-15 and later, which supports attachment of multiple images. The `image_id` field is still supported in Square API version prior to 2021-12-15. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview)
+  * [CatalogItem](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItem), [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItemVariation), [CatalogCategory](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogCategory) or [CatalogModifierList](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogModifierList) object
+    *  Added `image_ids` list to hold attached image objects. The first element of `image_ids` list refers to the primary image attached to the catalog object. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview)
+  * [UpdateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/update-catalog-image) endpoint
+    *  Added to support replacing the image file encapsulated by an existing [CatalogImage](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogImage) object. For more information, see [Replace image file on a CatalogImage object.](https://developer.squareup.com/docs/catalog-api/manage-images#replace-the-image-file-of-a-catalogimage-object)
+
+  * [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule) object
+    * Added  [minimum_order_subtotal_money](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule#definition__property-minimum_order_subtotal_money) field to require that the minimum order subtotal be reached before the pricing rule may be applied. 
+
+### Documentation updates
+* Added a new top-level node for Developer Tools. This node includes such features as Sandbox, API Logs, and Webhooks.
+* Added [Webhook Event Logs (beta)](https://developer.squareup.com/docs/devtools/webhook-logs) documentation to the Developer Tools node.
+
+
 ## Version 16.0.0.20211117 (2021-11-17)
 ## API updates
 

doc/api/catalog.md

@@ -14,6 +14,7 @@ catalog_api = client.catalog
 * [Batch Retrieve Catalog Objects](/doc/api/catalog.md#batch-retrieve-catalog-objects)
 * [Batch Upsert Catalog Objects](/doc/api/catalog.md#batch-upsert-catalog-objects)
 * [Create Catalog Image](/doc/api/catalog.md#create-catalog-image)
+* [Update Catalog Image](/doc/api/catalog.md#update-catalog-image)
 * [Catalog Info](/doc/api/catalog.md#catalog-info)
 * [List Catalog](/doc/api/catalog.md#list-catalog)
 * [Upsert Catalog Object](/doc/api/catalog.md#upsert-catalog-object)
@@ -302,6 +303,7 @@ body['batches'][0]['objects'][2]['catalog_v1_ids'][2]['location_id'] = 'location
 body['batches'][0]['objects'][2]['present_at_all_locations'] = True
 body['batches'][0]['objects'][2]['category_data'] = {}
 body['batches'][0]['objects'][2]['category_data']['name'] = 'Beverages'
+body['batches'][0]['objects'][2]['category_data']['image_ids'] = ['image_ids1', 'image_ids2']
 
 body['batches'][0]['objects'].append({})
 body['batches'][0]['objects'][3]['type'] = 'TAX'
@@ -338,9 +340,9 @@ elif result.is_error():
 
 # Create Catalog Image
 
-Uploads an image file to be represented by a [CatalogImage](/doc/models/catalog-image.md) object linked to an existing
-[CatalogObject](/doc/models/catalog-object.md) instance. A call to this endpoint can upload an image, link an image to
-a catalog object, or do both.
+Uploads an image file to be represented by a [CatalogImage](/doc/models/catalog-image.md) object that can be linked to an existing
+[CatalogObject](/doc/models/catalog-object.md) instance. The resulting `CatalogImage` is unattached to any `CatalogObject` if the `object_id`
+is not specified.
 
 This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in
 JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
@@ -385,6 +387,8 @@ request['image']['image_data'] = {}
 request['image']['image_data']['name'] = 'name0'
 request['image']['image_data']['url'] = 'url4'
 request['image']['image_data']['caption'] = 'A picture of a cup of coffee'
+request['image']['image_data']['photo_studio_order_id'] = 'photo_studio_order_id2'
+request['is_primary'] = False
 image_file = FileWrapper(open('dummy_file', 'rb'), 'optional-content-type')
 
 result = catalog_api.create_catalog_image(request, image_file)
@@ -396,6 +400,49 @@ elif result.is_error():
 ```
 
 
+# Update Catalog Image
+
+Uploads a new image file to replace the existing one in the specified [CatalogImage](/doc/models/catalog-image.md) object.
+
+This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in
+JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
+
+```python
+def update_catalog_image(self,
+                        image_id,
+                        request=None,
+                        image_file=None)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `image_id` | `string` | Template, Required | The ID of the `CatalogImage` object to update the encapsulated image file. |
+| `request` | [`Update Catalog Image Request`](/doc/models/update-catalog-image-request.md) | Form, Optional | - |
+| `image_file` | `typing.BinaryIO` | Form, Optional | - |
+
+## Response Type
+
+[`Update Catalog Image Response`](/doc/models/update-catalog-image-response.md)
+
+## Example Usage
+
+```python
+image_id = 'image_id4'
+request = {}
+request['idempotency_key'] = '528dea59-7bfb-43c1-bd48-4a6bba7dd61f86'
+image_file = FileWrapper(open('dummy_file', 'rb'), 'optional-content-type')
+
+result = catalog_api.update_catalog_image(image_id, request, image_file)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
 # Catalog Info
 
 Retrieves information about the Square Catalog API, such as batch size
@@ -423,11 +470,10 @@ elif result.is_error():
 
 # List Catalog
 
-Returns a list of [CatalogObject](/doc/models/catalog-object.md)s that includes
-all objects of a set of desired types (for example, all [CatalogItem](/doc/models/catalog-item.md)
-and [CatalogTax](/doc/models/catalog-tax.md) objects) in the catalog. The `types` parameter
-is specified as a comma-separated list of valid [CatalogObject](/doc/models/catalog-object.md) types:
-`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`.
+Returns a list of all [CatalogObject](/doc/models/catalog-object.md)s of the specified types in the catalog.
+
+The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](/doc/models/catalog-object-type.md) values,
+for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`".
 
 __Important:__ ListCatalog does not return deleted catalog items. To retrieve
 deleted catalog items, use [SearchCatalogObjects](/doc/api/catalog.md#search-catalog-objects)
@@ -445,8 +491,8 @@ def list_catalog(self,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `cursor` | `string` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.<br>The page size is currently set to be 100.<br>See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. |
-| `types` | `string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.<br><br>The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, including<br>`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,<br>`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.<br><br>If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request. |
-| `catalog_version` | `long\|int` | Query, Optional | The specific version of the catalog objects to be included in the response.<br>This allows you to retrieve historical<br>versions of objects. The specified version value is matched against<br>the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. |
+| `types` | `string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.<br><br>The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, for example,<br>`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,<br>`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.<br><br>If this is unspecified, the operation returns objects of all the top level types at the version<br>of the Square API used to make the request. Object types that are nested onto other object types<br>are not included in the defaults.<br><br>At the current API version the default object types are:<br>ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,<br>SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,<br>SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. |
+| `catalog_version` | `long\|int` | Query, Optional | The specific version of the catalog objects to be included in the response.<br>This allows you to retrieve historical<br>versions of objects. The specified version value is matched against<br>the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute.  If not included, results will<br>be from the current version of the catalog. |
 
 ## Response Type
 
@@ -644,8 +690,8 @@ def retrieve_catalog_object(self,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `object_id` | `string` | Template, Required | The object ID of any type of catalog objects to be retrieved. |
-| `include_related_objects` | `bool` | Query, Optional | If `true`, the response will include additional objects that are related to the<br>requested object, as follows:<br><br>If the `object` field of the response contains a `CatalogItem`, its associated<br>`CatalogCategory`, `CatalogTax`, `CatalogImage` and `CatalogModifierList` objects will<br>be returned in the `related_objects` field of the response. If the `object` field of<br>the response contains a `CatalogItemVariation`, its parent `CatalogItem` will be returned<br>in the `related_objects` field of the response.<br><br>Default value: `false`<br>**Default**: `False` |
-| `catalog_version` | `long\|int` | Query, Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical<br>versions of objects. The value to retrieve a specific version of an object can be found<br>in the version field of [CatalogObject](/doc/models/catalog-object.md)s. |
+| `include_related_objects` | `bool` | Query, Optional | If `true`, the response will include additional objects that are related to the<br>requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field<br>of the response. These objects are put in the `related_objects` field. Setting this to `true` is<br>helpful when the objects are needed for immediate display to a user.<br>This process only goes one level deep. Objects referenced by the related objects will not be included. For example,<br><br>if the `objects` field of the response contains a CatalogItem, its associated<br>CatalogCategory objects, CatalogTax objects, CatalogImage objects and<br>CatalogModifierLists will be returned in the `related_objects` field of the<br>response. If the `objects` field of the response contains a CatalogItemVariation,<br>its parent CatalogItem will be returned in the `related_objects` field of<br>the response.<br><br>Default value: `false`<br>**Default**: `False` |
+| `catalog_version` | `long\|int` | Query, Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical<br>versions of objects. The value to retrieve a specific version of an object can be found<br>in the version field of [CatalogObject](/doc/models/catalog-object.md)s. If not included, results will<br>be from the current version of the catalog. |
 
 ## Response Type
 

doc/api/locations.md

@@ -18,11 +18,8 @@ locations_api = client.locations
 
 # List Locations
 
-Provides information of all locations of a business.
-
-Many Square API endpoints require a `location_id` parameter.
-The `id` field of the [`Location`](/doc/models/location.md) objects returned by this
-endpoint correspond to that `location_id` parameter.
+Provides details about all of the seller's locations,
+including those with an inactive status.
 
 ```python
 def list_locations(self)
@@ -46,7 +43,13 @@ elif result.is_error():
 
 # Create Location
 
-Creates a location.
+Creates a [location](https://developer.squareup.com/docs/locations-api).
+Creating new locations allows for separate configuration of receipt layouts, item prices,
+and sales reports. Developers can use locations to separate sales activity via applications
+that integrate with Square from sales activity elsewhere in a seller's account.
+Locations created programmatically with the Locations API will last forever and
+are visible to the seller for their own management, so ensure that
+each location has a sensible and unique name.
 
 ```python
 def create_location(self,
@@ -94,9 +97,8 @@ elif result.is_error():
 
 # Retrieve Location
 
-Retrieves details of a location. You can specify "main"
-as the location ID to retrieve details of the
-main location.
+Retrieves details of a single location. Specify "main"
+as the location ID to retrieve details of the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location).
 
 ```python
 def retrieve_location(self,
@@ -107,7 +109,7 @@ def retrieve_location(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `location_id` | `string` | Template, Required | The ID of the location to retrieve. If you specify the string "main",<br>then the endpoint returns the main location. |
+| `location_id` | `string` | Template, Required | The ID of the location to retrieve. Specify the string<br>"main" to return the main location. |
 
 ## Response Type
 

doc/api/mobile-authorization.md

@@ -11,9 +11,9 @@ mobile_authorization_api = client.mobile_authorization
 
 # Create Mobile Authorization Code
 
-Generates code to authorize a mobile application to connect to a Square card reader
+Generates code to authorize a mobile application to connect to a Square card reader.
 
-Authorization codes are one-time-use and expire __60 minutes__ after being issued.
+Authorization codes are one-time-use codes and expire 60 minutes after being issued.
 
 __Important:__ The `Authorization` header you provide to this endpoint must have the following format:
 

doc/api/o-auth.md

@@ -24,10 +24,10 @@ o_auth_api = client.o_auth
 
 Renews an OAuth access token before it expires.
 
-OAuth access tokens besides your application's personal access token expire after __30 days__.
-You can also renew expired tokens within __15 days__ of their expiration.
+OAuth access tokens besides your application's personal access token expire after 30 days.
+You can also renew expired tokens within 15 days of their expiration.
 You cannot renew an access token that has been expired for more than 15 days.
-Instead, the associated user must re-complete the OAuth flow from the beginning.
+Instead, the associated user must recomplete the OAuth flow from the beginning.
 
 __Important:__ The `Authorization` header for this endpoint must have the
 following format:
@@ -37,7 +37,7 @@ Authorization: Client APPLICATION_SECRET
 ```
 
 Replace `APPLICATION_SECRET` with the application secret on the Credentials
-page in the [developer dashboard](https://developer.squareup.com/apps).
+page in the [Developer Dashboard](https://developer.squareup.com/apps).
 
 :information_source: **Note** This endpoint does not require authentication.
 
@@ -52,7 +52,7 @@ def renew_token(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `client_id` | `string` | Template, Required | Your application ID, available from the OAuth page for your<br>application on the Developer Dashboard. |
+| `client_id` | `string` | Template, Required | Your application ID, which is available in the OAuth page in the [Developer Dashboard](https://developer.squareup.com/apps). |
 | `body` | [`Renew Token Request`](/doc/models/renew-token-request.md) | Body, Required | An object containing the fields to POST for the request.<br><br>See the corresponding object definition for field details. |
 | `authorization` | `string` | Header, Required | Client APPLICATION_SECRET |