API Explorer

You are viewing an old version of the API

All Versions

Batch upsert catalog objects

POST /v2/catalog/batch-upsert

Creates or updates up to 10,000 target objects based on the provided list of objects.

Open in API Reference

Access Tokens Sign in to populate your access tokens from the developer dashboard Sign In

Body

batches

A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request.

For each object, its updated_at field is ignored and replaced with a current timestamp, and its is_deleted field must not be set to true.

To modify an existing object, supply its ID. To create a new object, use an ID starting with #. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID #ABC and a CatalogItemVariation with its item_id attribute set to #ABC in order to associate the CatalogItemVariation with its parent CatalogItem.

Any #-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.

CatalogObjectBatch [ ]

batches[0] CatalogObjectBatch [ ]

objects[0] 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

PRODUCT_SET The CatalogObject instance is of the CatalogProductSet type and represents a product set. The product-set-specific data will be stored in the product_set_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

all_products

If set to true, the product set will include every item in the catalog. Only one of product_ids_all, product_ids_any, or all_products can be set.

boolean

name

User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items".

string

product_ids_all

Unique IDs for any CatalogObject included in this product set. All objects in this set must be included in an order for a pricing rule to apply.

Only one of product_ids_all, product_ids_any, or all_products can be set.

Max: 500 catalog object IDs.

Max Length 500

string[]

product_ids_any

Unique IDs for any CatalogObject included in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply.

This can be used with product_ids_all in a parent CatalogProductSet to match groups of products for a bulk discount, such as a discount for an entree and side combo.

Only one of product_ids_all, product_ids_any, or all_products can be set.

Max: 500 catalog object IDs.

Max Length 500

string[]

quantity_exact

If set, there must be exactly this many items from products_any or products_all in the cart for the discount to apply.

Cannot be combined with either quantity_min or quantity_max.

integer

quantity_max

If set, the pricing rule will apply to a maximum of this many items from products_any or products_all.

integer

quantity_min

If set, there must be at least this many items from products_any or products_all in a cart for the discount to apply. See quantity_exact. Defaults to 0 if quantity_exact, quantity_min and quantity_max are all unspecified.

integer

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

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

objects[1] CatalogObject [ ]

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

DISCOUNT The CatalogObject instance is of the CatalogDiscount type and represents a discount. The discount-specific data must be set on the discount_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

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

Map<string, CatalogCustomAttributeValue>

discount_data

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

CatalogDiscount

amount_money

The amount of the discount. Specify an amount of 0 if discount_type is VARIABLE_AMOUNT.

Do not use this field for percentage-based or variable discounts.

Money

discount_type

Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.

string

Select discount_type

FIXED_PERCENTAGE Apply the discount as a fixed percentage e.g., 5 off the item price.

label_color

The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.

string

maximum_amount_money

For a percentage discount, the maximum absolute value of the discount. For example, if a 50% discount has a maximum_amount_money of $20, a $100 purchase will yield a $20 discount, not a $50 discount.

Money

modify_tax_basis

Indicates whether this discount should reduce the price used to calculate tax.

Most discounts should use MODIFY_TAX_BASIS. However, in some circumstances taxes must be calculated based on an item's price, ignoring a particular discount. For example, in many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a customer pays but does not reduce the sale price used to calculate how much sales tax is due. In this case, the discount representing that manufacturer coupon should have DO_NOT_MODIFY_TAX_BASIS for this field.

If you are unsure whether you need to use this field, consult your tax professional.

string

Select modify_tax_basis

MODIFY_TAX_BASIS Application of the discount will modify the tax basis.
DO_NOT_MODIFY_TAX_BASIS Application of the discount will not modify the tax basis.

name

The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.

Max Length 255

string

percentage

The percentage of the discount as a string representation of a decimal number, using a . as the decimal separator and without a % sign. A value of 7.5 corresponds to 7.5%. Specify a percentage of 0 if discount_type is VARIABLE_PERCENTAGE.

Do not use this field for amount-based or variable discounts.

string

pin_required

Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app.

boolean

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

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

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

objects[2] CatalogObject [ ]

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

PRICING_RULE The CatalogObject instance is of the CatalogPricingRule type and represents a pricing rule. The pricing-rule-specific data must be set on the pricing_rule_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

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

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

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

customer_group_ids_any

A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule. Notice that a group ID is generated by the Customers API. If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer has a customer profile created or not. If this customer_group_ids_any field is set, the specified discount applies only to matched products sold to customers belonging to the specified customer groups.

string[]

discount_id

Unique ID for the CatalogDiscount to take off the price of all matched items.

string

exclude_products_id

CatalogProductSet to exclude from the pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.

string

exclude_strategy

If an exclude_products_id was given, controls which subset of matched products is excluded from any discounts.

Default value: LEAST_EXPENSIVE

string

Select exclude_strategy

LEAST_EXPENSIVE The least expensive matched products are excluded from the pricing. If the pricing rule is set to exclude one product and multiple products in the match set qualify as least expensive, then one will be excluded at random. Excluding the least expensive product gives the best discount value to the buyer.
MOST_EXPENSIVE The most expensive matched product is excluded from the pricing rule. If multiple products have the same price and all qualify as least expensive, one will be excluded at random. This guarantees that the most expensive product is purchased at full price.

match_products_id

Unique ID for the CatalogProductSet that will be matched by this rule. A match rule matches within the entire cart, and can match multiple times. This field will always be set.

string

minimum_order_subtotal_money

The minimum order subtotal (before discounts or taxes are applied) that must be met before this rule may be applied.

Money

name

User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off".

string

time_period_ids

A list of unique IDs for the catalog time periods when this pricing rule is in effect. If left unset, the pricing rule is always in effect.

string[]

valid_from_date

Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).

string

valid_from_local_time

Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.

string

valid_until_date

Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).

string

valid_until_local_time

Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.

string

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

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

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

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