--- title: "BatchRetrieveCatalogObjects" method: POST path: "/v2/catalog/batch-retrieve" tags: ["Catalog"] --- # BatchRetrieveCatalogObjects `POST /v2/catalog/batch-retrieve` Returns a set of objects based on the provided ID. Each [CatalogItem](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItem) returned in the set includes all of its child information including: all of its [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) objects, references to its [CatalogModifierList](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogModifierList) objects, and the ids of any [CatalogTax](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogTax) objects that apply to it. ## Request body - BatchRetrieveCatalogObjectsRequest - `catalog_version` integer — The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject)s' `version` attribute. - `include_related_objects` boolean — If `true`, the response will include additional objects that are related to the requested objects, as follows: If the `objects` field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the `related_objects` field of the response. If the `objects` field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the `related_objects` field of the response. - `object_ids` string[], required — The IDs of the CatalogObjects to be retrieved. ## Response `200` Success - BatchRetrieveCatalogObjectsResponse - `errors` Error[] — Any errors that occurred during the request. - `category` string, required — The high-level category for the error. - `code` string, required — The specific code of the error. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `objects` CatalogObject[] — A list of [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject)s returned. - `absent_at_location_ids` string[] — A list of locations where the object is not present, even if `present_at_all_locations` is `true`. This can include locations that are deactivated. - `catalog_v1_ids` CatalogV1Id[] — The Connect v1 IDs for this object at each location where it is present, where they differ from the object's Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs. - `catalog_v1_id` string — The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID. - `location_id` string — The ID of the `Location` this Connect V1 ID is associated with. - `category_data` CatalogCategory — A category to which a `CatalogItem` instance belongs. - `name` string — The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `custom_attribute_definition_data` CatalogCustomAttributeDefinition — 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) - `allowed_object_types` string[], required — The set of Catalog Object Types that this Custom Attribute may be applied to. Currently, only `ITEM` and `ITEM_VARIATION` are allowed. At least one type must be included. - `app_visibility` string — The visibility of a custom attribute to applications other than the application that created the attribute. - `custom_attribute_usage_count` integer — __Read-only.__ The number of custom attributes that reference this custom attribute definition. Set by the server in response to a ListCatalog request with `include_counts` set to `true`. If the actual count is greater than 100, `custom_attribute_usage_count` will be set to `100`. - `description` string — Seller-oriented description of the meaning of this Custom Attribute, any constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs. - `key` string — The name of the desired custom attribute key that can be used to access the custom attribute value on catalog objects. Cannot be modified after the custom attribute definition has been created. Must be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`. - `name` string, required — The name of this definition for API and seller-facing UI purposes. The name must be unique within the (merchant, application) pair. Required. May not be empty and may not exceed 255 characters. Can be modified after creation. - `number_config` CatalogCustomAttributeDefinitionNumberConfig - `precision` integer — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in number custom attribute values For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 5 - `selection_config` CatalogCustomAttributeDefinitionSelectionConfig — Configuration associated with `SELECTION`-type custom attribute definitions. - `allowed_selections` CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection[] — The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100 selections can be defined. Can be modified. - `name` string, required — Selection name, unique within `allowed_selections`. - `uid` string — Unique ID set by Square. - `max_allowed_selections` integer — The maximum number of selections that can be set. The maximum value for this attribute is 100. The default value is 1. The value can be modified, but changing the value will not affect existing custom attribute values on objects. Clients need to handle custom attributes with more selected values than allowed by this limit. - `seller_visibility` string — The visibility of a custom attribute in seller-facing UIs (including Square Point of Sale applications and Square Dashboard). May be modified. - `source_application` SourceApplication — Provides information about the application used to generate a change. - `application_id` string — Read-only Square ID assigned to the application. Only used for [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type `EXTERNAL_API`. - `name` string — Read-only display name assigned to the application (e.g. `"Custom Application"`, `"Square POS 4.74 for Android"`). - `product` string — Read-only [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type for the application. - `string_config` CatalogCustomAttributeDefinitionStringConfig — Configuration associated with Custom Attribute Definitions of type `STRING`. - `enforce_uniqueness` boolean — If true, each Custom Attribute instance associated with this Custom Attribute Definition must have a unique value within the seller's catalog. For example, this may be used for a value like a SKU that should not be duplicated within a seller's catalog. May not be modified after the definition has been created. - `type` string, required — The type of this custom attribute. Cannot be modified after creation. Required. - `custom_attribute_values` object — A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a [CatalogCustomAttributeValue](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogCustomAttributeValue) object. The key is the `key` attribute value defined in the associated [CatalogCustomAttributeDefinition](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogCustomAttributeDefinition) object defined by the application making the request. If the `CatalogCustomAttributeDefinition` object is defined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by the defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of `"cocoa_brand"` and the defining application ID is `"abcd1234"`, the key in the map is `"abcd1234:cocoa_brand"` if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply `"cocoa_brand"`. Application-defined custom attributes that are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). - `discount_data` CatalogDiscount — A discount applicable to items. - `amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `discount_type` string — Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. - `label_color` string — The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code. - `modify_tax_basis` string — Indicates whether this discount should reduce the price used to calculate tax. Most discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must be calculated based on an item's price, ignoring a particular discount. For example, in many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a customer pays but does not reduce the sale price used to calculate how much sales tax is due. In this case, the discount representing that manufacturer coupon should have `DO_NOT_MODIFY_TAX_BASIS` for this field. If you are unsure whether you need to use this field, consult your tax professional. - `name` string — The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `percentage` string — The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal separator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type` is `VARIABLE_PERCENTAGE`. Do not use this field for amount-based or variable discounts. - `pin_required` boolean — Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app. - `id` string, required — An identifier to reference this object in the catalog. When a new `CatalogObject` is inserted, the client should set the id to a temporary identifier starting with a "`#`" character. Other objects being inserted or updated within the same request may use this identifier to refer to the new object. When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references. - `image_data` CatalogImage — An image file to use in Square catalogs. It can be associated with catalog items, item variations, and categories. - `caption` string — A caption that describes what is shown in the image. Displayed in the Square Online Store. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/search-catalog-objects). - `name` string — The internal name to identify this image in calls to the Square API. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/search-catalog-objects). It is not unique and should not be shown in a buyer facing context. - `url` string — The URL of this image, generated by Square after an image is uploaded using the [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/create-catalog-image) endpoint. - `image_id` string — Identifies the `CatalogImage` attached to this `CatalogObject`. - `is_deleted` boolean — If `true`, the object has been deleted from the database. Must be `false` for new objects being inserted. When deleted, the `updated_at` field will equal the deletion time. - `item_data` CatalogItem — A [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog. - `abbreviation` string — The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. This attribute is searchable, and its value length is of Unicode code points. - `available_electronically` boolean — If `true`, the item can be added to electronically fulfilled orders from the merchant's online store. - `available_for_pickup` boolean — If `true`, the item can be added to pickup orders from the merchant's online store. - `available_online` boolean — If `true`, the item can be added to shipping orders from the merchant's online store. - `category_id` string — The ID of the item's category, if any. - `description` string — The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `item_options` CatalogItemOptionForItem[] — List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options. - `item_option_id` string — The unique id of the item option, used to form the dimensions of the item option matrix in a specified order. - `label_color` string — The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code. - `modifier_list_info` CatalogItemModifierListInfo[] — A set of `CatalogItemModifierListInfo` objects representing the modifier lists that apply to this item, along with the overrides and min and max limits that are specific to this item. Modifier lists may also be added to or deleted from an item using `UpdateItemModifierLists`. - `enabled` boolean — If `true`, enable this `CatalogModifierList`. The default value is `true`. - `max_selected_modifiers` integer — If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`. - `min_selected_modifiers` integer — If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`. - `modifier_list_id` string, required — The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`. - `modifier_overrides` CatalogModifierOverride[] — A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default. - `modifier_id` string, required — The ID of the `CatalogModifier` whose default behavior is being overridden. - `on_by_default` boolean — If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`. - `name` string — The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points. - `product_type` string — The product type of the item. May not be changed once an item has been created. Only items of product type `REGULAR` or `APPOINTMENTS_SERVICE` may be created by this API; items with other product types are read-only. - `skip_modifier_screen` boolean — If `false`, the Square Point of Sale app will present the `CatalogItem`'s details screen immediately, allowing the merchant to choose `CatalogModifier`s before adding the item to the cart. This is the default behavior. If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item's details. Third-party clients are encouraged to implement similar behaviors. - `sort_name` string — A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting. It is currently supported for sellers of the Japanese locale only. - `tax_ids` string[] — A set of IDs indicating the taxes enabled for this item. When updating an item, any taxes listed here will be added to the item. Taxes may also be added to or deleted from an item using `UpdateItemTaxes`. - `variations` CatalogObject[] — A list of [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) objects for this item. An item must have at least one variation. - `item_option_data` CatalogItemOption — A group of variations for a `CatalogItem`. - `description` string — The item option's human-readable description. Displayed in the Square Point of Sale app for the seller and in the Online Store or on receipts for the buyer. This is a searchable attribute for use in applicable query filters. - `display_name` string — The item option's display name for the customer. This is a searchable attribute for use in applicable query filters. - `name` string — The item option's display name for the seller. Must be unique across all item options. This is a searchable attribute for use in applicable query filters. - `show_colors` boolean — If true, display colors for entries in `values` when present. - `values` CatalogObject[] — A list of CatalogObjects containing the `CatalogItemOptionValue`s for this item. - `item_option_value_data` CatalogItemOptionValue — An enumerated value that can link a `CatalogItemVariation` to an item option as one of its item option values. - `color` string — The HTML-supported hex color for the item option (e.g., "#ff8d4e85"). Only displayed if `show_colors` is enabled on the parent `ItemOption`. When left unset, `color` defaults to white ("#ffffff") when `show_colors` is enabled on the parent `ItemOption`. - `description` string — A human-readable description for the option value. This is a searchable attribute for use in applicable query filters. - `item_option_id` string — Unique ID of the associated item option. - `name` string — Name of this item option value. This is a searchable attribute for use in applicable query filters. - `ordinal` integer — Determines where this option value appears in a list of option values. - `item_variation_data` CatalogItemVariation — An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations. - `available_for_booking` boolean — If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking. - `inventory_alert_threshold` integer — If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer. - `inventory_alert_type` string — Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. - `item_id` string — The ID of the `CatalogItem` associated with this item variation. - `item_option_values` CatalogItemOptionValueForItemVariation[] — List of item option values associated with this item variation. Listed in the same order as the item options of the parent item. - `item_option_id` string — The unique id of an item option. - `item_option_value_id` string — The unique id of the selected value for the item option. - `location_overrides` ItemVariationLocationOverrides[] — Per-location price and inventory overrides. - `inventory_alert_threshold` integer — If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer. - `inventory_alert_type` string — Indicates whether the `CatalogItemVariation` displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. - `location_id` string — The ID of the `Location`. This can include locations that are deactivated. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `pricing_type` string — The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`. - `track_inventory` boolean — If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`. - `measurement_unit_id` string — ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity sold of this item variation. If left unset, the item will be sold in whole quantities. - `name` string — The item variation's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal for each item variation within a parent `CatalogItem` is set according to the item variations's position. On reads, the value is not guaranteed to be sequential or unique. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `pricing_type` string — Indicates whether the item variation's price is fixed or determined at the time of sale. - `service_duration` integer — If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For example, a 30 minute appointment would have the value `1800000`, which is equal to 30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second). - `sku` string — The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters. - `stockable` boolean — Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). For backward compatibility missing values will be interpreted as TRUE. - `stockable_conversion` CatalogStockConversion — Represents the rule of conversion between a stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) and a non-stockable sell-by or receive-by `CatalogItemVariation` that share the same underlying stock. - `nonstockable_quantity` string, required — The converted equivalent quantity of the non-stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) in its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together define the conversion ratio between stockable item variation and the non-stockable item variation. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point. - `stockable_item_variation_id` string, required — References to the stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) for this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation` defined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`. This immutable field must reference a stockable `CatalogItemVariation` that shares the parent [CatalogItem](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItem) of the converted `CatalogItemVariation.` - `stockable_quantity` string, required — The quantity of the stockable item variation (as identified by `stockable_item_variation_id`) equivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`) as defined by this stock conversion. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point. - `team_member_ids` string[] — Tokens of employees that can perform the service represented by this variation. Only valid for variations of type `APPOINTMENTS_SERVICE`. - `track_inventory` boolean — If `true`, inventory tracking is active for the variation. - `upc` string — The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters. The value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard, Square Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned to this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps unless it is updated to fit the expected format. - `user_data` string — Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points. - `measurement_unit_data` CatalogMeasurementUnit — Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities. - `measurement_unit` MeasurementUnit — Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: `custom_unit`, `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. - `area_unit` string — Represents a standard area unit. - `custom_unit` MeasurementUnitCustom — The information needed to define a custom unit, provided by the seller. - `abbreviation` string, required — The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports. - `name` string, required — The name of the custom unit, for example "bushel". - `generic_unit` string — Reserved for API integrations that lack the ability to specify a real measurement unit - `length_unit` string — Represents a standard length unit. - `time_unit` string — Represents a standard unit of time. - `type` string — Represents the type of the measurement unit. - `volume_unit` string — Represents a standard volume unit. - `weight_unit` string — Represents a standard unit of weight or mass. - `precision` integer — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 3 - `modifier_data` CatalogModifier — A modifier applicable to items at the time of sale. - `modifier_list_id` string — The ID of the `CatalogModifierList` associated with this modifier. - `name` string — The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — Determines where this `CatalogModifier` appears in the `CatalogModifierList`. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `modifier_list_data` CatalogModifierList — A list of modifiers applicable to items at the time of sale. For example, a "Condiments" modifier list applicable to a "Hot Dog" item may contain "Ketchup", "Mustard", and "Relish" modifiers. Use the `selection_type` field to specify whether or not multiple selections from the modifier list are allowed. - `modifiers` CatalogObject[] — The options included in the `CatalogModifierList`. You must include at least one `CatalogModifier`. Each CatalogObject must have type `MODIFIER` and contain `CatalogModifier` data. - `name` string — The name for the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — Determines where this modifier list appears in a list of `CatalogModifierList` values. - `selection_type` string — Indicates whether multiple options from the modifier list can be applied to a single `CatalogItem`. - `present_at_all_locations` boolean — If `true`, this object is present at all locations (including future locations), except where specified in the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations), except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. - `present_at_location_ids` string[] — A list of locations where the object is present, even if `present_at_all_locations` is `false`. This can include locations that are deactivated. - `pricing_rule_data` CatalogPricingRule — Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period. - `apply_products_id` string — __Deprecated__: Please use the `exclude_products_id` field to apply an exclude set instead. Exclude sets allow better control over quantity ranges and offer more flexibility for which matched items receive a discount. `CatalogProductSet` to apply the pricing to. An apply rule matches within the subset of the cart that fits the match rules (the match set). An apply rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules. - `customer_group_ids_any` string[] — A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule. Notice that a group ID is generated by the Customers API. If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer has a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount applies only to matched products sold to customers belonging to the specified customer groups. - `discount_id` string — Unique ID for the `CatalogDiscount` to take off the price of all matched items. - `exclude_products_id` string — `CatalogProductSet` to exclude from the pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules. - `exclude_strategy` string — If an `exclude_products_id` was given, controls which subset of matched products is excluded from any discounts. Default value: `LEAST_EXPENSIVE` - `match_products_id` string — Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule matches within the entire cart, and can match multiple times. This field will always be set. - `name` string — User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off". - `time_period_ids` string[] — A list of unique IDs for the catalog time periods when this pricing rule is in effect. If left unset, the pricing rule is always in effect. - `valid_from_date` string — Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD). - `valid_from_local_time` string — Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. - `valid_until_date` string — Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD). - `valid_until_local_time` string — Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. - `product_set_data` CatalogProductSet — Represents a collection of catalog objects for the purpose of applying a `PricingRule`. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations. - `all_products` boolean — If set to `true`, the product set will include every item in the catalog. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. - `name` string — User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items". - `product_ids_all` string[] — Unique IDs for any `CatalogObject` included in this product set. All objects in this set must be included in an order for a pricing rule to apply. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs. - `product_ids_any` string[] — Unique IDs for any `CatalogObject` included in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply. This can be used with `product_ids_all` in a parent `CatalogProductSet` to match groups of products for a bulk discount, such as a discount for an entree and side combo. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs. - `quantity_exact` integer — If set, there must be exactly this many items from `products_any` or `products_all` in the cart for the discount to apply. Cannot be combined with either `quantity_min` or `quantity_max`. - `quantity_max` integer — If set, the pricing rule will apply to a maximum of this many items from `products_any` or `products_all`. - `quantity_min` integer — If set, there must be at least this many items from `products_any` or `products_all` in a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if `quantity_exact`, `quantity_min` and `quantity_max` are all unspecified. - `quick_amounts_settings_data` CatalogQuickAmountsSettings — A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts. - `amounts` CatalogQuickAmount[] — Represents a set of Quick Amounts at this location. - `amount` Money, required — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `ordinal` integer — The order in which this Quick Amount should be displayed. - `score` integer — Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100]. MANUAL type amount will always have score = 100. - `type` string, required — Represents the type of the Quick Amount. - `eligible_for_auto_amounts` boolean — Represents location's eligibility for auto amounts The boolean should be consistent with whether there are AUTO amounts in the `amounts`. - `option` string, required — Represents the option seller currently uses on Quick Amounts. - `subscription_plan_data` CatalogSubscriptionPlan — Describes a subscription plan. For more information, see [Set Up and Manage a Subscription Plan](https://developer.squareup.com/docs/subscriptions-api/setup-plan). - `name` string, required — The name of the plan. - `phases` SubscriptionPhase[], required — A list of SubscriptionPhase containing the [SubscriptionPhase](https://developer.squareup.com/reference/square_2021-08-18/objects/SubscriptionPhase) for this plan. - `cadence` string, required — The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created. - `ordinal` integer — The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. - `periods` integer — The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created. - `recurring_price_money` Money, required — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `uid` string — The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created. - `tax_data` CatalogTax — A tax applicable to an item. - `applies_to_custom_amounts` boolean — If `true`, the fee applies to custom amounts entered into the Square Point of Sale app that are not associated with a particular `CatalogItem`. - `calculation_phase` string — Whether the tax is calculated based on a payment's subtotal or total. - `enabled` boolean — A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`). - `inclusion_type` string — Whether the tax is `ADDITIVE` or `INCLUSIVE`. - `name` string — The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `percentage` string — The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. A value of `7.5` corresponds to 7.5%. - `time_period_data` CatalogTimePeriod — Represents a time period - either a single period or a repeating period. - `event` string — An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which specifies the name, timing, duration and recurrence of this time period. Example: ``` DTSTART:20190707T180000 DURATION:P2H RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR ``` Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported. `DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT` and `END:VEVENT` is not required in the request. The response will always include them. - `type` string, required — The type of this object. Each object type has expected properties expressed in a structured format within its corresponding `*_data` field below. - `updated_at` string — 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"` would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. - `version` integer — The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting. - `related_objects` CatalogObject[] — A list of [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject)s referenced by the object in the `objects` field. - `absent_at_location_ids` string[] — A list of locations where the object is not present, even if `present_at_all_locations` is `true`. This can include locations that are deactivated. - `catalog_v1_ids` CatalogV1Id[] — The Connect v1 IDs for this object at each location where it is present, where they differ from the object's Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs. - `catalog_v1_id` string — The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID. - `location_id` string — The ID of the `Location` this Connect V1 ID is associated with. - `category_data` CatalogCategory — A category to which a `CatalogItem` instance belongs. - `name` string — The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `custom_attribute_definition_data` CatalogCustomAttributeDefinition — 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) - `allowed_object_types` string[], required — The set of Catalog Object Types that this Custom Attribute may be applied to. Currently, only `ITEM` and `ITEM_VARIATION` are allowed. At least one type must be included. - `app_visibility` string — The visibility of a custom attribute to applications other than the application that created the attribute. - `custom_attribute_usage_count` integer — __Read-only.__ The number of custom attributes that reference this custom attribute definition. Set by the server in response to a ListCatalog request with `include_counts` set to `true`. If the actual count is greater than 100, `custom_attribute_usage_count` will be set to `100`. - `description` string — Seller-oriented description of the meaning of this Custom Attribute, any constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs. - `key` string — The name of the desired custom attribute key that can be used to access the custom attribute value on catalog objects. Cannot be modified after the custom attribute definition has been created. Must be between 1 and 60 characters, and may only contain the characters `[a-zA-Z0-9_-]`. - `name` string, required — The name of this definition for API and seller-facing UI purposes. The name must be unique within the (merchant, application) pair. Required. May not be empty and may not exceed 255 characters. Can be modified after creation. - `number_config` CatalogCustomAttributeDefinitionNumberConfig - `precision` integer — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in number custom attribute values For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 5 - `selection_config` CatalogCustomAttributeDefinitionSelectionConfig — Configuration associated with `SELECTION`-type custom attribute definitions. - `allowed_selections` CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection[] — The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100 selections can be defined. Can be modified. - `name` string, required — Selection name, unique within `allowed_selections`. - `uid` string — Unique ID set by Square. - `max_allowed_selections` integer — The maximum number of selections that can be set. The maximum value for this attribute is 100. The default value is 1. The value can be modified, but changing the value will not affect existing custom attribute values on objects. Clients need to handle custom attributes with more selected values than allowed by this limit. - `seller_visibility` string — The visibility of a custom attribute in seller-facing UIs (including Square Point of Sale applications and Square Dashboard). May be modified. - `source_application` SourceApplication — Provides information about the application used to generate a change. - `application_id` string — Read-only Square ID assigned to the application. Only used for [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type `EXTERNAL_API`. - `name` string — Read-only display name assigned to the application (e.g. `"Custom Application"`, `"Square POS 4.74 for Android"`). - `product` string — Read-only [Product](https://developer.squareup.com/reference/square_2021-08-18/enums/Product) type for the application. - `string_config` CatalogCustomAttributeDefinitionStringConfig — Configuration associated with Custom Attribute Definitions of type `STRING`. - `enforce_uniqueness` boolean — If true, each Custom Attribute instance associated with this Custom Attribute Definition must have a unique value within the seller's catalog. For example, this may be used for a value like a SKU that should not be duplicated within a seller's catalog. May not be modified after the definition has been created. - `type` string, required — The type of this custom attribute. Cannot be modified after creation. Required. - `custom_attribute_values` object — A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a [CatalogCustomAttributeValue](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogCustomAttributeValue) object. The key is the `key` attribute value defined in the associated [CatalogCustomAttributeDefinition](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogCustomAttributeDefinition) object defined by the application making the request. If the `CatalogCustomAttributeDefinition` object is defined by another application, the `CatalogCustomAttributeDefinition`'s key attribute value is prefixed by the defining application ID. For example, if the `CatalogCustomAttributeDefinition` has a `key` attribute of `"cocoa_brand"` and the defining application ID is `"abcd1234"`, the key in the map is `"abcd1234:cocoa_brand"` if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply `"cocoa_brand"`. Application-defined custom attributes that are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). - `discount_data` CatalogDiscount — A discount applicable to items. - `amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `discount_type` string — Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. - `label_color` string — The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code. - `modify_tax_basis` string — Indicates whether this discount should reduce the price used to calculate tax. Most discounts should use `MODIFY_TAX_BASIS`. However, in some circumstances taxes must be calculated based on an item's price, ignoring a particular discount. For example, in many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a customer pays but does not reduce the sale price used to calculate how much sales tax is due. In this case, the discount representing that manufacturer coupon should have `DO_NOT_MODIFY_TAX_BASIS` for this field. If you are unsure whether you need to use this field, consult your tax professional. - `name` string — The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `percentage` string — The percentage of the discount as a string representation of a decimal number, using a `.` as the decimal separator and without a `%` sign. A value of `7.5` corresponds to `7.5%`. Specify a percentage of `0` if `discount_type` is `VARIABLE_PERCENTAGE`. Do not use this field for amount-based or variable discounts. - `pin_required` boolean — Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app. - `id` string, required — An identifier to reference this object in the catalog. When a new `CatalogObject` is inserted, the client should set the id to a temporary identifier starting with a "`#`" character. Other objects being inserted or updated within the same request may use this identifier to refer to the new object. When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references. - `image_data` CatalogImage — An image file to use in Square catalogs. It can be associated with catalog items, item variations, and categories. - `caption` string — A caption that describes what is shown in the image. Displayed in the Square Online Store. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/search-catalog-objects). - `name` string — The internal name to identify this image in calls to the Square API. This is a searchable attribute for use in applicable query filters using the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/search-catalog-objects). It is not unique and should not be shown in a buyer facing context. - `url` string — The URL of this image, generated by Square after an image is uploaded using the [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/create-catalog-image) endpoint. - `image_id` string — Identifies the `CatalogImage` attached to this `CatalogObject`. - `is_deleted` boolean — If `true`, the object has been deleted from the database. Must be `false` for new objects being inserted. When deleted, the `updated_at` field will equal the deletion time. - `item_data` CatalogItem — A [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) instance of the `ITEM` type, also referred to as an item, in the catalog. - `abbreviation` string — The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. This attribute is searchable, and its value length is of Unicode code points. - `available_electronically` boolean — If `true`, the item can be added to electronically fulfilled orders from the merchant's online store. - `available_for_pickup` boolean — If `true`, the item can be added to pickup orders from the merchant's online store. - `available_online` boolean — If `true`, the item can be added to shipping orders from the merchant's online store. - `category_id` string — The ID of the item's category, if any. - `description` string — The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `item_options` CatalogItemOptionForItem[] — List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options. - `item_option_id` string — The unique id of the item option, used to form the dimensions of the item option matrix in a specified order. - `label_color` string — The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code. - `modifier_list_info` CatalogItemModifierListInfo[] — A set of `CatalogItemModifierListInfo` objects representing the modifier lists that apply to this item, along with the overrides and min and max limits that are specific to this item. Modifier lists may also be added to or deleted from an item using `UpdateItemModifierLists`. - `enabled` boolean — If `true`, enable this `CatalogModifierList`. The default value is `true`. - `max_selected_modifiers` integer — If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`. - `min_selected_modifiers` integer — If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`. - `modifier_list_id` string, required — The ID of the `CatalogModifierList` controlled by this `CatalogModifierListInfo`. - `modifier_overrides` CatalogModifierOverride[] — A set of `CatalogModifierOverride` objects that override whether a given `CatalogModifier` is enabled by default. - `modifier_id` string, required — The ID of the `CatalogModifier` whose default behavior is being overridden. - `on_by_default` boolean — If `true`, this `CatalogModifier` should be selected by default for this `CatalogItem`. - `name` string — The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points. - `product_type` string — The product type of the item. May not be changed once an item has been created. Only items of product type `REGULAR` or `APPOINTMENTS_SERVICE` may be created by this API; items with other product types are read-only. - `skip_modifier_screen` boolean — If `false`, the Square Point of Sale app will present the `CatalogItem`'s details screen immediately, allowing the merchant to choose `CatalogModifier`s before adding the item to the cart. This is the default behavior. If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item's details. Third-party clients are encouraged to implement similar behaviors. - `sort_name` string — A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting. It is currently supported for sellers of the Japanese locale only. - `tax_ids` string[] — A set of IDs indicating the taxes enabled for this item. When updating an item, any taxes listed here will be added to the item. Taxes may also be added to or deleted from an item using `UpdateItemTaxes`. - `variations` CatalogObject[] — A list of [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) objects for this item. An item must have at least one variation. - `item_option_data` CatalogItemOption — A group of variations for a `CatalogItem`. - `description` string — The item option's human-readable description. Displayed in the Square Point of Sale app for the seller and in the Online Store or on receipts for the buyer. This is a searchable attribute for use in applicable query filters. - `display_name` string — The item option's display name for the customer. This is a searchable attribute for use in applicable query filters. - `name` string — The item option's display name for the seller. Must be unique across all item options. This is a searchable attribute for use in applicable query filters. - `show_colors` boolean — If true, display colors for entries in `values` when present. - `values` CatalogObject[] — A list of CatalogObjects containing the `CatalogItemOptionValue`s for this item. - `item_option_value_data` CatalogItemOptionValue — An enumerated value that can link a `CatalogItemVariation` to an item option as one of its item option values. - `color` string — The HTML-supported hex color for the item option (e.g., "#ff8d4e85"). Only displayed if `show_colors` is enabled on the parent `ItemOption`. When left unset, `color` defaults to white ("#ffffff") when `show_colors` is enabled on the parent `ItemOption`. - `description` string — A human-readable description for the option value. This is a searchable attribute for use in applicable query filters. - `item_option_id` string — Unique ID of the associated item option. - `name` string — Name of this item option value. This is a searchable attribute for use in applicable query filters. - `ordinal` integer — Determines where this option value appears in a list of option values. - `item_variation_data` CatalogItemVariation — An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations. - `available_for_booking` boolean — If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking. - `inventory_alert_threshold` integer — If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer. - `inventory_alert_type` string — Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. - `item_id` string — The ID of the `CatalogItem` associated with this item variation. - `item_option_values` CatalogItemOptionValueForItemVariation[] — List of item option values associated with this item variation. Listed in the same order as the item options of the parent item. - `item_option_id` string — The unique id of an item option. - `item_option_value_id` string — The unique id of the selected value for the item option. - `location_overrides` ItemVariationLocationOverrides[] — Per-location price and inventory overrides. - `inventory_alert_threshold` integer — If the inventory quantity for the variation is less than or equal to this value and `inventory_alert_type` is `LOW_QUANTITY`, the variation displays an alert in the merchant dashboard. This value is always an integer. - `inventory_alert_type` string — Indicates whether the `CatalogItemVariation` displays an alert when its inventory quantity is less than or equal to its `inventory_alert_threshold`. - `location_id` string — The ID of the `Location`. This can include locations that are deactivated. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `pricing_type` string — The pricing type (fixed or variable) for the `CatalogItemVariation` at the given `Location`. - `track_inventory` boolean — If `true`, inventory tracking is active for the `CatalogItemVariation` at this `Location`. - `measurement_unit_id` string — ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity sold of this item variation. If left unset, the item will be sold in whole quantities. - `name` string — The item variation's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal for each item variation within a parent `CatalogItem` is set according to the item variations's position. On reads, the value is not guaranteed to be sequential or unique. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `pricing_type` string — Indicates whether the item variation's price is fixed or determined at the time of sale. - `service_duration` integer — If the `CatalogItem` that owns this item variation is of type `APPOINTMENTS_SERVICE`, then this is the duration of the service in milliseconds. For example, a 30 minute appointment would have the value `1800000`, which is equal to 30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second). - `sku` string — The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters. - `stockable` boolean — Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). For backward compatibility missing values will be interpreted as TRUE. - `stockable_conversion` CatalogStockConversion — Represents the rule of conversion between a stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) and a non-stockable sell-by or receive-by `CatalogItemVariation` that share the same underlying stock. - `nonstockable_quantity` string, required — The converted equivalent quantity of the non-stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) in its measurement unit. The `stockable_quantity` value and this `nonstockable_quantity` value together define the conversion ratio between stockable item variation and the non-stockable item variation. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point. - `stockable_item_variation_id` string, required — References to the stockable [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) for this stock conversion. Selling, receiving or recounting the non-stockable `CatalogItemVariation` defined with a stock conversion results in adjustments of this stockable `CatalogItemVariation`. This immutable field must reference a stockable `CatalogItemVariation` that shares the parent [CatalogItem](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItem) of the converted `CatalogItemVariation.` - `stockable_quantity` string, required — The quantity of the stockable item variation (as identified by `stockable_item_variation_id`) equivalent to the non-stockable item variation quantity (as specified in `nonstockable_quantity`) as defined by this stock conversion. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point. - `team_member_ids` string[] — Tokens of employees that can perform the service represented by this variation. Only valid for variations of type `APPOINTMENTS_SERVICE`. - `track_inventory` boolean — If `true`, inventory tracking is active for the variation. - `upc` string — The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters. The value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard, Square Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned to this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps unless it is updated to fit the expected format. - `user_data` string — Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points. - `measurement_unit_data` CatalogMeasurementUnit — Represents the unit used to measure a `CatalogItemVariation` and specifies the precision for decimal quantities. - `measurement_unit` MeasurementUnit — Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: `custom_unit`, `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. - `area_unit` string — Represents a standard area unit. - `custom_unit` MeasurementUnitCustom — The information needed to define a custom unit, provided by the seller. - `abbreviation` string, required — The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports. - `name` string, required — The name of the custom unit, for example "bushel". - `generic_unit` string — Reserved for API integrations that lack the ability to specify a real measurement unit - `length_unit` string — Represents a standard length unit. - `time_unit` string — Represents a standard unit of time. - `type` string — Represents the type of the measurement unit. - `volume_unit` string — Represents a standard volume unit. - `weight_unit` string — Represents a standard unit of weight or mass. - `precision` integer — An integer between 0 and 5 that represents the maximum number of positions allowed after the decimal in quantities measured with this unit. For example: - if the precision is 0, the quantity can be 1, 2, 3, etc. - if the precision is 1, the quantity can be 0.1, 0.2, etc. - if the precision is 2, the quantity can be 0.01, 0.12, etc. Default: 3 - `modifier_data` CatalogModifier — A modifier applicable to items at the time of sale. - `modifier_list_id` string — The ID of the `CatalogModifierList` associated with this modifier. - `name` string — The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — Determines where this `CatalogModifier` appears in the `CatalogModifierList`. - `price_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `modifier_list_data` CatalogModifierList — A list of modifiers applicable to items at the time of sale. For example, a "Condiments" modifier list applicable to a "Hot Dog" item may contain "Ketchup", "Mustard", and "Relish" modifiers. Use the `selection_type` field to specify whether or not multiple selections from the modifier list are allowed. - `modifiers` CatalogObject[] — The options included in the `CatalogModifierList`. You must include at least one `CatalogModifier`. Each CatalogObject must have type `MODIFIER` and contain `CatalogModifier` data. - `name` string — The name for the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `ordinal` integer — Determines where this modifier list appears in a list of `CatalogModifierList` values. - `selection_type` string — Indicates whether multiple options from the modifier list can be applied to a single `CatalogItem`. - `present_at_all_locations` boolean — If `true`, this object is present at all locations (including future locations), except where specified in the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations), except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. - `present_at_location_ids` string[] — A list of locations where the object is present, even if `present_at_all_locations` is `false`. This can include locations that are deactivated. - `pricing_rule_data` CatalogPricingRule — Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period. - `apply_products_id` string — __Deprecated__: Please use the `exclude_products_id` field to apply an exclude set instead. Exclude sets allow better control over quantity ranges and offer more flexibility for which matched items receive a discount. `CatalogProductSet` to apply the pricing to. An apply rule matches within the subset of the cart that fits the match rules (the match set). An apply rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules. - `customer_group_ids_any` string[] — A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule. Notice that a group ID is generated by the Customers API. If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer has a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount applies only to matched products sold to customers belonging to the specified customer groups. - `discount_id` string — Unique ID for the `CatalogDiscount` to take off the price of all matched items. - `exclude_products_id` string — `CatalogProductSet` to exclude from the pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules. - `exclude_strategy` string — If an `exclude_products_id` was given, controls which subset of matched products is excluded from any discounts. Default value: `LEAST_EXPENSIVE` - `match_products_id` string — Unique ID for the `CatalogProductSet` that will be matched by this rule. A match rule matches within the entire cart, and can match multiple times. This field will always be set. - `name` string — User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off". - `time_period_ids` string[] — A list of unique IDs for the catalog time periods when this pricing rule is in effect. If left unset, the pricing rule is always in effect. - `valid_from_date` string — Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD). - `valid_from_local_time` string — Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. - `valid_until_date` string — Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD). - `valid_until_local_time` string — Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated. - `product_set_data` CatalogProductSet — Represents a collection of catalog objects for the purpose of applying a `PricingRule`. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations. - `all_products` boolean — If set to `true`, the product set will include every item in the catalog. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. - `name` string — User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items". - `product_ids_all` string[] — Unique IDs for any `CatalogObject` included in this product set. All objects in this set must be included in an order for a pricing rule to apply. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs. - `product_ids_any` string[] — Unique IDs for any `CatalogObject` included in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply. This can be used with `product_ids_all` in a parent `CatalogProductSet` to match groups of products for a bulk discount, such as a discount for an entree and side combo. Only one of `product_ids_all`, `product_ids_any`, or `all_products` can be set. Max: 500 catalog object IDs. - `quantity_exact` integer — If set, there must be exactly this many items from `products_any` or `products_all` in the cart for the discount to apply. Cannot be combined with either `quantity_min` or `quantity_max`. - `quantity_max` integer — If set, the pricing rule will apply to a maximum of this many items from `products_any` or `products_all`. - `quantity_min` integer — If set, there must be at least this many items from `products_any` or `products_all` in a cart for the discount to apply. See `quantity_exact`. Defaults to 0 if `quantity_exact`, `quantity_min` and `quantity_max` are all unspecified. - `quick_amounts_settings_data` CatalogQuickAmountsSettings — A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts. - `amounts` CatalogQuickAmount[] — Represents a set of Quick Amounts at this location. - `amount` Money, required — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `ordinal` integer — The order in which this Quick Amount should be displayed. - `score` integer — Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100]. MANUAL type amount will always have score = 100. - `type` string, required — Represents the type of the Quick Amount. - `eligible_for_auto_amounts` boolean — Represents location's eligibility for auto amounts The boolean should be consistent with whether there are AUTO amounts in the `amounts`. - `option` string, required — Represents the option seller currently uses on Quick Amounts. - `subscription_plan_data` CatalogSubscriptionPlan — Describes a subscription plan. For more information, see [Set Up and Manage a Subscription Plan](https://developer.squareup.com/docs/subscriptions-api/setup-plan). - `name` string, required — The name of the plan. - `phases` SubscriptionPhase[], required — A list of SubscriptionPhase containing the [SubscriptionPhase](https://developer.squareup.com/reference/square_2021-08-18/objects/SubscriptionPhase) for this plan. - `cadence` string, required — The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a `SubscriptionPhase` is created. - `ordinal` integer — The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. - `periods` integer — The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created. - `recurring_price_money` Money, required — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `uid` string — The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created. - `tax_data` CatalogTax — A tax applicable to an item. - `applies_to_custom_amounts` boolean — If `true`, the fee applies to custom amounts entered into the Square Point of Sale app that are not associated with a particular `CatalogItem`. - `calculation_phase` string — Whether the tax is calculated based on a payment's subtotal or total. - `enabled` boolean — A Boolean flag to indicate whether the tax is displayed as enabled (`true`) in the Square Point of Sale app or not (`false`). - `inclusion_type` string — Whether the tax is `ADDITIVE` or `INCLUSIVE`. - `name` string — The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points. - `percentage` string — The percentage of the tax in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. A value of `7.5` corresponds to 7.5%. - `time_period_data` CatalogTimePeriod — Represents a time period - either a single period or a repeating period. - `event` string — An iCalendar (RFC 5545) [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which specifies the name, timing, duration and recurrence of this time period. Example: ``` DTSTART:20190707T180000 DURATION:P2H RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR ``` Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are supported. `DTSTART` must be in local (unzoned) time format. Note that while `BEGIN:VEVENT` and `END:VEVENT` is not required in the request. The response will always include them. - `type` string, required — The type of this object. Each object type has expected properties expressed in a structured format within its corresponding `*_data` field below. - `updated_at` string — 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"` would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. - `version` integer — The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting. --- [API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/versions/8d95e3639487/schema)