• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

Object Index
You are viewing an old version of the API
CatalogObject

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

Properties
Name Description
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.
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.

Min Length 1
updated_at
string

Read only 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.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00
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.
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.
custom_attribute_values
Map<string, CatalogCustomAttributeValue>
Beta

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.).
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.
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.
absent_at_location_ids
string [ ]

A list of locations where the object is not present, even if present_at_all_locations is true.
image_id
string

Identifies the CatalogImage attached to this CatalogObject.
item_data
CatalogItem

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

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

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

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

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

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

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

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

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

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.
image_data
CatalogImage

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

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

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

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

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

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

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

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?