Skip to content

Latest commit

 

History

History
95 lines (83 loc) · 11 KB

catalog-object.md

File metadata and controls

95 lines (83 loc) · 11 KB

Catalog Object

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.

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 object type.
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.
Constraints: Minimum Length: 1
updated_at string 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 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 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 List of 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 of string 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 of string 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.
image_id string Optional Identifies the CatalogImage attached to this CatalogObject.
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 (i.e., product) in the Catalog object model. Each item
may have a maximum of 250 item variations.
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 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.
modifier_data Catalog Modifier Optional A modifier applicable to items at the time of sale.
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 catalog
items, item variations, and categories.
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. For more information, see
Set Up and Manage a Subscription Plan.
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.

Example (as JSON)

{
  "type": "ITEM_VARIATION",
  "id": "id0",
  "updated_at": "updated_at4",
  "version": 172,
  "is_deleted": false,
  "custom_attribute_values": {
    "key0": {
      "name": "name9",
      "string_value": "string_value3",
      "custom_attribute_definition_id": "custom_attribute_definition_id3",
      "type": "BOOLEAN",
      "number_value": "number_value9"
    }
  },
  "catalog_v1_ids": [
    {
      "catalog_v1_id": "catalog_v1_id4",
      "location_id": "location_id4"
    },
    {
      "catalog_v1_id": "catalog_v1_id5",
      "location_id": "location_id5"
    }
  ]
}