Merge pull request #9 from square/release/5.1.0.20200325

release

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## Version 5.1.0.20200325 (2020-03-25)
+## Existing API updates
+* **[Payments API](${SQUARE_TECH_REF}/payments-api).** In support of the existing [Delayed capture](payments-api/take-payments) for payments, the following fields are added to the [Payment](${SQUARE_TECH_REF}/objects/Payment) type:
+   * `delay_duration`. In a [CreatePayment](${SQUARE_TECH_REF}/payments-api/create-payment) request, you can set `autocomplete` to false to get  payment approval but not charge the payment source. You can now add this field to specify a time period to complete (or cancel) the payment. For more information, see [Delay capture](payments-api/take-payments).
+   * `delay_action`. Defines the action that Square takes on the payment when the `delay_duration` elapses. In this release, the API supports only the cancel payment action.
+   * `delayed_until`. Provides the date and time on Square servers when Square applies `delay_action` on the payment.
+
 ## Version 5.0.0.20200226 (2020-02-26)
 ## API releases
 * **GA release**: All SDKs have been updated to support the new Bank Accounts and CashDrawerShifts APIs.

doc/models/cancel-payment-response.md

@@ -18,7 +18,7 @@ Return value from the [CancelPayment](#endpoint-payments-cancelpayment) endpoint
 ```json
 {
   "payment": {
-    "id": "YNR82sYrdgYlEEvJHnkJ7jrRuaB",
+    "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf",
     "created_at": "2018-10-17T20:38:46.743Z",
     "updated_at": "2018-10-17T20:38:57.693Z",
     "amount_money": {
@@ -42,14 +42,22 @@ Return value from the [CancelPayment](#endpoint-payments-cancelpayment) endpoint
         "last_4": "1234",
         "exp_month": 2,
         "exp_year": 2024,
-        "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP"
+        "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP",
+        "card_type": "DEBIT",
+        "prepaid_type": "PREPAID",
+        "bin": "411111"
       },
       "entry_method": "KEYED",
       "cvv_status": "CVV_ACCEPTED",
       "avs_status": "AVS_ACCEPTED",
-      "auth_result_code": "eWZBDh"
+      "auth_result_code": "eWZBDh",
+      "statement_description": "SQ *MY MERCHANT"
     },
-    "reference_id": "12323232323"
+    "location_id": "XTI0H92143A39",
+    "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3",
+    "reference_id": "123456",
+    "note": "Brief description",
+    "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I"
   }
 }
 ```

doc/models/catalog-custom-attribute-definition-app-visibility.md

@@ -0,0 +1,17 @@
+## Catalog Custom Attribute Definition App Visibility
+
+Defines the visibility of a custom attribute to applications other than their
+creating application.
+
+### Enumeration
+
+`CatalogCustomAttributeDefinitionAppVisibility`
+
+### Fields
+
+| Name | Description |
+|  --- | --- |
+| `APPVISIBILITYHIDDEN` | Other applications cannot read this custom attribute. |
+| `APPVISIBILITYREADONLY` | Other applications can read this custom attribute definition and<br>values. |
+| `APPVISIBILITYREADWRITEVALUES` | Other applications can read and write custom attribute values on objects.<br>They can read but cannot edit the custom attribute definition. |
+

doc/models/catalog-custom-attribute-definition-selection-config-custom-attribute-selection.md

@@ -0,0 +1,24 @@
+## Catalog Custom Attribute Definition Selection Config Custom Attribute Selection
+
+A named selection for this `SELECTION`-type custom attribute definition.
+
+### Structure
+
+`CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection`
+
+### Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `Uid` | `String` | Optional | Unique ID set by Square. |
+| `Name` | `String` |  | Selection name, unique within `allowed_selections`.<br>Required. Min length of 1, max length of 255. |
+
+### Example (as JSON)
+
+```json
+{
+  "uid": null,
+  "name": "name0"
+}
+```
+

doc/models/catalog-custom-attribute-definition-selection-config.md

@@ -0,0 +1,24 @@
+## Catalog Custom Attribute Definition Selection Config
+
+Configuration associated with `SELECTION`-type custom attribute definitions.
+
+### Structure
+
+`CatalogCustomAttributeDefinitionSelectionConfig`
+
+### Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `MaxAllowedSelections` | `Integer` | Optional | The maximum number of selections that can be set. The maximum value for this<br>attribute is 100. May be modified, but changing the value will not<br>affect existing custom attribute values on objects. Clients need to<br>handle Custom Attributes with more selected values than allowed by this limit. |
+| `AllowedSelections` | [`List<CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection>`](/doc/models/catalog-custom-attribute-definition-selection-config-custom-attribute-selection.md) | Optional | The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100<br>selections can be defined. Can be modified. |
+
+### Example (as JSON)
+
+```json
+{
+  "max_allowed_selections": null,
+  "allowed_selections": null
+}
+```
+

doc/models/catalog-custom-attribute-definition-seller-visibility.md

@@ -0,0 +1,17 @@
+## Catalog Custom Attribute Definition Seller Visibility
+
+Defines the visibility of a custom attribute to sellers in Square
+client applications, Square APIs or in Square UIs (including Square Point
+of Sale applications and Square Dashboard).
+
+### Enumeration
+
+`CatalogCustomAttributeDefinitionSellerVisibility`
+
+### Fields
+
+| Name | Description |
+|  --- | --- |
+| `SELLERVISIBILITYHIDDEN` | Sellers cannot read this custom attribute in Square client<br>applications or Square APIs. |
+| `SELLERVISIBILITYREADWRITEVALUES` | Sellers can read and write this custom attribute value in catalog objects,<br>but cannot edit the custom attribute definition. |
+

doc/models/catalog-custom-attribute-definition-string-config.md

@@ -0,0 +1,22 @@
+## Catalog Custom Attribute Definition String Config
+
+Configuration associated with Custom Attribute Definitions of type `STRING`.
+
+### Structure
+
+`CatalogCustomAttributeDefinitionStringConfig`
+
+### Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `EnforceUniqueness` | `Boolean` | Optional | If true, each Custom Attribute instance associated with this Custom Attribute<br>Definition must have a unique value within the seller's catalog. For<br>example, this may be used for a value like a SKU that should not be<br>duplicated within a seller's catalog. May not be modified after the<br>definition has been created. |
+
+### Example (as JSON)
+
+```json
+{
+  "enforce_uniqueness": null
+}
+```
+

doc/models/catalog-custom-attribute-definition-type.md

@@ -0,0 +1,17 @@
+## Catalog Custom Attribute Definition Type
+
+Defines the possible types for a custom attribute.
+
+### Enumeration
+
+`CatalogCustomAttributeDefinitionType`
+
+### Fields
+
+| Name | Description |
+|  --- | --- |
+| `STRING` | A free-form string containing up to 255 characters. |
+| `BOOLEAN` | A `true` or `false` value. |
+| `NUMBER` | Integer divided by 100,000. |
+| `SELECTION` | One or more choices from `allowed_selections`. |
+

doc/models/catalog-custom-attribute-definition.md

@@ -0,0 +1,46 @@
+## Catalog Custom Attribute Definition
+
+Contains information defining a custom attribute. Custom attributes are
+intended to store additional information about a catalog object or to associate a
+catalog object with an entity in another system. Do not use custom attributes
+to store any sensitive information (personally identifiable information, card details, etc.).
+[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)
+
+### Structure
+
+`CatalogCustomAttributeDefinition`
+
+### Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `Type` | [`String`](/doc/models/catalog-custom-attribute-definition-type.md) |  | Defines the possible types for a custom attribute. |
+| `Name` | `String` |  | The name of this definition for API and seller-facing UI purposes.<br>The name must be unique within the (merchant, application_id) pair. Required.<br>May not be empty and may not exceed 255 characters. Can be modified after creation. |
+| `Description` | `String` | Optional | Seller-oriented description of the meaning of this Custom Attribute,<br>any constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs. |
+| `SourceApplication` | [`SourceApplication`](/doc/models/source-application.md) | Optional | Provides information about the application used to generate an inventory<br>change. |
+| `AllowedObjectTypes` | [`List<String>`](/doc/models/catalog-object-type.md) | Optional | The set of Catalog Object Types that this Custom Attribute may be applied to.<br>Currently, only `ITEM` and `ITEM_VARIATION` are allowed.<br>See [CatalogObjectType](#type-catalogobjecttype) for possible values |
+| `SellerVisibility` | [`String`](/doc/models/catalog-custom-attribute-definition-seller-visibility.md) | Optional | Defines the visibility of a custom attribute to sellers in Square<br>client applications, Square APIs or in Square UIs (including Square Point<br>of Sale applications and Square Dashboard). |
+| `AppVisibility` | [`String`](/doc/models/catalog-custom-attribute-definition-app-visibility.md) | Optional | Defines the visibility of a custom attribute to applications other than their<br>creating application. |
+| `StringConfig` | [`CatalogCustomAttributeDefinitionStringConfig`](/doc/models/catalog-custom-attribute-definition-string-config.md) | Optional | Configuration associated with Custom Attribute Definitions of type `STRING`. |
+| `SelectionConfig` | [`CatalogCustomAttributeDefinitionSelectionConfig`](/doc/models/catalog-custom-attribute-definition-selection-config.md) | Optional | Configuration associated with `SELECTION`-type custom attribute definitions. |
+| `CustomAttributeUsageCount` | `Integer` | Optional | __Read-only.__ The number of custom attributes that reference this<br>custom attribute definition. Set by the server in response to a ListCatalog<br>request with `include_counts` set to `true`.  If the actual count is greater<br>than 100, `custom_attribute_usage_count` will be set to `100`. |
+| `Key` | `String` | Optional | The name of the desired custom attribute key that can be used to access<br>the custom attribute value on catalog objects. Cannot be modified after the<br>custom attribute definition has been created. |
+
+### Example (as JSON)
+
+```json
+{
+  "type": "NUMBER",
+  "name": "name0",
+  "description": null,
+  "source_application": null,
+  "allowed_object_types": null,
+  "seller_visibility": null,
+  "app_visibility": null,
+  "string_config": null,
+  "selection_config": null,
+  "custom_attribute_usage_count": null,
+  "key": null
+}
+```
+

doc/models/catalog-custom-attribute-value.md

@@ -0,0 +1,38 @@
+## Catalog Custom Attribute Value
+
+An instance of a custom attribute. Custom attributes can be defined and
+added to `ITEM` and `ITEM_VARIATION` type catalog objects.
+[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes).
+
+### Structure
+
+`CatalogCustomAttributeValue`
+
+### Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `Name` | `String` | Optional | The name of the custom attribute. |
+| `StringValue` | `String` | Optional | The string value of the custom attribute.  Populated if `type` = `STRING`. |
+| `CustomAttributeDefinitionId` | `String` | Optional | __Read-only.__ The custom attribute definition this value belongs to. |
+| `Type` | [`String`](/doc/models/catalog-custom-attribute-definition-type.md) | Optional | Defines the possible types for a custom attribute. |
+| `NumberValue` | `String` | Optional | Populated if `type` = `NUMBER`. Contains a string<br>representation of a decimal number, using a `.` as the decimal separator. |
+| `BooleanValue` | `Boolean` | Optional | A `true` or `false` value. Populated if `type` = `BOOLEAN`. |
+| `SelectionUidValues` | `List<String>` | Optional | One or more choices from `allowed_selections`. Populated if `type` = `SELECTION`. |
+| `Key` | `String` | Optional | __Read-only.__ A copy of key from the associated custom attribute definition. |
+
+### Example (as JSON)
+
+```json
+{
+  "name": null,
+  "string_value": null,
+  "custom_attribute_definition_id": null,
+  "type": null,
+  "number_value": null,
+  "boolean_value": null,
+  "selection_uid_values": null,
+  "key": null
+}
+```
+

doc/models/catalog-object-batch.md

@@ -23,6 +23,7 @@ A batch of catalog objects.
       "updated_at": null,
       "version": null,
       "is_deleted": null,
+      "custom_attribute_values": null,
       "catalog_v1_ids": null,
       "present_at_all_locations": null,
       "present_at_location_ids": null,
@@ -41,14 +42,16 @@ A batch of catalog objects.
       "image_data": null,
       "measurement_unit_data": null,
       "item_option_data": null,
-      "item_option_value_data": null
+      "item_option_value_data": null,
+      "custom_attribute_definition_data": null
     },
     {
       "type": "DISCOUNT",
       "id": "id9",
       "updated_at": null,
       "version": null,
       "is_deleted": null,
+      "custom_attribute_values": null,
       "catalog_v1_ids": null,
       "present_at_all_locations": null,
       "present_at_location_ids": null,
@@ -67,7 +70,8 @@ A batch of catalog objects.
       "image_data": null,
       "measurement_unit_data": null,
       "item_option_data": null,
-      "item_option_value_data": null
+      "item_option_value_data": null,
+      "custom_attribute_definition_data": null
     }
   ]
 }

doc/models/catalog-object.md

@@ -29,6 +29,7 @@ For a more detailed discussion of the Catalog data model, please see the
 | `UpdatedAt` | `String` | Optional | Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"`<br>would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. |
 | `Version` | `Long` | Optional | The version of the object. When updating an object, the version supplied<br>must match the version in the database, otherwise the write will be rejected as conflicting. |
 | `IsDeleted` | `Boolean` | Optional | If `true`, the object has been deleted from the database. Must be `false` for new objects<br>being inserted. When deleted, the `updated_at` field will equal the deletion time. |
+| `CustomAttributeValues` | [`Map<String, CatalogCustomAttributeValue>`](/doc/models/catalog-custom-attribute-value.md) | Optional | Application-defined key/value attributes that are set at a global (location-independent) level.<br>Values from the `*_data` fields may not be duplicated. Custom Attribute fields are intended to store additional<br>information about a Catalog Object or associations with an entity in another system. Do not use custom attributes<br>to store any sensitive information (personally identifiable information, card details, etc.).<br><br>For CustomAttributesDefinitions defined by the app making the request, the map key is the key defined in<br>CustomAttributeDefinition (eg. “reference_id”). For CustomAttributesDefinitions by other apps, the map key is<br>the key defined in CustomAttributeDefinition prefixed with the application ID and a colon<br>(eg. “abcd1234:reference_id”). |
 | `CatalogV1Ids` | [`List<CatalogV1Id>`](/doc/models/catalog-v1-id.md) | Optional | The Connect v1 IDs for this object at each location where it is present, where they<br>differ from the object's Connect V2 ID. The field will only be present for objects that<br>have been created or modified by legacy APIs. |
 | `PresentAtAllLocations` | `Boolean` | Optional | If `true`, this object is present at all locations (including future locations), except where specified in<br>the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),<br>except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. |
 | `PresentAtLocationIds` | `List<String>` | Optional | A list of locations where the object is present, even if `present_at_all_locations` is `false`. |
@@ -48,6 +49,7 @@ For a more detailed discussion of the Catalog data model, please see the
 | `MeasurementUnitData` | [`CatalogMeasurementUnit`](/doc/models/catalog-measurement-unit.md) | Optional | Represents the unit used to measure a `CatalogItemVariation` and<br>specifies the precision for decimal quantities. |
 | `ItemOptionData` | [`CatalogItemOption`](/doc/models/catalog-item-option.md) | Optional | A group of variations for a `CatalogItem`. |
 | `ItemOptionValueData` | [`CatalogItemOptionValue`](/doc/models/catalog-item-option-value.md) | Optional | An enumerated value that can link a<br>`CatalogItemVariation` to an item option as one of<br>its item option values. |
+| `CustomAttributeDefinitionData` | [`CatalogCustomAttributeDefinition`](/doc/models/catalog-custom-attribute-definition.md) | Optional | Contains information defining a custom attribute. Custom attributes are<br>intended to store additional information about a catalog object or to associate a<br>catalog object with an entity in another system. Do not use custom attributes<br>to store any sensitive information (personally identifiable information, card details, etc.).<br>[Read more about custom attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes) |
 
 ### Example (as JSON)
 
@@ -58,6 +60,7 @@ For a more detailed discussion of the Catalog data model, please see the
   "updated_at": null,
   "version": null,
   "is_deleted": null,
+  "custom_attribute_values": null,
   "catalog_v1_ids": null,
   "present_at_all_locations": null,
   "present_at_location_ids": null,
@@ -76,7 +79,8 @@ For a more detailed discussion of the Catalog data model, please see the
   "image_data": null,
   "measurement_unit_data": null,
   "item_option_data": null,
-  "item_option_value_data": null
+  "item_option_value_data": null,
+  "custom_attribute_definition_data": null
 }
 ```