Merge pull request #12 from square/release/3.20191120.0

Release 3.20191120.0

Author: jessdelacruzsantos

.travis.yml

@@ -23,7 +23,7 @@ env:
 notifications:
   slack:
     secure: Gh641zg9Ch+sFZCWwxdi6ZPQk1csUGcwenfL9cgs3op+BfQOJbBgw3LWGqYVBBgTowO8ibg/q/kapzg9lGjLxQOVNPQZci7dFB5WHmdVwUoSoLxQCZcCa0IQkk0XfI7UYKBnuoqpBsEe6eXKyvdFEUrx51Z4XwFtjLpINYZ4DY2NmsA9QihFJBSqhB4si7l0yON2Q8JR4Dc6PXCLn+LrzNliHCgzWveF/FtRQocT4uj3e3frySdOHmb6fV2yGb8Z/jR01s/97cyX6Y37BWyGrZFTfyDb+V5lcAzJdgkYhLaeLo8coKwZwgWOu6Eo6EeQ4/Y/XKr9BjdKmyWY0Z2gc4FPWrHvfrGdUsSfr2ECdApMsNcNPeTtvAc2xe8wDVbASLdrg5pcZCba5PZBgZ4KvQ7Rg7olo9dbHRbUddy0VFM1Td9heBKXV9gL1bkv1eLMa400uGKoA6A7lim8AkjEBTiLQ3pZOalZGDUop5iDD8pmnwZ9rd51LI03hSIrC75j1ePlqxwQ6z6R2xjwCHznNveiI/CQGtLr4vMuexGG//afK8/WGlnVch+CpEkC/aEok/0L3ik3l6OgfXuHItgY3SrUny18uYNQK4NXPo+PT+m82qzSONpHxhdkYXsz8GP5/Rn5v2wUShLUKwU/EKi20fjcI1jO/JAW8gcJAwfBChA=
-  on_success: change
+    on_success: change
     template:
       - "@oncall"
       - "Build <%{build_url}|#%{build_number}> (<%{compare_url}|%{commit}>) of %{repository_slug}@%{branch} in PR <%{pull_request_url}|#%{pull_request_number}> by %{author} %{result} in %{duration}"

doc/apple-pay.md

@@ -18,7 +18,7 @@ This endpoint provides an easy way for platform developers to bulk activate
 Web Apple Pay with Square for merchants using their platform.
 
 To learn more about Apple Pay on Web see the Apple Pay section in the
-[Embedding the Square Payment Form](https://developer.squareup.com/docs/payment-form/add-digital-wallets/apple-pay) guide.
+[Square Payment Form Walkthrough](https://developer.squareup.com/docs/docs/payment-form/payment-form-walkthrough).
 
 ```python
 def register_domain(self,

doc/catalog.md

@@ -13,6 +13,7 @@ catalog_api = client.catalog
 * [Batch Delete Catalog Objects](/doc/catalog.md#batch-delete-catalog-objects)
 * [Batch Retrieve Catalog Objects](/doc/catalog.md#batch-retrieve-catalog-objects)
 * [Batch Upsert Catalog Objects](/doc/catalog.md#batch-upsert-catalog-objects)
+* [Create Catalog Image](/doc/catalog.md#create-catalog-image)
 * [Catalog Info](/doc/catalog.md#catalog-info)
 * [List Catalog](/doc/catalog.md#list-catalog)
 * [Upsert Catalog Object](/doc/catalog.md#upsert-catalog-object)
@@ -199,6 +200,82 @@ elif result.is_error():
     print(result.errors)
 ```
 
+## Create Catalog Image
+
+Upload an image file to create a new [CatalogImage](#type-catalogimage) for an existing
+[CatalogObject](#type-catalogobject). Images can be uploaded and linked in this request or created independently
+(without an object assignment) and linked to a [CatalogObject](#type-catalogobject) at a later time.
+
+CreateCatalogImage 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. The following is an example of such an HTTP request:
+
+```
+POST /v2/catalog/images
+Accept: application/json
+Content-Type: multipart/form-data;boundary="boundary"
+Square-Version: XXXX-XX-XX
+Authorization: Bearer {ACCESS_TOKEN}
+
+--boundary
+Content-Disposition: form-data; name="request"
+Content-Type: application/json
+
+{
+"idempotency_key":"528dea59-7bfb-43c1-bd48-4a6bba7dd61f86",
+"object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
+"image":{
+"id":"#TEMP_ID",
+"type":"IMAGE",
+"image_data":{
+"caption":"A picture of a cup of coffee"
+}
+}
+}
+--boundary
+Content-Disposition: form-data; name="image"; filename="Coffee.jpg"
+Content-Type: image/jpeg
+
+{ACTUAL_IMAGE_BYTES}
+--boundary
+```
+
+Additional information and an example cURL request can be found in the [Create a Catalog Image recipe](https://developer.squareup.com/docs/more-apis/catalog/cookbook/create-catalog-images).
+
+```python
+def create_catalog_image(self,
+                        request=None,
+                        image_file=None)
+```
+
+### Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `request` | [`Create Catalog Image Request`](/doc/models/create-catalog-image-request.md) | Form, Optional | - |
+| `image_file` | `string` | Form, Optional | - |
+
+### Response Type
+
+[`Create Catalog Image Response`](/doc/models/create-catalog-image-response.md)
+
+### Example Usage
+
+```python
+request = {}
+request['idempotency_key'] = '528dea59-7bfb-43c1-bd48-4a6bba7dd61f86'
+request['object_id'] = 'ND6EA5AAJEO5WL3JNNIAQA32'
+request['image'] = {}
+request['image']['type'] = 'IMAGE'
+request['image']['id'] = '#TEMP_ID'
+
+result = catalog_api.create_catalog_image(request)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
 ## Catalog Info
 
 Returns information about the Square Catalog API, such as batch size
@@ -246,7 +323,7 @@ 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>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, for example<br>`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.<br><br>The legal values are taken from the [CatalogObjectType](#type-catalogobjecttype)<br>enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,<br>`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. |
+| `types` | `string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve, for example<br>`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.<br><br>The legal values are taken from the CatalogObjectType enum:<br>`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,<br>`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. |
 
 ### Response Type
 
@@ -321,7 +398,7 @@ def delete_catalog_object(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `object_id` | `string` | Template, Required | The ID of the [CatalogObject](#type-catalogobject) to be deleted. When an object is deleted, other<br>objects in the graph that depend on that object will be deleted as well (for example, deleting a<br>[CatalogItem](#type-catalogitem) will delete its [CatalogItemVariation](#type-catalogitemvariation)s). |
+| `object_id` | `string` | Template, Required | The ID of the catalog object to be deleted. When an object is deleted, other<br>objects in the graph that depend on that object will be deleted as well (for example, deleting a<br>catalog item will delete its catalog item variations). |
 
 ### Response Type
 
@@ -360,8 +437,8 @@ def retrieve_catalog_object(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `object_id` | `string` | Template, Required | The object ID of any type of [CatalogObject](#type-catalogobject)s 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](#type-catalogitem),<br>its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es,<br>[CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s<br>will be returned in the `related_objects` field of the response. If the `object`<br>field of the response contains a [CatalogItemVariation](#type-catalogitemvariation),<br>its parent [CatalogItem](#type-catalogitem) will be returned in the `related_objects` field of <br>the response.<br><br>Default value: `false` |
+| `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,<br>its associated CatalogCategory, CatalogTax objects,<br>CatalogImages and CatalogModifierLists<br>will be returned in the `related_objects` field of the response. If the `object`<br>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` |
 
 ### Response Type
 
@@ -389,6 +466,13 @@ Queries the targeted catalog using a variety of query types:
 [CatalogQueryText](#type-catalogquerytext),
 [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and
 [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist).
+--
+--
+Future end of the above comment:
+[CatalogQueryItemsForTax](#type-catalogqueryitemsfortax),
+[CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist),
+[CatalogQueryItemsForItemOptions](#type-catalogqueryitemsforitemoptions), and
+[CatalogQueryItemVariationsForItemOptionValues](#type-catalogqueryitemvariationsforitemoptionvalues).
 
 ```python
 def search_catalog_objects(self,

doc/client.md

@@ -34,9 +34,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 to retrieve the next set of results for your original query.<br><br>See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. |
-| `sort_field` | [`str (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Query, Optional | Indicates how Customers should be sorted. 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. Default: `ASC`. |
+| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for your original query.<br><br>See the [Pagination guide](https://developer.squareup.com/docs/working-with-apis/pagination) for more information. |
+| `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`. |
 
 ### Response Type
 
@@ -228,9 +228,8 @@ the new `customer_id` to update merged profiles.
 
 You cannot edit a customer's cards on file with this endpoint. To make changes
 to a card on file, you must delete the existing card on file with the
-[DeleteCustomerCard](#endpoint-customers-deletecustomercard) endpoint, then
-create a new one with the
-[CreateCustomerCard](#endpoint-customers-createcustomercard) endpoint.
+[DeleteCustomerCard](#endpoint-deletecustomercard) endpoint, then create a new one with the
+[CreateCustomerCard](#endpoint-createcustomercard) endpoint.
 
 ```python
 def update_customer(self,
@@ -274,9 +273,6 @@ As with charges, calls to `CreateCustomerCard` are idempotent. Multiple
 calls with the same card nonce return the same card record that was created
 with the provided nonce during the _first_ call.
 
-Cards on file are automatically updated on a monthly basis to confirm they
-are still valid and can be charged.
-
 ```python
 def create_customer_card(self,
                         customer_id,

doc/customers.md

@@ -15,7 +15,7 @@ employees_api = client.employees
 
 ## List Employees
 
-Gets a list of `Employee` objects for a business.
+ListEmployees
 
 ```python
 def list_employees(self,
@@ -29,7 +29,7 @@ def list_employees(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `location_id` | `string` | Query, Optional | Filter employees returned to only those that are associated with the<br>specified location. |
+| `location_id` | `string` | Query, Optional | Filter employees returned to only those that are associated with the specified location. |
 | `status` | [`str (Employee Status)`](/doc/models/employee-status.md) | Query, Optional | Specifies the EmployeeStatus to filter the employee by. |
 | `limit` | `int` | Query, Optional | The number of employees to be returned on each page. |
 | `cursor` | `string` | Query, Optional | The token required to retrieve the specified page of results. |
@@ -51,7 +51,7 @@ elif result.is_error():
 
 ## Retrieve Employee
 
-Gets an `Employee` by Square-assigned employee `ID` (UUID)
+RetrieveEmployee
 
 ```python
 def retrieve_employee(self,

doc/employees.md

@@ -245,7 +245,7 @@ def retrieve_inventory_count(self,
 |  --- | --- | --- | --- |
 | `catalog_object_id` | `string` | Template, Required | ID of the [CatalogObject](#type-catalogobject) to retrieve. |
 | `location_ids` | `string` | Query, Optional | The [Location](#type-location) IDs to look up as a comma-separated<br>list. An empty list queries all locations. |
-| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for the original query.<br><br>See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. |
+| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for the original query.<br><br>See the [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pagination) guide for more information. |
 
 ### Response Type
 
@@ -290,7 +290,7 @@ def retrieve_inventory_changes(self,
 |  --- | --- | --- | --- |
 | `catalog_object_id` | `string` | Template, Required | ID of the [CatalogObject](#type-catalogobject) to retrieve. |
 | `location_ids` | `string` | Query, Optional | The [Location](#type-location) IDs to look up as a comma-separated<br>list. An empty list queries all locations. |
-| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for the original query.<br><br>See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. |
+| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.<br>Provide this to retrieve the next set of results for the original query.<br><br>See the [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pagination) guide for more information. |
 
 ### Response Type
 

doc/inventory.md

@@ -11,12 +11,13 @@ locations_api = client.locations
 ## Methods
 
 * [List Locations](/doc/locations.md#list-locations)
+* [Create Location](/doc/locations.md#create-location)
 * [Retrieve Location](/doc/locations.md#retrieve-location)
 * [Update Location](/doc/locations.md#update-location)
 
 ## List Locations
 
-Provides the details for all of a business's locations.
+Provides information of all locations of a business.
 
 Most other Connect API endpoints have a required `location_id` path parameter.
 The `id` field of the [`Location`](#type-location) objects returned by this
@@ -41,6 +42,47 @@ elif result.is_error():
     print(result.errors)
 ```
 
+## Create Location
+
+Creates a location.
+For more information about locations, see [Locations API Overview](https://developer.squareup.com/docs/locations-api).
+
+```python
+def create_location(self,
+                   body)
+```
+
+### Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Create Location Request`](/doc/models/create-location-request.md) | Body, Required | An object containing the fields to POST for the request.<br><br>See the corresponding object definition for field details. |
+
+### Response Type
+
+[`Create Location Response`](/doc/models/create-location-response.md)
+
+### Example Usage
+
+```python
+body = {}
+body['location'] = {}
+body['location']['name'] = 'New location name'
+body['location']['address'] = {}
+body['location']['address']['address_line_1'] = '1234 Peachtree St. NE'
+body['location']['address']['locality'] = 'Atlanta'
+body['location']['address']['administrative_district_level_1'] = 'GA'
+body['location']['address']['postal_code'] = '30309'
+body['location']['description'] = 'My new location.'
+
+result = locations_api.create_location(body)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
 ## Retrieve Location
 
 Retrieves details of a location.
@@ -75,7 +117,7 @@ elif result.is_error():
 
 ## Update Location
 
-Updates the `Location` specified by the given ID.
+Updates a location.
 
 ```python
 def update_location(self,
@@ -99,6 +141,24 @@ def update_location(self,
 ```python
 location_id = 'location_id4'
 body = {}
+body['location'] = {}
+body['location']['name'] = 'Updated nickname'
+body['location']['address'] = {}
+body['location']['address']['address_line_1'] = '1234 Peachtree St. NE'
+body['location']['address']['locality'] = 'Atlanta'
+body['location']['address']['administrative_district_level_1'] = 'GA'
+body['location']['address']['postal_code'] = '30309'
+body['location']['business_hours'] = {}
+body['location']['business_hours']['periods'] = []
+
+body['location']['business_hours']['periods'].append({})
+body['location']['business_hours']['periods'][0]['day_of_week'] = 'MON'
+body['location']['business_hours']['periods'][0]['start_local_time'] = '09:00'
+body['location']['business_hours']['periods'][0]['end_local_time'] = '17:00'
+
+body['location']['description'] = 'Updated description'
+body['location']['twitter_username'] = 'twitter'
+body['location']['instagram_username'] = 'instagram'
 
 result = locations_api.update_location(location_id, body)