Merge pull request #20 from square/release/6.1.0.20200722

release 6.1.0.20200722

Author: okenshields

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Change Log
 
+## Version 6.1.0.20200722 (2020-07-22)
+## API releases
+
+* Invoices API (beta):
+  * For an overview, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/invoices-api/overview).
+  * For technical reference, see [Invoices API](https://developer.squareup.com/reference/square_2020-07-22/invoices-api).
+
+## Existing API updates
+
+* Catalog API
+	* [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items). You can now call the new search endpoint to [search for catalog items or item variations](https://developer.squareup.com/docs/catalog-api/search-catalog-items), with simplified programming experiences, using one or more of the supported query filters, including the custom attribute value filter.
+* Locations API
+  * [Locations API Overview](https://developer.squareup.com/docs/locations-api). Introduced the "main" location concept. 
+  * [RetrieveLocation](https://developer.squareup.com/reference/square_2020-07-22/locations-api/retrieve-location). You can now specify "main" as the location ID to retrieve the main location information.
+
+* Merchants API
+  * [RetrieveMerchant](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant) and [ListMerchants](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant). These endpoints now return a new field, `main_location_id`.
+
+* Orders API 
+  * [PricingOptions](https://developer.squareup.com/reference/square_2020-07-22/objects/Order#definition__property-pricing_options). You can now enable the `auto_apply_discounts` of the options to have rule-based discounts automatically applied to an [Order](https://developer.squareup.com/reference/square_2020-07-22/objects/Order) that is pre-configured with a [pricing rule](https://developer.squareup.com/reference/square_2020-07-22/objects/CatalogPricingRule). 
+
+* [Inventory API](https://developer.squareup.com/reference/square_2020-07-22/inventory-api)
+	* Replaced 500 error on max string length exceeded with a max length error message. Max length attribute added to string type fields.
+
+* Terminal API (beta)
+	* [TerminalCheckout](https://developer.squareup.com/reference/square_2020-07-22/objects/TerminalCheckout) object. The `TerminalCheckoutCancelReason` field is renamed to `ActionCancelReason`.
+
+## Documentation updates
+
+* Catalog API
+	* [Search a catalog](https://developer.squareup.com/docs/catalog-api/search-catalog). New topics added to provide actionable guides to using the existing [SearchCatalogObjects](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-objects) endpoint, in addition to the [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items) endpoints.
+
+* Orders API
+	* [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders). Updated existing content with the new pricing option for the automatic application of rule-based discounts. 
+
+
 ## Version 6.0.0.20200625 (2020-06-25)
 
 ## New API release 

README.md

@@ -20,6 +20,7 @@ CatalogApi catalogApi = client.getCatalogApi();
 * [Delete Catalog Object](/doc/catalog.md#delete-catalog-object)
 * [Retrieve Catalog Object](/doc/catalog.md#retrieve-catalog-object)
 * [Search Catalog Objects](/doc/catalog.md#search-catalog-objects)
+* [Search Catalog Items](/doc/catalog.md#search-catalog-items)
 * [Update Item Modifier Lists](/doc/catalog.md#update-item-modifier-lists)
 * [Update Item Taxes](/doc/catalog.md#update-item-taxes)
 
@@ -270,12 +271,12 @@ catalogApi.batchUpsertCatalogObjectsAsync(body).thenAccept(result -> {
 
 ## 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.
+Uploads an image file to be represented by an [CatalogImage](#type-catalogimage) object linked to an existing
+[CatalogObject](#type-catalogobject) instance. A call to this endpoint can upload an image, link an image to
+a catalog object, or do both.
 
-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. 
+This `CreateCatalogImage` endpoint 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.
 
 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).
 
@@ -323,8 +324,8 @@ catalogApi.createCatalogImageAsync(request, null).thenAccept(result -> {
 
 ## Catalog Info
 
-Returns information about the Square Catalog API, such as batch size
-limits for `BatchUpsertCatalogObjects`.
+Retrieves information about the Square Catalog API, such as batch size
+limits that can be used by the `BatchUpsertCatalogObjects` endpoint.
 
 ```java
 CompletableFuture<CatalogInfoResponse> catalogInfoAsync()
@@ -509,17 +510,16 @@ catalogApi.retrieveCatalogObjectAsync(objectId, null).thenAccept(result -> {
 
 ## Search Catalog Objects
 
-Queries the targeted catalog using a variety of query expressions.
+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, 
 
-Supported query expressions are of the following types:
-- [CatalogQuerySortedAttribute](#type-catalogquerysortedattribute),
-- [CatalogQueryExact](#type-catalogqueryexact),
-- [CatalogQueryRange](#type-catalogqueryrange),
-- [CatalogQueryText](#type-catalogquerytext),
-- [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax),
-- [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist),
-- [CatalogQueryItemsForItemOptions](#type-catalogqueryitemsforitemoptions), and
-- [CatalogQueryItemVariationsForItemOptionValues](#type-catalogqueryitemvariationsforitemoptionvalues).
+This (`SearchCatalogObjects`) endpoint differs from the [SearchCatalogItems](#endpoint-Catalog-SearchCatalogItems)
+endpoint in the following aspects:
+
+- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.
+- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.
+- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.
+- The both endpoints have different call conventions, including the query filter formats.
 
 ```java
 CompletableFuture<SearchCatalogObjectsResponse> searchCatalogObjectsAsync(
@@ -562,6 +562,94 @@ catalogApi.searchCatalogObjectsAsync(body).thenAccept(result -> {
 });
 ```
 
+## 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, 
+
+This (`SearchCatalogItems`) endpoint differs from the [SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
+endpoint in the following aspects:
+
+- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.
+- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.
+- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.
+- The both endpoints use different call conventions, including the query filter formats.
+
+```java
+CompletableFuture<SearchCatalogItemsResponse> searchCatalogItemsAsync(
+    final SearchCatalogItemsRequest body)
+```
+
+### Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`SearchCatalogItemsRequest`](/doc/models/search-catalog-items-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
+
+[`SearchCatalogItemsResponse`](/doc/models/search-catalog-items-response.md)
+
+### Example Usage
+
+```java
+List<String> bodyCategoryIds = new LinkedList<>();
+bodyCategoryIds.add("WINE_CATEGORY_ID");
+List<String> bodyStockLevels = new LinkedList<>();
+bodyStockLevels.add("OUT");
+bodyStockLevels.add("LOW");
+List<String> bodyEnabledLocationIds = new LinkedList<>();
+bodyEnabledLocationIds.add("ATL_LOCATION_ID");
+List<String> bodyProductTypes = new LinkedList<>();
+bodyProductTypes.add("REGULAR");
+List<CustomAttributeFilter> bodyCustomAttributeFilters = new LinkedList<>();
+
+CustomAttributeFilter bodyCustomAttributeFilters0 = new CustomAttributeFilter.Builder()
+    .customAttributeDefinitionId("VEGAN_DEFINITION_ID")
+    .boolFilter(true)
+    .build();
+bodyCustomAttributeFilters.add(bodyCustomAttributeFilters0);
+
+CustomAttributeFilter bodyCustomAttributeFilters1 = new CustomAttributeFilter.Builder()
+    .customAttributeDefinitionId("BRAND_DEFINITION_ID")
+    .stringFilter("Dark Horse")
+    .build();
+bodyCustomAttributeFilters.add(bodyCustomAttributeFilters1);
+
+Range bodyCustomAttributeFilters2NumberFilter = new Range.Builder()
+    .min("2017")
+    .max("2018")
+    .build();
+CustomAttributeFilter bodyCustomAttributeFilters2 = new CustomAttributeFilter.Builder()
+    .key("VINTAGE")
+    .numberFilter(bodyCustomAttributeFilters2NumberFilter)
+    .build();
+bodyCustomAttributeFilters.add(bodyCustomAttributeFilters2);
+
+CustomAttributeFilter bodyCustomAttributeFilters3 = new CustomAttributeFilter.Builder()
+    .customAttributeDefinitionId("VARIETAL_DEFINITION_ID")
+    .build();
+bodyCustomAttributeFilters.add(bodyCustomAttributeFilters3);
+
+SearchCatalogItemsRequest body = new SearchCatalogItemsRequest.Builder()
+    .textFilter("red")
+    .categoryIds(bodyCategoryIds)
+    .stockLevels(bodyStockLevels)
+    .enabledLocationIds(bodyEnabledLocationIds)
+    .limit(100)
+    .sortOrder("ASC")
+    .productTypes(bodyProductTypes)
+    .customAttributeFilters(bodyCustomAttributeFilters)
+    .build();
+
+catalogApi.searchCatalogItemsAsync(body).thenAccept(result -> {
+    // TODO success callback handler
+}).exceptionally(exception -> {
+    // TODO failure callback handler
+    return null;
+});
+```
+
 ## Update Item Modifier Lists
 
 Updates the [CatalogModifierList](#type-catalogmodifierlist) objects

doc/catalog.md

@@ -310,7 +310,7 @@ CompletableFuture<RetrieveInventoryChangesResponse> retrieveInventoryChangesAsyn
 |  --- | --- | --- | --- |
 | `catalogObjectId` | `String` | Template, Required | ID of the [CatalogObject](#type-catalogobject) to retrieve. |
 | `locationIds` | `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 the [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pagination) guide 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/working-with-apis/pagination) guide for more information. |
 
 ### Response Type