Merge pull request #59 from square/release/11.0.0.20210513

Generated PR for Release: 11.0.0.20210513
square · May 13, 2021 · 5d30eea · 5d30eea
2 parents 49546d6 + d4f5ed1
commit 5d30eea
Show file tree

Hide file tree

Showing 133 changed files with 1,255 additions and 441 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -0,0 +1,36 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python package
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  build:
+    env:
+      SQUARE_ENVIRONMENT: sandbox
+      SQUARE_SANDBOX_TOKEN: ${{ secrets.SQUARE_SANDBOX_TOKEN }}
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [2.7, 3.5]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r test-requirements.txt
+      - name: Test with nose
+        run: |
+          nosetests
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,39 @@
 # Change Log
 
+## Version 11.0.0.20210513 (2021-05-13)
+## New API releases
+
+* **Sites API.** The [Sites API](https://developer.squareup.com/reference/square_2021-05-13/sites-api) lets you retrieve basic details about the Square Online sites that belong to a Square seller. For more information, see [Sites API Overview.](https://developer.squareup.com/docs/sites-api/overview)
+
+
+* **Snippets API.** The [Snippets API](https://developer.squareup.com/reference/square_2021-05-13/snippets-api) lets you manage snippets that provide custom functionality on Square Online sites. A snippet is a script that is injected into all pages on a site, except for checkout pages. For more information, see [Snippets API Overview.](https://developer.squareup.com/docs/snippets-api/overview)
+
+The Sites API and Snippets API are publicly available to all developers as part of an early access program (EAP). For more information, see [Early access program for Square Online APIs.](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis)
+
+## API updates
+
+* **Payments API.**
+  * [CreatePayment.](https://developer.squareup.com/reference/square_2021-05-13/payments-api/create-payment) The endpoint now supports ACH bank transfer payments. For more information, see [ACH Payment](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments).
+
+* **Loyalty API:**
+  * The [Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state.
+
+  * The [ListLoyaltyPrograms](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/list-loyalty-programs) endpoint is deprecated and replaced by the [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/retrieve-loyalty-program) endpoint when used with the `main` keyword.
+
+  * [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccount)  object. The `mappings` field is retired and replaced by `mapping`. 
+
+  * [LoyaltyAccountMapping](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccountMapping) object. The `type` and `value` fields are retired and replaced by `phone_number`.  
+
+    Starting in Square version 2021-05-13: 
+    * `mappings` is not accepted in `CreateLoyaltyAccount` requests or returned in responses.  
+    * `type` and `value` are not accepted in `CreateLoyaltyAccount` or `SearchLoyaltyAccounts` requests or returned in responses.
+
+    For more information, see [Migration notes.](https://developer.squareup.com/docs/loyalty-api/overview#migration-notes)
+
+## Documentation updates
+* **Getting Started** Added step that shows how to use the API Logs to examine a transaction. 
+
+
 ## Version 10.0.0.20210421 (2021-04-21)
 ## New API releases
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # Square Python SDK
 
-[![Travis status](https://travis-ci.org/square/square-python-sdk.svg?branch=master)](https://travis-ci.org/square/square-python-sdk)
+[![Build](https://github.com/square/square-python-sdk/actions/workflows/python-package.yml/badge.svg)](https://github.com/square/square-python-sdk/actions/workflows/python-package.yml)
 [![PyPi version](https://badge.fury.io/py/squareup.svg?new)](https://badge.fury.io/py/squareup)
 [![Apache-2 license](https://img.shields.io/badge/license-Apache2-brightgreen.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
@@ -86,9 +86,13 @@ pip install -r test-requirements.txt
 ### Financials
 * [Bank Accounts]
 
+### Online
+* [Sites]
+* [Snippets]
+
 ### Authorization APIs
 * [Mobile Authorization]
-* [O Auth]
+* [OAuth]
 
 ### Deprecated APIs
 * [V1 Employees]
@@ -394,7 +398,7 @@ You can also use the Square API to create applications or services that work wit
 [Refunds]: doc/api/refunds.md
 [Subscriptions]: doc/api/subscriptions.md
 [Mobile Authorization]: doc/api/mobile-authorization.md
-[O Auth]: doc/api/o-auth.md
+[OAuth]: doc/api/o-auth.md
 [V1 Employees]: doc/api/v1-employees.md
 [V1 Transactions]: doc/api/v1-transactions.md
 [V1 Items]: doc/api/v1-items.md
@@ -403,3 +407,5 @@ You can also use the Square API to create applications or services that work wit
 [Python SDK]: https://github.com/square/square-python-sdk
 [Locations overview]: https://developer.squareup.com/docs/locations-api/what-it-does
 [OAuth overview]: https://developer.squareup.com/docs/oauth-api/what-it-does
+[Sites]: doc/api/sites.md
+[Snippets]: doc/api/snippets.md
diff --git a/doc/api/catalog.md b/doc/api/catalog.md
@@ -444,9 +444,9 @@ 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. |
+| `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, 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`. |
-| `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. |
+| `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. |
 
 ## Response Type
 
@@ -590,7 +590,7 @@ def retrieve_catalog_object(self,
 |  --- | --- | --- | --- |
 | `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. |
+| `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. |
 
 ## Response Type
 

diff --git a/doc/api/customers.md b/doc/api/customers.md
@@ -211,7 +211,7 @@ def delete_customer(self,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `customer_id` | `string` | Template, Required | The ID of the customer to delete. |
-| `version` | `long|int` | Query, Optional | The current version of the customer profile.<br><br>As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control.  For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile). |
+| `version` | `long\|int` | Query, Optional | The current version of the customer profile.<br><br>As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control.  For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile). |
 
 ## Response Type
 

diff --git a/doc/api/loyalty.md b/doc/api/loyalty.md
@@ -28,7 +28,7 @@ loyalty_api = client.loyalty
 
 # Create Loyalty Account
 
-Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and either the `mapping` field (preferred) or the `mappings` field.
+Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.
 
 ```python
 def create_loyalty_account(self,
@@ -51,23 +51,13 @@ def create_loyalty_account(self,
 body = {}
 body['loyalty_account'] = {}
 body['loyalty_account']['id'] = 'id2'
-body['loyalty_account']['mappings'] = []
-
-body['loyalty_account']['mappings'].append({})
-body['loyalty_account']['mappings'][0]['id'] = 'id0'
-body['loyalty_account']['mappings'][0]['type'] = 'PHONE'
-body['loyalty_account']['mappings'][0]['value'] = 'value2'
-body['loyalty_account']['mappings'][0]['created_at'] = 'created_at8'
-body['loyalty_account']['mappings'][0]['phone_number'] = 'phone_number8'
-
 body['loyalty_account']['program_id'] = 'd619f755-2d17-41f3-990d-c04ecedd64dd'
 body['loyalty_account']['balance'] = 14
 body['loyalty_account']['lifetime_points'] = 38
 body['loyalty_account']['customer_id'] = 'customer_id0'
+body['loyalty_account']['enrolled_at'] = 'enrolled_at2'
 body['loyalty_account']['mapping'] = {}
 body['loyalty_account']['mapping']['id'] = 'id6'
-body['loyalty_account']['mapping']['type'] = 'PHONE'
-body['loyalty_account']['mapping']['value'] = 'value8'
 body['loyalty_account']['mapping']['created_at'] = 'created_at4'
 body['loyalty_account']['mapping']['phone_number'] = '+14155551234'
 body['idempotency_key'] = 'ec78c477-b1c3-4899-a209-a4e71337c996'
@@ -113,8 +103,6 @@ body['query']['mappings'] = []
 
 body['query']['mappings'].append({})
 body['query']['mappings'][0]['id'] = 'id4'
-body['query']['mappings'][0]['type'] = 'PHONE'
-body['query']['mappings'][0]['value'] = 'value6'
 body['query']['mappings'][0]['created_at'] = 'created_at8'
 body['query']['mappings'][0]['phone_number'] = '+14155551234'
 
@@ -318,8 +306,12 @@ elif result.is_error():
 
 # List Loyalty Programs
 
+**This endpoint is deprecated. **
+
 Returns a list of loyalty programs in the seller's account.
-Currently, a seller can only have one loyalty program.
+Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).
+
+Replaced with [RetrieveLoyaltyProgram](/doc/api/loyalty.md#retrieve-loyalty-program) when used with the keyword `main`.
 
 ```python
 def list_loyalty_programs(self)

diff --git a/doc/api/orders.md b/doc/api/orders.md
@@ -21,12 +21,11 @@ orders_api = client.orders
 
 # Create Order
 
-Creates a new [Order](/doc/models/order.md) which can include information on products for
+Creates a new [order](/doc/models/order.md) that can include information about products for
 purchase and settings to apply to the purchase.
 
-To pay for a created order, please refer to the
-[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
-guide.
+To pay for a created order, see
+[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
 
 You can modify open orders using the [UpdateOrder](/doc/api/orders.md#update-order) endpoint.
 
@@ -169,9 +168,9 @@ elif result.is_error():
 
 # Batch Retrieve Orders
 
-Retrieves a set of [Order](/doc/models/order.md)s by their IDs.
+Retrieves a set of [orders](/doc/models/order.md) by their IDs.
 
-If a given Order ID does not exist, the ID is ignored instead of generating an error.
+If a given order ID does not exist, the ID is ignored instead of generating an error.
 
 ```python
 def batch_retrieve_orders(self,
@@ -314,19 +313,19 @@ elif result.is_error():
 
 Search all orders for one or more locations. Orders include all sales,
 returns, and exchanges regardless of how or when they entered the Square
-Ecosystem (e.g. Point of Sale, Invoices, Connect APIs, etc).
+ecosystem (such as Point of Sale, Invoices, and Connect APIs).
 
-SearchOrders requests need to specify which locations to search and define a
-[`SearchOrdersQuery`](/doc/models/search-orders-query.md) object which controls
-how to sort or filter the results. Your SearchOrdersQuery can:
+`SearchOrders` requests need to specify which locations to search and define a
+[SearchOrdersQuery](/doc/models/search-orders-query.md) object that controls
+how to sort or filter the results. Your `SearchOrdersQuery` can:
 
 Set filter criteria.
-Set sort order.
-Determine whether to return results as complete Order objects, or as
+Set the sort order.
+Determine whether to return results as complete `Order` objects or as
 [OrderEntry](/doc/models/order-entry.md) objects.
 
 Note that details for orders processed with Square Point of Sale while in
-offline mode may not be transmitted to Square for up to 72 hours. Offline
+offline mode might not be transmitted to Square for up to 72 hours. Offline
 orders have a `created_at` value that reflects the time the order was created,
 not the time it was subsequently transmitted to Square.
 
@@ -422,21 +421,21 @@ elif result.is_error():
 
 # Update Order
 
-Updates an open [Order](/doc/models/order.md) by adding, replacing, or deleting
+Updates an open [order](/doc/models/order.md) by adding, replacing, or deleting
 fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.
 
-An UpdateOrder request requires the following:
+An `UpdateOrder` request requires the following:
 
 - The `order_id` in the endpoint path, identifying the order to update.
 - The latest `version` of the order to update.
 - The [sparse order](https://developer.squareup.com/docs/orders-api/manage-orders#sparse-order-objects)
-  containing only the fields to update and the version the update is
-  being applied to.
+  containing only the fields to update and the version to which the update is
+  being applied.
 - If deleting fields, the [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot-notation)
-  identifying fields to clear.
+  identifying the fields to clear.
 
-To pay for an order, please refer to the
-[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders) guide.
+To pay for an order, see
+[Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
 
 ```python
 def update_order(self,
@@ -517,20 +516,20 @@ elif result.is_error():
 
 # Pay Order
 
-Pay for an [order](/doc/models/order.md) using one or more approved [payments](/doc/models/payment.md),
+Pay for an [order](/doc/models/order.md) using one or more approved [payments](/doc/models/payment.md)
 or settle an order with a total of `0`.
 
 The total of the `payment_ids` listed in the request must be equal to the order
 total. Orders with a total amount of `0` can be marked as paid by specifying an empty
 array of `payment_ids` in the request.
 
-To be used with PayOrder, a payment must:
+To be used with `PayOrder`, a payment must:
 
 - Reference the order by specifying the `order_id` when [creating the payment](/doc/api/payments.md#create-payment).
   Any approved payments that reference the same `order_id` not specified in the
-  `payment_ids` will be canceled.
+  `payment_ids` is canceled.
 - Be approved with [delayed capture](https://developer.squareup.com/docs/payments-api/take-payments#delayed-capture).
-  Using a delayed capture payment with PayOrder will complete the approved payment.
+  Using a delayed capture payment with `PayOrder` completes the approved payment.
 
 ```python
 def pay_order(self,

diff --git a/doc/api/payments.md b/doc/api/payments.md
@@ -50,7 +50,7 @@ def list_payments(self,
 | `sort_order` | `string` | Query, Optional | The order in which results are listed:<br><br>- `ASC` - Oldest to newest.<br>- `DESC` - Newest to oldest (default). |
 | `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 the default (main) location associated with the seller. |
-| `total` | `long|int` | Query, Optional | The exact amount in the `total_money` for a payment. |
+| `total` | `long\|int` | Query, Optional | The exact amount in the `total_money` for a payment. |
 | `last_4` | `string` | Query, Optional | The last four digits of a payment card. |
 | `card_brand` | `string` | Query, Optional | The brand of the payment card (for example, VISA). |
 | `limit` | `int` | Query, Optional | The maximum number of results to be returned in a single page.<br>It is possible to receive fewer results than the specified limit on a given page.<br><br>The default value of 100 is also the maximum allowed value. If the provided value is<br>greater than 100, it is ignored and the default value is used instead.<br><br>Default: `100` |

diff --git a/doc/api/sites.md b/doc/api/sites.md
@@ -0,0 +1,36 @@
+# Sites
+
+```python
+sites_api = client.sites
+```
+
+## Class Name
+
+`SitesApi`
+
+
+# List Sites
+
+Lists the Square Online sites that belong to a seller.
+
+__Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).
+
+```python
+def list_sites(self)
+```
+
+## Response Type
+
+[`List Sites Response`](/doc/models/list-sites-response.md)
+
+## Example Usage
+
+```python
+result = sites_api.list_sites()
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+