catalog-object.md

Catalog Object

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

Depending on the type attribute value, a CatalogObject instance assumes a type-specific data to yield the corresponding type of catalog object.

For example, if type=ITEM, the CatalogObject instance must have the ITEM-specific data set on the item_data attribute. The resulting CatalogObject instance is also a CatalogItem instance.

In general, if type=<OBJECT_TYPE>, the CatalogObject instance must have the <OBJECT_TYPE>-specific data set on the <object_type>_data attribute. The resulting CatalogObject instance is also a Catalog<ObjectType> instance.

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

Structure

Catalog Object

Fields

Name	Type	Tags	Description
type	str (Catalog Object Type)	Required	Possible types of CatalogObjects returned from the catalog, each containing type-specific properties in the *_data field corresponding to the specified object type.
id	str	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. Constraints: Minimum Length: 1
updated_at	str	Optional	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.
version	long|int	Optional	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	bool	Optional	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	Dict Str Catalog Custom Attribute Value	Optional	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.).
catalog_v1_ids	List Catalog V1 Id	Optional	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	bool	Optional	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	List[str]	Optional	A list of locations where the object is present, even if present_at_all_locations is false. This can include locations that are deactivated.
absent_at_location_ids	List[str]	Optional	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.
item_data	Catalog Item	Optional	A CatalogObject instance of the ITEM type, also referred to as an item, in the catalog.
category_data	Catalog Category	Optional	A category to which a CatalogItem instance belongs.
item_variation_data	Catalog Item Variation	Optional	An item variation, representing a product for sale, in the Catalog object model. Each item must have at least one item variation and can have at most 250 item variations. An item variation can be sellable, stockable, or both if it has a unit of measure for its count for the sold number of the variation, the stocked number of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both stockable and sellable. But when a variation of the wine is sold by the glass, the sold units cannot be used as a measure of the stocked units. This by-the-glass variation is sellable, but not stockable. To accurately keep track of the wine's inventory count at any time, the sellable count must be converted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes the stockable_conversion property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count decreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion.
tax_data	Catalog Tax	Optional	A tax applicable to an item.
discount_data	Catalog Discount	Optional	A discount applicable to items.
modifier_list_data	Catalog Modifier List	Optional	For a text-based modifier, this encapsulates the modifier's text when its modifier_type is TEXT. For example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied text string to be selected for the T-shirt at the time of sale. For non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items at the time of sale. Each element of the modifier list is a CatalogObject instance of the MODIFIER type. For example, a "Condiments" modifier list applicable to a "Hot Dog" item may contain "Ketchup", "Mustard", and "Relish" modifiers. A non text-based modifier can be applied to the modified item once or multiple times, if the selection_type field is set to SINGLE or MULTIPLE, respectively. On the other hand, a text-based modifier can be applied to the item only once and the selection_type field is always set to SINGLE.
modifier_data	Catalog Modifier	Optional	A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item.
time_period_data	Catalog Time Period	Optional	Represents a time period - either a single period or a repeating period.
product_set_data	Catalog Product Set	Optional	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.
pricing_rule_data	Catalog Pricing Rule	Optional	Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
image_data	Catalog Image	Optional	An image file to use in Square catalogs. It can be associated with CatalogItem, CatalogItemVariation, CatalogCategory, and CatalogModifierList objects. Only the images on items and item variations are exposed in Dashboard. Only the first image on an item is displayed in Square Point of Sale (SPOS). Images on items and variations are displayed through Square Online Store. Images on other object types are for use by 3rd party application developers.
measurement_unit_data	Catalog Measurement Unit	Optional	Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.
subscription_plan_data	Catalog Subscription Plan	Optional	Describes a subscription plan. A subscription plan represents what you want to sell in a subscription model, and includes references to each of the associated subscription plan variations. For more information, see Subscription Plans and Variations.
item_option_data	Catalog Item Option	Optional	A group of variations for a CatalogItem.
item_option_value_data	Catalog Item Option Value	Optional	An enumerated value that can link a CatalogItemVariation to an item option as one of its item option values.
custom_attribute_definition_data	Catalog Custom Attribute Definition	Optional	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
quick_amounts_settings_data	Catalog Quick Amounts Settings	Optional	A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
subscription_plan_variation_data	Catalog Subscription Plan Variation	Optional	Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold. For more information, see Subscription Plans and Variations.
availability_period_data	Catalog Availability Period	Optional	Represents a time period of availability.

Example (as JSON)

{
  "type": "TIME_PERIOD",
  "id": "id4",
  "category_data": {
    "object": {
      "category_data": {
        "name": "Beverages"
      },
      "id": "#Beverages",
      "present_at_all_locations": true,
      "type": "CATEGORY"
    }
  },
  "tax_data": {
    "object": {
      "id": "#SalesTax",
      "present_at_all_locations": true,
      "tax_data": {
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "enabled": true,
        "fee_applies_to_custom_amounts": true,
        "inclusion_type": "ADDITIVE",
        "name": "Sales Tax",
        "percentage": "5.0"
      },
      "type": "TAX"
    }
  },
  "discount_data": {
    "object": {
      "discount_data": {
        "discount_type": "FIXED_PERCENTAGE",
        "label_color": "red",
        "name": "Welcome to the Dark(Roast) Side!",
        "percentage": "5.4",
        "pin_required": false
      },
      "id": "#Maythe4th",
      "present_at_all_locations": true,
      "type": "DISCOUNT"
    }
  },
  "modifier_data": {
    "object": {
      "modifier_data": {
        "name": "Almond Milk",
        "price_money": {
          "amount": 250,
          "currency": "USD"
        }
      },
      "present_at_all_locations": true,
      "type": "MODIFIER"
    }
  },
  "updated_at": "updated_at0",
  "version": 186,
  "is_deleted": false,
  "custom_attribute_values": {
    "key0": {
      "name": "name8",
      "string_value": "string_value2",
      "custom_attribute_definition_id": "custom_attribute_definition_id4",
      "type": "STRING",
      "number_value": "number_value8"
    },
    "key1": {
      "name": "name8",
      "string_value": "string_value2",
      "custom_attribute_definition_id": "custom_attribute_definition_id4",
      "type": "STRING",
      "number_value": "number_value8"
    },
    "key2": {
      "name": "name8",
      "string_value": "string_value2",
      "custom_attribute_definition_id": "custom_attribute_definition_id4",
      "type": "STRING",
      "number_value": "number_value8"
    }
  },
  "catalog_v1_ids": [
    {
      "catalog_v1_id": "catalog_v1_id4",
      "location_id": "location_id4"
    },
    {
      "catalog_v1_id": "catalog_v1_id4",
      "location_id": "location_id4"
    },
    {
      "catalog_v1_id": "catalog_v1_id4",
      "location_id": "location_id4"
    }
  ]
}