Merge pull request #128 from square/release/35.0.0.20240222

Generated PR for Release: 35.0.0.20240222
square · Feb 21, 2024 · c4a8749 · c4a8749
2 parents ad8dd22 + e1f76eb
commit c4a8749
Show file tree

Hide file tree

Showing 106 changed files with 1,417 additions and 1,858 deletions.
diff --git a/doc/api/checkout.md b/doc/api/checkout.md
@@ -311,7 +311,7 @@ def list_payment_links(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `cursor` | `str` | 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>If a cursor is not provided, the endpoint returns the first page of the results.<br>For more  information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). |
+| `cursor` | `str` | 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>If a cursor is not provided, the endpoint returns the first page of the results.<br>For more  information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
 | `limit` | `int` | Query, Optional | A limit on the number of results to return per page. The limit is advisory and<br>the implementation might return more or less results. If the supplied limit is negative, zero, or<br>greater than the maximum limit of 1000, it is ignored.<br><br>Default value: `100` |
 
 ## Response Type

diff --git a/doc/api/customers.md b/doc/api/customers.md
@@ -12,6 +12,10 @@ customers_api = client.customers
 
 * [List Customers](../../doc/api/customers.md#list-customers)
 * [Create Customer](../../doc/api/customers.md#create-customer)
+* [Bulk Create Customers](../../doc/api/customers.md#bulk-create-customers)
+* [Bulk Delete Customers](../../doc/api/customers.md#bulk-delete-customers)
+* [Bulk Retrieve Customers](../../doc/api/customers.md#bulk-retrieve-customers)
+* [Bulk Update Customers](../../doc/api/customers.md#bulk-update-customers)
 * [Search Customers](../../doc/api/customers.md#search-customers)
 * [Delete Customer](../../doc/api/customers.md#delete-customer)
 * [Retrieve Customer](../../doc/api/customers.md#retrieve-customer)
@@ -128,6 +132,221 @@ elif result.is_error():
 ```
 
 
+# Bulk Create Customers
+
+Creates multiple [customer profiles](../../doc/models/customer.md) for a business.
+
+This endpoint takes a map of individual create requests and returns a map of responses.
+
+You must provide at least one of the following values in each create request:
+
+- `given_name`
+- `family_name`
+- `company_name`
+- `email_address`
+- `phone_number`
+
+```python
+def bulk_create_customers(self,
+                         body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Bulk Create Customers Request`](../../doc/models/bulk-create-customers-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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Create Customers Response`](../../doc/models/bulk-create-customers-response.md).
+
+## Example Usage
+
+```python
+body = {
+    'customers': {
+        '8bb76c4f-e35d-4c5b-90de-1194cd9179f0': {
+            'given_name': 'Amelia',
+            'family_name': 'Earhart',
+            'email_address': 'Amelia.Earhart@example.com',
+            'address': {
+                'address_line_1': '500 Electric Ave',
+                'address_line_2': 'Suite 600',
+                'locality': 'New York',
+                'administrative_district_level_1': 'NY',
+                'postal_code': '10003',
+                'country': 'US'
+            },
+            'phone_number': '+1-212-555-4240',
+            'reference_id': 'YOUR_REFERENCE_ID',
+            'note': 'a customer'
+        },
+        'd1689f23-b25d-4932-b2f0-aed00f5e2029': {
+            'given_name': 'Marie',
+            'family_name': 'Curie',
+            'email_address': 'Marie.Curie@example.com',
+            'address': {
+                'address_line_1': '500 Electric Ave',
+                'address_line_2': 'Suite 601',
+                'locality': 'New York',
+                'administrative_district_level_1': 'NY',
+                'postal_code': '10003',
+                'country': 'US'
+            },
+            'phone_number': '+1-212-444-4240',
+            'reference_id': 'YOUR_REFERENCE_ID',
+            'note': 'another customer'
+        }
+    }
+}
+
+result = customers_api.bulk_create_customers(body)
+print(result)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# Bulk Delete Customers
+
+Deletes multiple customer profiles.
+
+The endpoint takes a list of customer IDs and returns a map of responses.
+
+```python
+def bulk_delete_customers(self,
+                         body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Bulk Delete Customers Request`](../../doc/models/bulk-delete-customers-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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Delete Customers Response`](../../doc/models/bulk-delete-customers-response.md).
+
+## Example Usage
+
+```python
+body = {
+    'customer_ids': [
+        '8DDA5NZVBZFGAX0V3HPF81HHE0',
+        'N18CPRVXR5214XPBBA6BZQWF3C',
+        '2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
+    ]
+}
+
+result = customers_api.bulk_delete_customers(body)
+print(result)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# Bulk Retrieve Customers
+
+Retrieves multiple customer profiles.
+
+This endpoint takes a list of customer IDs and returns a map of responses.
+
+```python
+def bulk_retrieve_customers(self,
+                           body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Bulk Retrieve Customers Request`](../../doc/models/bulk-retrieve-customers-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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Retrieve Customers Response`](../../doc/models/bulk-retrieve-customers-response.md).
+
+## Example Usage
+
+```python
+body = {
+    'customer_ids': [
+        '8DDA5NZVBZFGAX0V3HPF81HHE0',
+        'N18CPRVXR5214XPBBA6BZQWF3C',
+        '2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
+    ]
+}
+
+result = customers_api.bulk_retrieve_customers(body)
+print(result)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
+# Bulk Update Customers
+
+Updates multiple customer profiles.
+
+This endpoint takes a map of individual update requests and returns a map of responses.
+
+You cannot use this endpoint to change cards on file. To make changes, use the [Cards API](../../doc/api/cards.md) or [Gift Cards API](../../doc/api/gift-cards.md).
+
+```python
+def bulk_update_customers(self,
+                         body)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Bulk Update Customers Request`](../../doc/models/bulk-update-customers-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
+
+This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Update Customers Response`](../../doc/models/bulk-update-customers-response.md).
+
+## Example Usage
+
+```python
+body = {
+    'customers': {
+        '8DDA5NZVBZFGAX0V3HPF81HHE0': {
+            'email_address': 'New.Amelia.Earhart@example.com',
+            'phone_number': 'phone_number2',
+            'note': 'updated customer note',
+            'version': 2
+        },
+        'N18CPRVXR5214XPBBA6BZQWF3C': {
+            'given_name': 'Marie',
+            'family_name': 'Curie',
+            'version': 0
+        }
+    }
+}
+
+result = customers_api.bulk_update_customers(body)
+print(result)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
 # Search Customers
 
 Searches the customer profiles associated with a Square account using one or more supported query filters.
@@ -202,9 +421,6 @@ elif result.is_error():
 
 Deletes a customer profile from a business. This operation also unlinks any associated cards on file.
 
-As a best practice, include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control.
-If included, the value must be set to the current version of the customer profile.
-
 To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
 
 ```python
@@ -276,11 +492,7 @@ elif result.is_error():
 # Update Customer
 
 Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request.
-To add or update a field, specify the new value. To remove a field, specify `null`
-(recommended) or specify an empty string (string fields only).
-
-As a best practice, include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control.
-If included, the value must be set to the current version of the customer profile.
+To add or update a field, specify the new value. To remove a field, specify `null`.
 
 To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
 
@@ -310,7 +522,7 @@ customer_id = 'customer_id8'
 
 body = {
     'email_address': 'New.Amelia.Earhart@example.com',
-    'phone_number': '',
+    'phone_number': 'phone_number2',
     'note': 'updated customer note',
     'version': 2
 }

diff --git a/doc/api/invoices.md b/doc/api/invoices.md
@@ -484,9 +484,12 @@ nothing. Square also makes the invoice available on a Square-hosted invoice page
 
 The invoice `status` also changes from `DRAFT` to a status
 based on the invoice configuration. For example, the status changes to `UNPAID` if
-Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the
+Square emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the
 invoice amount.
 
+In addition to the required `ORDERS_WRITE` and `INVOICES_WRITE` permissions, `CUSTOMERS_READ`
+and `PAYMENTS_WRITE` are required when publishing invoices configured for card-on-file payments.
+
 ```python
 def publish_invoice(self,
                    invoice_id,

diff --git a/doc/api/locations.md b/doc/api/locations.md
@@ -19,7 +19,7 @@ locations_api = client.locations
 # List Locations
 
 Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api),
-including those with an inactive status.
+including those with an inactive status. Locations are listed alphabetically by `name`.
 
 ```python
 def list_locations(self)