API Explorer

You are viewing an old version of the API

All Versions

Upsert catalog object

POST /v2/catalog/object

Creates a new or updates the specified CatalogObject.

Open in API Reference

Access Tokens Sign in to populate your access tokens from the developer dashboard Sign In

Body

idempotency_key

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.

Min Length 1

string

object

A CatalogObject to be created or updated.

For updates, the object must be active (the is_deleted field is not true).
For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID.

CatalogObject

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.

Min Length 1

string

type

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

string

Select type

ITEM_OPTION_VAL
The CatalogObject instance is of the CatalogItemOptionValue type and represents a value associated with one or more item options. For example, an item option of Size may have item option values such as Small or Medium. The item-option-value-specific data must be on the item_option_value_data field.
ITEM_OPTION
The CatalogObject instance is of the CatalogItemOption type and represents a list of options such as a color or size of a T-shirt that can be assigned to item variations. The item-option-specific data must be on the item_option_data field.
ITEM_VARIATION
The CatalogObject instance is of the CatalogItemVariation type and represents an item variation, also referred to as variation. The item variation-specific data must be set on the item_variation_data field.
ITEM The CatalogObject instance is of the CatalogItem type and represents an item. The item-specific data must be set on the item_data field.

absent_at_location_ids

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.

string[]

catalog_v1_ids

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.

CatalogV1Id [ ]

category_data

Structured data for a CatalogCategory, set for CatalogObjects of type CATEGORY.

CatalogCategory

custom_attribute_definition_data

Structured data for a CatalogCustomAttributeDefinition, set for CatalogObjects of type CUSTOM_ATTRIBUTE_DEFINITION.

CatalogCustomAttributeDefinition

custom_attribute_values

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

Map<string, CatalogCustomAttributeValue>

discount_data

Structured data for a CatalogDiscount, set for CatalogObjects of type DISCOUNT.

CatalogDiscount

image_data

Structured data for a CatalogImage, set for CatalogObjects of type IMAGE.

CatalogImage

is_deleted

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.

boolean

item_data

Structured data for a CatalogItem, set for CatalogObjects of type ITEM.

CatalogItem

abbreviation

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.

Max Length 24

string

available_electronically

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

boolean

available_for_pickup

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

boolean

available_online

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

boolean

category_id

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

string

description_html

The item's description as expressed in valid HTML elements. The length of this field value, including those of HTML tags, is of Unicode points. With application query filters, the text values of the HTML elements and attributes are searchable. Invalid or unsupported HTML elements or attributes are ignored.

Supported HTML elements include:

a: Link. Supports linking to website URLs, email address, and telephone numbers.
b, strong: Bold text
br: Line break
code: Computer code
div: Section
h1-h6: Headings
i, em: Italics
li: List element
ol: Numbered list
p: Paragraph
ul: Bullet list
u: Underline

Supported HTML attributes include:

align: Alignment of the text content
href: Link destination
rel: Relationship between link's target and source
target: Place to open the linked document

Max Length 65535

string

image_ids

The IDs of images associated with this CatalogItem instance. These images will be shown to customers in Square Online Store. The first image will show up as the icon for this item in POS.

string[]

is_archived

Indicates whether this item is archived (true) or not (false).

boolean

item_options

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

Maximum: 6 item options.

Max Length 6

CatalogItemOptionForItem [ ]

label_color

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

string

modifier_list_info

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.

CatalogItemModifierListInfo [ ]

name

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.

Max Length 512

string

product_type

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.

string

Select product_type

REGULAR An ordinary item.

skip_modifier_screen

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.

boolean

sort_name

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. Its value must not be empty.

It is currently supported for sellers of the Japanese locale only.

string

tax_ids

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.

string[]

variations[0] CatalogObject [ ]

When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references.

Min Length 1

string

type

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

string

Select type

ITEM_VARIATION The CatalogObject instance is of the CatalogItemVariation type and represents an item variation, also referred to as variation. The item variation-specific data must be set on the item_variation_data field.

absent_at_location_ids

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.

string[]

catalog_v1_ids

CatalogV1Id [ ]

category_data

Structured data for a CatalogCategory, set for CatalogObjects of type CATEGORY.

CatalogCategory

custom_attribute_definition_data

Structured data for a CatalogCustomAttributeDefinition, set for CatalogObjects of type CUSTOM_ATTRIBUTE_DEFINITION.

CatalogCustomAttributeDefinition

custom_attribute_values

Map<string, CatalogCustomAttributeValue>

discount_data

Structured data for a CatalogDiscount, set for CatalogObjects of type DISCOUNT.

CatalogDiscount

image_data

Structured data for a CatalogImage, set for CatalogObjects of type IMAGE.

CatalogImage

is_deleted

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.

boolean

item_data

Structured data for a CatalogItem, set for CatalogObjects of type ITEM.

CatalogItem

item_option_data

Structured data for a CatalogItemOption, set for CatalogObjects of type ITEM_OPTION.

CatalogItemOption

item_option_value_data

Structured data for a CatalogItemOptionValue, set for CatalogObjects of type ITEM_OPTION_VAL.

CatalogItemOptionValue

item_variation_data

Structured data for a CatalogItemVariation, set for CatalogObjects of type ITEM_VARIATION.

CatalogItemVariation

available_for_booking

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

boolean

image_ids

The IDs of images associated with this CatalogItemVariation instance. These images will be shown to customers in Square Online Store.

string[]

inventory_alert_threshold

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.

integer

inventory_alert_type

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

string

Select inventory_alert_type

NONE The variation does not display an alert.
LOW_QUANTITY The variation generates an alert when its quantity is low.

item_id

The ID of the CatalogItem associated with this item variation.

string

item_option_values

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

CatalogItemOptionValueForItemVariation [ ]

location_overrides

Per-location price and inventory overrides.

ItemVariationLocationOverrides [ ]

measurement_unit_id

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.

string

name

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.

Max Length 255

string

price_money

The item variation's price, if fixed pricing is used.

Money

amount

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.

integer

currency

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

string

Select currency

USD United States dollar

pricing_type

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

string

Select pricing_type

FIXED_PRICING The catalog item variation's price is fixed.

sellable

Whether this variation can be sold. The inventory count of a sellable variation indicates the number of units available for sale. When a variation is both stockable and sellable, its sellable inventory count can be smaller than or equal to its stockable count.

boolean

service_duration

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

integer

sku

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

string

stockable

Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). When a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock and is not an indicator of the number of units of the variation that can be sold.

boolean

stockable_conversion

The unit conversion rule, as prescribed by the CatalogStockConversion type, that describes how this non-stockable (i.e., sellable/receivable) item variation is converted to/from the stockable item variation sharing the same parent item. With the stock conversion, you can accurately track inventory when an item variation is sold in one unit, but stocked in another unit.

CatalogStockConversion

team_member_ids

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

string[]

track_inventory

If true, inventory tracking is active for the variation.

boolean

upc

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.

string

user_data

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

Max Length 255

string

measurement_unit_data

Structured data for a CatalogMeasurementUnit, set for CatalogObjects of type MEASUREMENT_UNIT.

CatalogMeasurementUnit

modifier_data

Structured data for a CatalogModifier, set for CatalogObjects of type MODIFIER.

CatalogModifier

modifier_list_data

Structured data for a CatalogModifierList, set for CatalogObjects of type MODIFIER_LIST.

CatalogModifierList

present_at_all_locations

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.

boolean

present_at_location_ids

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

string[]

pricing_rule_data

Structured data for a CatalogPricingRule, set for CatalogObjects of type PRICING_RULE. A CatalogPricingRule object often works with a CatalogProductSet object or a CatalogTimePeriod object.

CatalogPricingRule

product_set_data

Structured data for a CatalogProductSet, set for CatalogObjects of type PRODUCT_SET.

CatalogProductSet

quick_amounts_settings_data

Structured data for a CatalogQuickAmountsSettings, set for CatalogObjects of type QUICK_AMOUNTS_SETTINGS.

CatalogQuickAmountsSettings

subscription_plan_data

Structured data for a CatalogSubscriptionPlan, set for CatalogObjects of type SUBSCRIPTION_PLAN.

CatalogSubscriptionPlan

subscription_plan_variation_data

Structured data for a CatalogSubscriptionPlanVariation, set for CatalogObjects of type SUBSCRIPTION_PLAN_VARIATION.

CatalogSubscriptionPlanVariation

tax_data

Structured data for a CatalogTax, set for CatalogObjects of type TAX.

CatalogTax

time_period_data

Structured data for a CatalogTimePeriod, set for CatalogObjects of type TIME_PERIOD.

CatalogTimePeriod

version

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.

integer

item_option_data

Structured data for a CatalogItemOption, set for CatalogObjects of type ITEM_OPTION.

CatalogItemOption

item_option_value_data

Structured data for a CatalogItemOptionValue, set for CatalogObjects of type ITEM_OPTION_VAL.

CatalogItemOptionValue

item_variation_data

Structured data for a CatalogItemVariation, set for CatalogObjects of type ITEM_VARIATION.

CatalogItemVariation

measurement_unit_data

Structured data for a CatalogMeasurementUnit, set for CatalogObjects of type MEASUREMENT_UNIT.

CatalogMeasurementUnit

modifier_data

Structured data for a CatalogModifier, set for CatalogObjects of type MODIFIER.

CatalogModifier

modifier_list_data

Structured data for a CatalogModifierList, set for CatalogObjects of type MODIFIER_LIST.

CatalogModifierList

present_at_all_locations

boolean

present_at_location_ids

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

string[]

pricing_rule_data

Structured data for a CatalogPricingRule, set for CatalogObjects of type PRICING_RULE. A CatalogPricingRule object often works with a CatalogProductSet object or a CatalogTimePeriod object.

CatalogPricingRule

product_set_data

Structured data for a CatalogProductSet, set for CatalogObjects of type PRODUCT_SET.

CatalogProductSet

quick_amounts_settings_data

Structured data for a CatalogQuickAmountsSettings, set for CatalogObjects of type QUICK_AMOUNTS_SETTINGS.

CatalogQuickAmountsSettings

subscription_plan_data

Structured data for a CatalogSubscriptionPlan, set for CatalogObjects of type SUBSCRIPTION_PLAN.

CatalogSubscriptionPlan

subscription_plan_variation_data

Structured data for a CatalogSubscriptionPlanVariation, set for CatalogObjects of type SUBSCRIPTION_PLAN_VARIATION.

CatalogSubscriptionPlanVariation

tax_data

Structured data for a CatalogTax, set for CatalogObjects of type TAX.

CatalogTax

time_period_data

Structured data for a CatalogTimePeriod, set for CatalogObjects of type TIME_PERIOD.

CatalogTimePeriod

version

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.

integer

You are viewing an old version of the API

All Versions

Request

cURL

Response

// No response received yet.

Thanks for the feedback. For more help, check out our support resources.

Developer Support Developer Forums

There was an error submitting feedback. Try again later.

Developer Support Developer Forums