Generated PR for Release: 8.1.0.20210121

CHANGELOG.md

@@ -1,11 +1,45 @@
 # Change Log
 
+## Version 8.1.0.20210121 (2021-01-21T00:00)
+## Existing API updates
+
+* **Invoices API:** (beta)
+
+  The `InvoicePaymentRequest.request_method` field is deprecated, and its current options are separated into two new fields that better represent their scope: 
+  * `Invoice.delivery_method` specifies how Square should send invoices, reminders, and receipts to the customer. 
+  * `InvoicePaymentRequest.automatic_payment_source` specifies the payment method for an automatic payment.
+
+  As part of this change, the [InvoiceDeliveryMethod](https://developer.squareup.com/reference/square_2021-01-21/enums/InvoiceDeliveryMethod) and [InvoiceAutomaticPaymentSource](https://developer.squareup.com/reference/square_2021-01-21/enums/InvoiceAutomaticPaymentSource) enums are added and the `InvoiceRequestMethod` enum is deprecated.
+
+  The Invoices API will continue to accept `request_method` in create and update requests until the field is retired, but starting in this version, `request_method` is not included in returned `Invoice` objects. For more information, see the [migration notes.](https://developer.squareup.com/docs/invoices-api/overview#migrate-InvoicePaymentRequest.request_method)
+
+
+* **Locations API:**
+  * The [Locations.MCC](https://developer.squareup.com/reference/square_2021-01-21/objects/Location#definition__property-mcc) field is now updatable (beta). You can use the `UpdateLocation` endpoint to update the merchant category code (MCC) associated with a seller location. For more information, see [Initialize a merchant category code.](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code)
+
+
+
+
+## SDKs
+* **Connect Node.js SDK:** (deprecated) 
+
+  The deprecated Connect Node.js SDK is in the security [maintenance state.](https://developer.squareup.com/docs/build-basics/api-lifecycle#maintenance) It will not receive any bug fixes or API updates from the Square version 2021-01-21 release. However, the SDK will receive support and security patches until it is retired (EOL) in Q2, 2021. For more information, including steps for migrating to the [Square Node.js SDK,](https://github.com/square/square-nodejs-sdk) see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md)
+
+## Documentation updates
+* **Catalog API:**
+  * The [Use Item Options to Manage Item Variations](https://developer.squareup.com/docs/catalog-api/item-options-migration) topic is added. It demonstrates how item variations are usually used and how item options can be used to enable random access to item variations.
+
+* **Inventory API:**
+  * The [Inventory API](inventory-api/what-it-does) content is updated. It provides clearer guidance about how to use the API, with a task-oriented TOC and improved code examples.
+
+
+
 ## Version 8.0.0.20201216 (2020-12-16T00:00)
 ## Existing API updates
 
 * **Orders API:** 
-  * [OrderLineItemPricingBlocklists.](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderLineItemPricingBlocklists) You can explicitly specify taxes and discounts in an order or automatically apply preconfigured taxes and discounts to an order. In addition, you can now block applying these taxes and discounts to a specific [OrderLineItem](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderLineItem) in an [order](https://developer.squareup.com/reference/square_2020_12_16/objects/Order). You add the `pricing_blocklists` attribute to individual line items and specify the `blocked_discounts` and `blocked_taxes` that you do not want to apply. For more information, see [Apply Taxes and Discounts.](orders-api/apply-taxes-and-discounts) For example walkthroughs, see [Automatically Apply Discounts](orders-api/apply-taxes-and-discounts/auto-apply-discounts) and [Automatically Apply Taxes.](orders-api/apply-taxes-and-discounts/auto-apply-taxes)
-  * [OrderPricingOptions](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderPricingOptions). Previously, the `pricing_options` field in an [order](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderPricingOptions) supported only `auto_apply_discounts` to enable the automatic application of preconfigured discounts. Now it also supports `auto_apply_taxes` to enable the automatic application of preconfigured taxes. For more information, see [Automatically apply preconfigured catalog taxes or discounts.](orders-api/apply-taxes-and-discounts#automatically-apply-preconfigured-catalog-taxes-or-discounts)
+  * [OrderLineItemPricingBlocklists.](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderLineItemPricingBlocklists) You can explicitly specify taxes and discounts in an order or automatically apply preconfigured taxes and discounts to an order. In addition, you can now block applying these taxes and discounts to a specific [OrderLineItem](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderLineItem) in an [order](https://developer.squareup.com/reference/square_2020_12_16/objects/Order). You add the `pricing_blocklists` attribute to individual line items and specify the `blocked_discounts` and `blocked_taxes` that you do not want to apply. For more information, see [Apply Taxes and Discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts) For example walkthroughs, see [Automatically Apply Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-discounts) and [Automatically Apply Taxes.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes)
+  * [OrderPricingOptions](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderPricingOptions). Previously, the `pricing_options` field in an [order](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderPricingOptions) supported only `auto_apply_discounts` to enable the automatic application of preconfigured discounts. Now it also supports `auto_apply_taxes` to enable the automatic application of preconfigured taxes. For more information, see [Automatically apply preconfigured catalog taxes or discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts#automatically-apply-preconfigured-catalog-taxes-or-discounts)
 
   * [OrderLineItemTax](https://developer.squareup.com/reference/square_2020_12_16/objects/OrderLineItemTax). It now includes the new `auto_applied` field. It indicates whether the tax was automatically applied using a preconfigured [CatalogTax](https://developer.squareup.com/reference/square_2020_12_16/objects/CatalogTax). 
 

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 Square, Inc.
+Copyright 2121 Square, Inc.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

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": "8.0.0.20201216",
+    "version": "8.1.0.20210121",
     "type": "library",
     "keywords": [
         "Square",

doc/apis/bookings.md

@@ -183,7 +183,7 @@ function listTeamMemberBookingProfiles(
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `bookableOnly` | `?bool` | Query, Optional | Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`). |
+| `bookableOnly` | `?bool` | Query, Optional | Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`).<br>**Default**: `false` |
 | `limit` | `?int` | Query, Optional | The maximum number of results to return. |
 | `cursor` | `?string` | Query, Optional | The cursor for paginating through the results. |
 | `locationId` | `?string` | Query, Optional | Indicates whether to include only team members enabled at the given location in the returned result. |

doc/apis/catalog.md

@@ -765,7 +765,7 @@ function retrieveCatalogObject(
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `objectId` | `string` | Template, Required | The object ID of any type of catalog objects to be retrieved. |
-| `includeRelatedObjects` | `?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` |
+| `includeRelatedObjects` | `?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` |
 | `catalogVersion` | `?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](#type-catalogobject)s. |
 
 ## Response Type
@@ -795,8 +795,8 @@ if ($apiResponse->isSuccess()) {
 
 # Search Catalog Objects
 
-Searches for [CatalogObject](#type-CatalogObject) of any types against supported search attribute values,
-excluding custom attribute values on items or item variations, against one or more of the specified query expressions,
+Searches for [CatalogObject](#type-CatalogObject) of any type by matching supported search attribute values,
+excluding custom attribute values on items or item variations, against one or more of the specified query expressions.
 
 This (`SearchCatalogObjects`) endpoint differs from the [SearchCatalogItems](#endpoint-Catalog-SearchCatalogItems)
 endpoint in the following aspects:
@@ -879,7 +879,7 @@ if ($apiResponse->isSuccess()) {
 # Search Catalog Items
 
 Searches for catalog items or item variations by matching supported search attribute values, including
-custom attribute values, against one or more of the specified query expressions,
+custom attribute values, against one or more of the specified query expressions.
 
 This (`SearchCatalogItems`) endpoint differs from the [SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
 endpoint in the following aspects:

doc/apis/employees.md

@@ -16,6 +16,8 @@ $employeesApi = $client->getEmployeesApi();
 
 # List Employees
 
+**This endpoint is deprecated. **
+
 ListEmployees
 
 ```php
@@ -64,6 +66,8 @@ if ($apiResponse->isSuccess()) {
 
 # Retrieve Employee
 
+**This endpoint is deprecated. **
+
 RetrieveEmployee
 
 ```php

doc/apis/invoices.md

@@ -108,13 +108,14 @@ $body_invoice_paymentRequests = [];
 
 $body_invoice_paymentRequests[0] = new Models\InvoicePaymentRequest;
 $body_invoice_paymentRequests[0]->setUid('uid4');
-$body_invoice_paymentRequests[0]->setRequestMethod(Models\InvoiceRequestMethod::EMAIL);
+$body_invoice_paymentRequests[0]->setRequestMethod(Models\InvoiceRequestMethod::SHARE_MANUALLY);
 $body_invoice_paymentRequests[0]->setRequestType(Models\InvoiceRequestType::BALANCE);
 $body_invoice_paymentRequests[0]->setDueDate('2030-01-24');
 $body_invoice_paymentRequests[0]->setFixedAmountRequestedMoney(new Models\Money);
 $body_invoice_paymentRequests[0]->getFixedAmountRequestedMoney()->setAmount(52);
 $body_invoice_paymentRequests[0]->getFixedAmountRequestedMoney()->setCurrency(Models\Currency::USS);
 $body_invoice_paymentRequests[0]->setTippingEnabled(true);
+$body_invoice_paymentRequests[0]->setAutomaticPaymentSource(Models\InvoiceAutomaticPaymentSource::NONE);
 $body_invoice_paymentRequests_0_reminders = [];
 
 $body_invoice_paymentRequests_0_reminders[0] = new Models\InvoicePaymentReminder;
@@ -127,6 +128,7 @@ $body_invoice_paymentRequests[0]->setReminders($body_invoice_paymentRequests_0_r
 
 $body_invoice->setPaymentRequests($body_invoice_paymentRequests);
 
+$body_invoice->setDeliveryMethod(Models\InvoiceDeliveryMethod::EMAIL);
 $body_invoice->setInvoiceNumber('inv-100');
 $body_invoice->setTitle('Event Planning Services');
 $body_invoice->setDescription('We appreciate your business!');
@@ -368,7 +370,7 @@ if ($apiResponse->isSuccess()) {
 Cancels an invoice. The seller cannot collect payments for
 the canceled invoice.
 
-You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
+You cannot cancel an invoice in the `DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
 
 ```php
 function cancelInvoice(string $invoiceId, CancelInvoiceRequest $body): ApiResponse

doc/apis/labor.md

@@ -269,6 +269,8 @@ if ($apiResponse->isSuccess()) {
 
 # List Employee Wages
 
+**This endpoint is deprecated. **
+
 Returns a paginated list of `EmployeeWage` instances for a business.
 
 ```php
@@ -310,6 +312,8 @@ if ($apiResponse->isSuccess()) {
 
 # Get Employee Wage
 
+**This endpoint is deprecated. **
+
 Returns a single `EmployeeWage` specified by id.
 
 ```php

doc/apis/o-auth.md

@@ -17,6 +17,8 @@ $oAuthApi = $client->getOAuthApi();
 
 # Renew Token
 
+**This endpoint is deprecated. **
+
 `RenewToken` is deprecated. For information about refreshing OAuth access tokens, see
 [Renew OAuth Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth-tokens).
 

doc/apis/transactions.md

@@ -21,6 +21,8 @@ $transactionsApi = $client->getTransactionsApi();
 
 # List Refunds
 
+**This endpoint is deprecated. **
+
 Lists refunds for one of a business's locations.
 
 In addition to full or partial tender refunds processed through Square APIs,
@@ -81,6 +83,8 @@ if ($apiResponse->isSuccess()) {
 
 # List Transactions
 
+**This endpoint is deprecated. **
+
 Lists transactions for a particular location.
 
 Transactions include payment information from sales and exchanges and refund
@@ -137,6 +141,8 @@ if ($apiResponse->isSuccess()) {
 
 # Charge
 
+**This endpoint is deprecated. **
+
 Charges a card represented by a card nonce or a customer's card on file.
 
 Your request to this endpoint must include _either_:
@@ -239,6 +245,8 @@ if ($apiResponse->isSuccess()) {
 
 # Retrieve Transaction
 
+**This endpoint is deprecated. **
+
 Retrieves details for a single transaction.
 
 ```php
@@ -278,6 +286,8 @@ if ($apiResponse->isSuccess()) {
 
 # Capture Transaction
 
+**This endpoint is deprecated. **
+
 Captures a transaction that was created with the [Charge](#endpoint-charge)
 endpoint with a `delay_capture` value of `true`.
 
@@ -321,6 +331,8 @@ if ($apiResponse->isSuccess()) {
 
 # Create Refund
 
+**This endpoint is deprecated. **
+
 Initiates a refund for a previously charged tender.
 
 You must issue a refund within 120 days of the associated payment. See
@@ -380,6 +392,8 @@ if ($apiResponse->isSuccess()) {
 
 # Void Transaction
 
+**This endpoint is deprecated. **
+
 Cancels a transaction that was created with the [Charge](#endpoint-charge)
 endpoint with a `delay_capture` value of `true`.
 

doc/apis/v1-employees.md

@@ -417,6 +417,8 @@ if ($apiResponse->isSuccess()) {
 
 # List Timecards
 
+**This endpoint is deprecated. **
+
 Provides summary information for all of a business's employee timecards.
 
 ```php
@@ -447,7 +449,7 @@ function listTimecards(
 | `endClockoutTime` | `?string` | Query, Optional | If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format. |
 | `beginUpdatedAt` | `?string` | Query, Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format. |
 | `endUpdatedAt` | `?string` | Query, Optional | If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format. |
-| `deleted` | `?bool` | Query, Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned. |
+| `deleted` | `?bool` | Query, Optional | If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned.<br>**Default**: `false` |
 | `limit` | `?int` | Query, Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. |
 | `batchToken` | `?string` | Query, Optional | A pagination cursor to retrieve the next set of results for your<br>original query to the endpoint. |
 
@@ -486,6 +488,8 @@ if ($apiResponse->isSuccess()) {
 
 # Create Timecard
 
+**This endpoint is deprecated. **
+
 Creates a timecard for an employee and clocks them in with an
 `API_CREATE` event and a `clockin_time` set to the current time unless
 the request provides a different value.
@@ -543,6 +547,8 @@ if ($apiResponse->isSuccess()) {
 
 # Delete Timecard
 
+**This endpoint is deprecated. **
+
 Deletes a timecard. Timecards can also be deleted through the
 Square Dashboard. Deleted timecards are still accessible through
 Connect API endpoints, but cannot be modified. The `deleted` field of
@@ -592,14 +598,13 @@ if ($apiResponse->isSuccess()) {
 
 # Retrieve Timecard
 
+**This endpoint is deprecated. **
+
 Provides the details for a single timecard.
 
-<aside>
 Only approved accounts can manage their employees with Square.
 Unapproved accounts cannot use employee management features with the
 API.
-</aside>
-
 
 ```php
 function retrieveTimecard(string $timecardId): ApiResponse
@@ -636,6 +641,8 @@ if ($apiResponse->isSuccess()) {
 
 # Update Timecard
 
+**This endpoint is deprecated. **
+
 Modifies the details of a timecard with an `API_EDIT` event for
 the timecard. Updating an active timecard with a `clockout_time`
 clocks the employee out.
@@ -685,6 +692,8 @@ if ($apiResponse->isSuccess()) {
 
 # List Timecard Events
 
+**This endpoint is deprecated. **
+
 Provides summary information for all events associated with a
 particular timecard.
 
@@ -727,6 +736,8 @@ if ($apiResponse->isSuccess()) {
 
 # List Cash Drawer Shifts
 
+**This endpoint is deprecated. **
+
 Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.
 
 ```php
@@ -775,6 +786,8 @@ if ($apiResponse->isSuccess()) {
 
 # Retrieve Cash Drawer Shift
 
+**This endpoint is deprecated. **
+
 Provides the details for a single cash drawer shift, including all events that occurred during the shift.
 
 ```php