Merge pull request #44 from square/release/11.0.0.20210513

Generated PR for Release: 11.0.0.20210513

.github/workflows/php.yml

@@ -0,0 +1,47 @@
+name: PHP Composer
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  build:
+    env:
+      SQUARE_ENVIRONMENT: sandbox
+      SQUARE_ACCESS_TOKEN: ${{ secrets.SQUARE_SANDBOX_TOKEN }}
+
+    runs-on: ubuntu-18.04
+
+    strategy:
+      matrix:
+        php-versions: ["7.2", "7.3", "7.4", "8.0"]
+        phpunit-versions: ["8.5.8"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          tools: phpunit:${{ matrix.phpunit-versions }}
+
+      - name: Cache Composer packages
+        id: composer-cache
+        uses: actions/cache@v2
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ matrix.php-versions }}-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-php-${{ matrix.php-versions }}-
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Run test suite
+        run: composer run test
+
+      - name: Run test suite
+        run: composer run analyze

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
 

README.md

@@ -1,6 +1,6 @@
 # Square PHP SDK
 
-[![Travis status](https://travis-ci.com/square/square-php-sdk.svg?branch=master)](https://travis-ci.com/square/square-php-sdk)
+[![Build](https://github.com/square/square-php-sdk/actions/workflows/php.yml/badge.svg)](https://github.com/square/square-php-sdk/actions/workflows/php.yml)
 [![PHP version](https://badge.fury.io/ph/square%2Fsquare.svg)](https://badge.fury.io/ph/square%2Fsquare)
 [![Apache-2 license](https://img.shields.io/badge/license-Apache2-brightgreen.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
@@ -75,9 +75,13 @@ After downloading the SDK and its dependencies you'll need to write a custom `au
 ### Financials
 * [Bank Accounts]
 
+### Online
+* [Sites]
+* [Snippets]
+
 ### Authorization APIs
 * [Mobile Authorization]
-* [O Auth]
+* [OAuth]
 
 ### Deprecated APIs
 * [V1 Employees]
@@ -409,9 +413,11 @@ You can also use the Square API to create applications or services that work wit
 [Refunds]: doc/apis/refunds.md
 [Subscriptions]: doc/apis/subscriptions.md
 [Mobile Authorization]: doc/apis/mobile-authorization.md
-[O Auth]: doc/apis/o-auth.md
+[OAuth]: doc/apis/o-auth.md
 [V1 Employees]: doc/apis/v1-employees.md
 [V1 Transactions]: doc/apis/v1-transactions.md
 [V1 Items]: doc/apis/v1-items.md
 [Team]: doc/apis/team.md
 [Transactions]: doc/apis/transactions.md
+[Sites]: doc/api/sites.md
+[Snippets]: doc/api/snippets.md

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "square/square",
     "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.",
-    "version": "10.0.0.20210421",
+    "version": "11.0.0.20210513",
     "type": "library",
     "keywords": [
         "Square",

doc/apis/catalog.md

@@ -591,7 +591,7 @@ function listCatalog(?string $cursor = null, ?string $types = null, ?int $catalo
 
 | 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`. |
 | `catalogVersion` | `?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. |
 

doc/apis/inventory.md

@@ -82,8 +82,10 @@ function batchChangeInventory(BatchChangeInventoryRequest $body): ApiResponse
 ## Example Usage
 
 ```php
-$body = new Models\BatchChangeInventoryRequest;
-$body->setIdempotencyKey('8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe');
+$body_idempotencyKey = '8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe';
+$body = new Models\BatchChangeInventoryRequest(
+    $body_idempotencyKey
+);
 $body_changes = [];
 
 $body_changes[0] = new Models\InventoryChange;

doc/apis/loyalty.md

@@ -28,7 +28,7 @@ $loyaltyApi = $client->getLoyaltyApi();
 
 # 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.
 
 ```php
 function createLoyaltyAccount(CreateLoyaltyAccountRequest $body): ApiResponse
@@ -52,23 +52,12 @@ $body_loyaltyAccount = new Models\LoyaltyAccount(
     $body_loyaltyAccount_programId
 );
 $body_loyaltyAccount->setId('id2');
-$body_loyaltyAccount_mappings = [];
-
-$body_loyaltyAccount_mappings[0] = new Models\LoyaltyAccountMapping;
-$body_loyaltyAccount_mappings[0]->setId('id0');
-$body_loyaltyAccount_mappings[0]->setType(Models\LoyaltyAccountMappingType::PHONE);
-$body_loyaltyAccount_mappings[0]->setValue('value2');
-$body_loyaltyAccount_mappings[0]->setCreatedAt('created_at8');
-$body_loyaltyAccount_mappings[0]->setPhoneNumber('phone_number8');
-$body_loyaltyAccount->setMappings($body_loyaltyAccount_mappings);
-
 $body_loyaltyAccount->setBalance(14);
 $body_loyaltyAccount->setLifetimePoints(38);
 $body_loyaltyAccount->setCustomerId('customer_id0');
+$body_loyaltyAccount->setEnrolledAt('enrolled_at2');
 $body_loyaltyAccount->setMapping(new Models\LoyaltyAccountMapping);
 $body_loyaltyAccount->getMapping()->setId('id6');
-$body_loyaltyAccount->getMapping()->setType(Models\LoyaltyAccountMappingType::PHONE);
-$body_loyaltyAccount->getMapping()->setValue('value8');
 $body_loyaltyAccount->getMapping()->setCreatedAt('created_at4');
 $body_loyaltyAccount->getMapping()->setPhoneNumber('+14155551234');
 $body_idempotencyKey = 'ec78c477-b1c3-4899-a209-a4e71337c996';
@@ -122,8 +111,6 @@ $body_query_mappings = [];
 
 $body_query_mappings[0] = new Models\LoyaltyAccountMapping;
 $body_query_mappings[0]->setId('id4');
-$body_query_mappings[0]->setType(Models\LoyaltyAccountMappingType::PHONE);
-$body_query_mappings[0]->setValue('value6');
 $body_query_mappings[0]->setCreatedAt('created_at8');
 $body_query_mappings[0]->setPhoneNumber('+14155551234');
 $body->getQuery()->setMappings($body_query_mappings);
@@ -366,8 +353,12 @@ if ($apiResponse->isSuccess()) {
 
 # 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/apis/loyalty.md#retrieve-loyalty-program) when used with the keyword `main`.
 
 ```php
 function listLoyaltyPrograms(): ApiResponse

doc/apis/orders.md

@@ -21,12 +21,11 @@ $ordersApi = $client->getOrdersApi();
 
 # 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/apis/orders.md#update-order) endpoint.
 
@@ -192,9 +191,9 @@ if ($apiResponse->isSuccess()) {
 
 # 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.
 
 ```php
 function batchRetrieveOrders(BatchRetrieveOrdersRequest $body): ApiResponse
@@ -373,19 +372,19 @@ if ($apiResponse->isSuccess()) {
 
 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.
 
@@ -493,21 +492,21 @@ if ($apiResponse->isSuccess()) {
 
 # 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).
 
 ```php
 function updateOrder(string $orderId, UpdateOrderRequest $body): ApiResponse
@@ -604,20 +603,20 @@ if ($apiResponse->isSuccess()) {
 
 # 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/apis/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.
 
 ```php
 function payOrder(string $orderId, PayOrderRequest $body): ApiResponse

doc/apis/sites.md

@@ -0,0 +1,41 @@
+# Sites
+
+```php
+$sitesApi = $client->getSitesApi();
+```
+
+## 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).
+
+```php
+function listSites(): ApiResponse
+```
+
+## Response Type
+
+[`ListSitesResponse`](/doc/models/list-sites-response.md)
+
+## Example Usage
+
+```php
+$apiResponse = $sitesApi->listSites();
+
+if ($apiResponse->isSuccess()) {
+    $listSitesResponse = $apiResponse->getResult();
+} else {
+    $errors = $apiResponse->getErrors();
+}
+
+// Get more response info...
+// $statusCode = $apiResponse->getStatusCode();
+// $headers = $apiResponse->getHeaders();
+```
+