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

SUBSCRIPTION_PLAN The CatalogObject instance is of the CatalogSubscriptionPlan type and represents a subscription plan. The subscription plan specific data must be stored on the subscription_plan_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

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

name

The name of the plan.

string

phases[0] SubscriptionPhase [ ]

cadence

The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a SubscriptionPhase is created.

string

Select cadence

THIRTY_DAYS Once every 30 days

ordinal

The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a SubscriptionPhase is created.

integer

periods

The number of cadences the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a SubscriptionPhase is created.

integer

recurring_price_money

The amount to bill for each cadence. Failure to specify this field results in a MISSING_REQUIRED_PARAMETER error at runtime.

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

uid

The Square-assigned ID of the subscription phase. This field cannot be changed after a SubscriptionPhase is created.

string

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