The wrapper object for the catalog entries of a given object type.
<- Object
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.
The type of this object. Each object type has expected properties expressed in a structured format within its corresponding *_data field below.
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.
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
The version of the object. When updating an object, the version supplied should match the version in the database. If it does not, the server attempts a three-way merge. If the client's changes and the concurrent changes don't overlap, the merge succeeds silently. A VERSION_MISMATCH error is only returned when both sides changed the same field to different values.
Use the same API version (Square-Version header) for both reading and writing catalog objects. The server uses the API version on a write request to determine which missing fields the client intentionally cleared versus which fields the client simply could not see at that version. If a client reads an object at an older API version and writes it back at a newer version, fields that were introduced between those two versions will be absent from the request, and the server will interpret that absence as an intentional clear.
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.
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.).
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.
Controls whether this object is present at all locations, including future locations.
Most object types have independent location control, including TAX, DISCOUNT, and MODIFIER_LIST.
ITEM and ITEM_VARIATION have separate settings, but a variation can only be enabled at locations where its parent item is enabled. Disabling a variation everywhere is valid even when the parent item is enabled at specific locations.
MODIFIER objects nested within a MODIFIER_LIST inherit location settings from their parent. Some object types, including CATEGORY, IMAGE, and CUSTOM_ATTRIBUTE_DEFINITION, must always be globally enabled and cannot use location-specific fields.
The field operates in two modes. When true (the default), the object is available at all current and future locations except those in absent_at_location_ids. When false, the object is available only at locations in present_at_location_ids. The unused list in each mode is ignored.
Locations where the object is present, used when present_at_all_locations is false.
When present_at_all_locations is true, this field is ignored since the object is already present everywhere. Can include deactivated locations. Empty strings are rejected.
Locations where the object is not present, used when present_at_all_locations is true.
When present_at_all_locations is false, this field is ignored since the object is already absent everywhere except those in present_at_location_ids. Can include deactivated locations. Empty strings are rejected.
Structured data for a CatalogCategory, set for CatalogObjects of type CATEGORY.
Structured data for a CatalogItemVariation, set for CatalogObjects of type ITEM_VARIATION.
Structured data for a CatalogDiscount, set for CatalogObjects of type DISCOUNT.
Structured data for a CatalogModifierList, set for CatalogObjects of type MODIFIER_LIST.
Structured data for a CatalogModifier, set for CatalogObjects of type MODIFIER.
Structured data for a CatalogTimePeriod, set for CatalogObjects of type TIME_PERIOD.
Structured data for a CatalogProductSet, set for CatalogObjects of type PRODUCT_SET.
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.
Structured data for a CatalogMeasurementUnit, set for CatalogObjects of type MEASUREMENT_UNIT.
Structured data for a CatalogSubscriptionPlan, set for CatalogObjects of type SUBSCRIPTION_PLAN.
Structured data for a CatalogItemOption, set for CatalogObjects of type ITEM_OPTION.
Structured data for a CatalogItemOptionValue, set for CatalogObjects of type ITEM_OPTION_VAL.
Structured data for a CatalogCustomAttributeDefinition, set for CatalogObjects of type CUSTOM_ATTRIBUTE_DEFINITION.
Structured data for a CatalogQuickAmountsSettings, set for CatalogObjects of type QUICK_AMOUNTS_SETTINGS.
Structured data for a CatalogSubscriptionPlanVariation, set for CatalogObjects of type SUBSCRIPTION_PLAN_VARIATION.