POST /v2/catalog/object

Default value: "application/json"

The wrapper object for the Catalog entries of a given object type.

The type of a particular CatalogObject is determined by the value of the type attribute and only the corresponding data attribute can be set on the CatalogObject instance. For example, the following list shows some instances of CatalogObject of a given type and their corresponding data attribute that can be set:

• For a CatalogObject of the ITEM type, set the item_data attribute to yield the CatalogItem object.
• For a CatalogObject of the ITEM_VARIATION type, set the item_variation_data attribute to yield the CatalogItemVariation object.
• For a CatalogObject of the MODIFIER type, set the modifier_data attribute to yield the CatalogModifier object.
• For a CatalogObject of the MODIFIER_LIST type, set the modifier_list_data attribute to yield the CatalogModifierList object.
• For a CatalogObject of the CATEGORY type, set the category_data attribute to yield the CatalogCategory object.
• For a CatalogObject of the DISCOUNT type, set the discount_data attribute to yield the CatalogDiscount object.
• For a CatalogObject of the TAX type, set the tax_data attribute to yield the CatalogTax object.
• For a CatalogObject of the IMAGE type, set the image_data attribute to yield the CatalogImageData object.
• For a CatalogObject of the QUICK_AMOUNTS_SETTINGS type, set the quick_amounts_settings_data attribute to yield the CatalogQuickAmountsSettings object.
• For a CatalogObject of the PRICING_RULE type, set the pricing_rule_data attribute to yield the CatalogPricingRule object.
• For a CatalogObject of the TIME_PERIOD type, set the time_period_data attribute to yield the CatalogTimePeriod object.
• For a CatalogObject of the PRODUCT_SET type, set the product_set_data attribute to yield the CatalogProductSet object.
• For a CatalogObject of the SUBSCRIPTION_PLAN type, set the subscription_plan_data attribute to yield the CatalogSubscriptionPlan object.

For a more detailed discussion of the Catalog data model, please see the Design a Catalog guide.

A tax applicable to an item.

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%.

If true, the fee applies to custom amounts entered into the Square Point of Sale app that are not associated with a particular CatalogItem.

The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

Whether the tax is ADDITIVE or INCLUSIVE.

A Boolean flag to indicate whether the tax is displayed as enabled (true) in the Square Point of Sale app or not (false).

Whether the tax is calculated based on a payment's subtotal or total.

An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations.

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).

Tokens of employees that can perform the service represented by this variation. Only valid for variations of type APPOINTMENTS_SERVICE.

Per-location price and inventory overrides.

The ID of the Location. This can include locations that are deactivated.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

Indicates whether the CatalogItemVariation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold.

The pricing type (fixed or variable) for the CatalogItemVariation at the given Location.

If true, inventory tracking is active for the CatalogItemVariation at this Location.

Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.

If the CatalogItem that owns this item variation is of type APPOINTMENTS_SERVICE, a bool representing whether this service is available for booking.

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.

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.

Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its inventory_alert_threshold.

Indicates whether the item variation's price is fixed or determined at the time of sale.

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.

If true, inventory tracking is active for the variation.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters.

List of item option values associated with this item variation. Listed in the same order as the item options of the parent item.

The unique id of an item option.

The unique id of the selected value for the item option.

Represents the rule of conversion between a stockable CatalogItemVariation and a non-stockable sell-by or receive-by CatalogItemVariation that share the same underlying stock.

References to the stockable 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 of the converted CatalogItemVariation.

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.

The converted equivalent quantity of the non-stockable 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.

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.

The ID of the CatalogItem associated with this item variation.

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.

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.

Represents a time period - either a single period or a repeating period.

An iCalendar (RFC 5545) event, 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.

Last modification timestamp 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.

A discount applicable to items.

The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.

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.

The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

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.

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.

Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

A CatalogObject instance of the ITEM type, also referred to as an item, in the catalog.

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.

A list of CatalogItemVariation objects for this item. An item must have at least one variation.

The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

If true, the item can be added to electronically fulfilled orders from the merchant's online store.

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.

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.

If false, the Square Point of Sale app will present the CatalogItem's details screen immediately, allowing the merchant to choose CatalogModifiers 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.

If true, the item can be added to shipping orders from the merchant's online store.

If true, the item can be added to pickup orders from the merchant's online store.

The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.

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.

If 0 or larger, the smallest number of CatalogModifiers that must be selected from this CatalogModifierList.

A set of CatalogModifierOverride objects that override whether a given CatalogModifier is enabled by default.

If true, this CatalogModifier should be selected by default for this CatalogItem.

The ID of the CatalogModifier whose default behavior is being overridden.

The ID of the CatalogModifierList controlled by this CatalogModifierListInfo.

If true, enable this CatalogModifierList. The default value is true.

If 0 or larger, the largest number of CatalogModifiers that can be selected from this CatalogModifierList.

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.

List of item options IDs for this item. Used to manage and group item variations in a specified order.

Maximum: 6 item options.

The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.

The ID of the item's category, if any.

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.

Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.

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.

Represents a standard length unit.

Represents a standard volume unit.

Represents a standard unit of time.

Reserved for API integrations that lack the ability to specify a real measurement unit

Represents the type of the measurement unit.

Represents a standard area unit.

The information needed to define a custom unit, provided by the seller.

The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports.

The name of the custom unit, for example "bushel".

Represents a standard unit of weight or mass.

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

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.

An enumerated value that can link a CatalogItemVariation to an item option as one of its item option values.

Unique ID of the associated item option.

Name of this item option value. This is a searchable attribute for use in applicable query filters.

A human-readable description for the option value. This is a searchable attribute for use in applicable query filters.

Determines where this option value appears in a list of option values.

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.

The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.

Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.

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.

Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).

User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off".

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.

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.

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.

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.

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.

Unique ID for the CatalogDiscount to take off the price of all matched items.

If an exclude_products_id was given, controls which subset of matched products is excluded from any discounts.

Default value: LEAST_EXPENSIVE

Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).

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.

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.

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.

User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items".

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.

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.

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.

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.

If set, the pricing rule will apply to a maximum of this many items from products_any or products_all.

A category to which a CatalogItem instance belongs.

The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

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

Configuration associated with SELECTION-type custom attribute definitions.

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.

The set of valid CatalogCustomAttributeSelections. Up to a maximum of 100 selections can be defined. Can be modified.

Selection name, unique within allowed_selections.

Unique ID set by Square.

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.

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.

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.

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_-].

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.

Provides information about the application used to generate a change.

Read-only display name assigned to the application (e.g. "Custom Application", "Square POS 4.74 for Android").

Read-only Square ID assigned to the application. Only used for Product type EXTERNAL_API.

Read-only Product type for the application.

Configuration associated with Custom Attribute Definitions of type STRING.

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.

The visibility of a custom attribute in seller-facing UIs (including Square Point of Sale applications and Square Dashboard). May be modified.

The type of this custom attribute. Cannot be modified after creation. Required.

The visibility of a custom attribute to applications other than the application that created the attribute.

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

A modifier applicable to items at the time of sale.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

The ID of the CatalogModifierList associated with this modifier.

Determines where this CatalogModifier appears in the CatalogModifierList.

A group of variations for a CatalogItem.

A list of CatalogObjects containing the CatalogItemOptionValues for this item.

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.

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.

The item option's display name for the customer. This is a searchable attribute for use in applicable query filters.

If true, display colors for entries in values when present.

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.

A list of locations where the object is present, even if present_at_all_locations is false. This can include locations that are deactivated.

A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.

Represents the option seller currently uses on Quick Amounts.

Represents location's eligibility for auto amounts The boolean should be consistent with whether there are AUTO amounts in the amounts.

Represents a set of Quick Amounts at this location.

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.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

The order in which this Quick Amount should be displayed.

Represents the type of the Quick Amount.

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.

The ID of the Location this Connect V1 ID is associated with.

The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID.

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.

The options included in the CatalogModifierList. You must include at least one CatalogModifier. Each CatalogObject must have type MODIFIER and contain CatalogModifier data.

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.

Determines where this modifier list appears in a list of CatalogModifierList values.

Indicates whether multiple options from the modifier list can be applied to a single CatalogItem.

Identifies the CatalogImage attached to this CatalogObject.

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.

A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair is a CatalogCustomAttributeValue object. The key is the key attribute value defined in the associated 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.).

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.

One or more choices from allowed_selections. Populated if type = SELECTION.

Read-only. The id of the CatalogCustomAttributeDefinition this value belongs to.

A true or false value. Populated if type = BOOLEAN.

The name of the custom attribute.

Read-only. A copy of key from the associated CatalogCustomAttributeDefinition.

Populated if type = NUMBER. Contains a string representation of a decimal number, using a . as the decimal separator.

The string value of the custom attribute. Populated if type = STRING.

Read-only. A copy of type from the associated CatalogCustomAttributeDefinition.

An image file to use in Square catalogs. It can be associated with catalog items, item variations, and categories.

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. It is not unique and should not be shown in a buyer facing context.

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.

The URL of this image, generated by Square after an image is uploaded using the CreateCatalogImage endpoint.

Describes a subscription plan. For more information, see Set Up and Manage a Subscription Plan.

The name of the plan.

A list of SubscriptionPhase containing the SubscriptionPhase for this plan.

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 for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

The Square-assigned ID of the subscription phase. This field cannot be changed after a SubscriptionPhase is created.

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.

The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a SubscriptionPhase is created.

The number of cadences 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.

A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID).

If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects.

See Idempotency for more information.