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

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

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[0] ItemVariationLocationOverrides [ ]

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

location_id

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

string

price_money

The price of the CatalogItemVariation at the given Location, or blank for variable pricing.

Money

pricing_type

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

string

Select pricing_type

FIXED_PRICING The catalog item variation's price is fixed.
VARIABLE_PRICING The catalog item variation's price is entered at the time of sale.

track_inventory

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

boolean

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

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