Square Catalog API
The Catalog API from Square — 13 operation(s) for catalog.
Square Catalog API is one of 45 APIs that Square publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Catalog. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and an AsyncAPI specification.
This API exposes 14 operations across 13 paths, and defines 126 schemas. It is described by OpenAPI 3.2.0, at version 2.0.
Requests are made against a single base URL, https://connect.squareup.com.
14 operations
13 paths
126 schemas
1 DELETE3 GET9 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Square Catalog API declares
2 security schemes
for authenticating requests.
It supports OAuth 2.0 (oauth2) using the authorizationCode flow, exposing 57 scopes.
An API key is passed in the header as Authorization (oauth2ClientSecret).
Paths & Operations 14
Across 13 paths, the API surfaces 14 operations — 1 DELETE, 3 GET, 9 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
Catalog 14
POST
/v2/catalog/batch-delete
Square Batch Delete Catalog Objects
POST
/v2/catalog/batch-retrieve
Square Batch Retrieve Catalog Objects
POST
/v2/catalog/batch-upsert
Square Batch Upsert Catalog Objects
POST
/v2/catalog/images
Square Create Catalog Image
PUT
/v2/catalog/images/{image_id}
Square Update Catalog Image
GET
/v2/catalog/info
Square Catalog Info
GET
/v2/catalog/list
Square List Catalog
POST
/v2/catalog/object
Square Upsert Catalog Object
DELETE
/v2/catalog/object/{object_id}
Square Delete Catalog Object
GET
/v2/catalog/object/{object_id}
Square Retrieve Catalog Object
POST
/v2/catalog/search
Square Search Catalog Objects
POST
/v2/catalog/search-catalog-items
Square Search Catalog Items
POST
/v2/catalog/update-item-modifier-lists
Square Update Item Modifier Lists
POST
/v2/catalog/update-item-taxes
Square Update Item Taxes
Schemas 126
The contract defines 126 schemas that model the data the API accepts and returns. The most detailed are CatalogObject (29 properties), CatalogItem (22 properties), CatalogItemVariation (21 properties), CatalogPricingRule (13 properties). Each schema is shown below with its type and property counts.
Currency
string
Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO4217).
CatalogTimePeriod
object
Represents a time period - either a single period or a repeating period.
1 property
CatalogItemProductType
string
The type of a CatalogItem. Connect V2 only allows the creation of REGULAR or APPOINTMENTSSERVICE items.
CatalogItemVariation
object
An item variation, representing a product for sale, in the Catalog object model. Each [item](entity:CatalogItem) must have at least one item variation and can…
21 properties
UpdateItemModifierListsResponse
object
2 properties
CatalogQueryText
object
The query filter to return the search result whose searchable attribute values contain all of the specified keywords or tokens, independent of the token order…
1 property
1 required
CatalogModifierListModifierType
string
Defines the type of CatalogModifierList.
CatalogPricingType
string
Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.
StandardUnitDescriptionGroup
object
Group of standard measurement units.
2 properties
CatalogQuickAmountsSettings
object
A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
3 properties
1 required
CatalogInfoResponse
object
3 properties
MeasurementUnitCustom
object
The information needed to define a custom unit, provided by the seller.
2 properties
2 required
CatalogDiscountModifyTaxBasis
string
ListCatalogResponse
object
3 properties
CatalogItemFoodAndBeverageDetailsDietaryPreference
object
Dietary preferences that can be assigned to an FOODANDBEV item and its ingredients.
3 properties
CatalogItemOptionValue
object
An enumerated value that can link a CatalogItemVariation to an item option as one of its item option values.
5 properties
CatalogModifierOverride
object
Options to control how to override the default behavior of the specified modifier.
2 properties
1 required
CatalogItemOptionValueForItemVariation
object
A CatalogItemOptionValue links an item variation to an item option as an item option value. For example, a t-shirt item may offer a color option and a size opt…
2 properties
CatalogItemOption
object
A group of variations for a CatalogItem.
5 properties
SubscriptionPricingType
string
Determines the pricing of a [Subscription](entity:Subscription)
CatalogCustomAttributeDefinitionSellerVisibility
string
Defines the visibility of a custom attribute to sellers in Square client applications, Square APIs or in Square UIs (including Square Point of Sale application…
CatalogQueryItemsForItemOptions
object
The query filter to return the items containing the specified item option IDs.
1 property
CatalogCustomAttributeDefinitionSelectionConfig
object
Configuration associated with SELECTION-type custom attribute definitions.
2 properties
UpdateItemTaxesRequest
object
3 properties
1 required
MeasurementUnitVolume
string
The unit of volume used to measure a quantity.
SourceApplication
object
Represents information about the application used to generate a change.
3 properties
CatalogModifierListSelectionType
string
Indicates whether a CatalogModifierList supports multiple selections.
CatalogQuickAmountsSettingsOption
string
Determines a seller's option on Quick Amounts feature.
MeasurementUnitLength
string
The unit of length used to measure a quantity.
TaxInclusionType
string
Whether to the tax amount should be additional to or included in the CatalogItem price.
CatalogCustomAttributeDefinitionStringConfig
object
Configuration associated with Custom Attribute Definitions of type STRING.
1 property
CatalogObject
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…
29 properties
2 required
MeasurementUnitUnitType
string
Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.
SubscriptionPhase
object
Describes a phase in a subscription plan variation. For more information, see [Subscription Plans and Variations](https://developer.squareup.com/docs/subscript…
6 properties
1 required
CatalogCategoryType
string
Indicates the type of a category.
ItemVariationLocationOverrides
object
Price and inventory alerting overrides for a CatalogItemVariation at a specific Location.
8 properties
UpdateItemTaxesResponse
object
2 properties
BatchRetrieveCatalogObjectsResponse
object
3 properties
CreateCatalogImageResponse
object
2 properties
CatalogInfoResponseLimits
object
11 properties
CatalogQueryItemVariationsForItemOptionValues
object
The query filter to return the item variations containing the specified item option value IDs.
1 property
MeasurementUnitWeight
string
Unit of weight used to measure a quantity.
CatalogCategory
object
A category to which a CatalogItem instance belongs.
11 properties
DeleteCatalogObjectResponse
object
3 properties
CatalogStockConversion
object
Represents the rule of conversion between a stockable [CatalogItemVariation](entity:CatalogItemVariation) and a non-stockable sell-by or receive-by CatalogItem…
3 properties
3 required
CatalogCustomAttributeDefinitionType
string
Defines the possible types for a custom attribute.
BatchUpsertCatalogObjectsRequest
object
2 properties
2 required
CatalogItem
object
A [CatalogObject](entity:CatalogObject) instance of the ITEM type, also referred to as an item, in the catalog.
22 properties
MeasurementUnitArea
string
Unit of area used to measure a quantity.
TaxCalculationPhase
string
When to calculate the taxes due on a cart.
CatalogAvailabilityPeriod
object
Represents a time period of availability.
3 properties
StandardUnitDescription
object
Contains the name and abbreviation for standard measurement unit.
3 properties
CatalogQueryItemsForTax
object
The query filter to return the items containing the specified tax IDs.
1 property
1 required
SearchCatalogObjectsRequest
object
8 properties
CategoryPathToRootNode
object
A node in the path from a retrieved category to its root node.
2 properties
CatalogQuery
object
A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects endpoint. Although a q…
10 properties
CatalogQuerySortedAttribute
object
The query expression to specify the key to sort search results.
3 properties
1 required
CatalogSubscriptionPlan
object
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…
6 properties
1 required
InventoryAlertType
string
Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.
UpsertCatalogObjectResponse
object
3 properties
DayOfWeek
string
Indicates the specific day of the week.
UpdateCatalogImageRequest
object
1 property
1 required
Range
object
The range of a number value between the specified lower and upper bounds.
2 properties
BatchUpsertCatalogObjectsResponse
object
4 properties
CatalogItemFoodAndBeverageDetailsDietaryPreferenceType
string
The type of dietary preference for the FOODANDBEV type of items and integredients.
CatalogQuickAmountType
string
Determines the type of a specific Quick Amount.
CatalogCustomAttributeDefinition
object
Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catal…
12 properties
3 required
Money
object
Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered…
2 properties
CatalogCustomAttributeDefinitionNumberConfig
object
1 property
SubscriptionPricing
object
Describes the pricing for the subscription.
3 properties
CatalogCustomAttributeValue
object
An instance of a custom attribute. Custom attributes can be defined and added to ITEM and ITEMVARIATION type catalog objects. [Read more about custom attribute…
8 properties
CatalogQuerySet
object
The query filter to return the search result(s) by exact match of the specified attributename and any of the attributevalues.
2 properties
2 required
MeasurementUnitGeneric
string
SearchCatalogObjectsResponse
object
5 properties
SearchCatalogItemsRequestStockLevel
string
Defines supported stock levels of the item inventory.
SubscriptionCadence
string
Determines the billing cadence of a [Subscription](entity:Subscription)
CatalogModifierList
object
For a text-based modifier, this encapsulates the modifier's text when its modifiertype is TEXT. For example, to sell T-shirts with custom prints, a text-based…
9 properties
CatalogQueryItemsForModifierList
object
The query filter to return the items containing the specified modifier list IDs.
1 property
1 required
CatalogMeasurementUnit
object
Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.
2 properties
CatalogObjectBatch
object
A batch of catalog objects.
1 property
1 required
CatalogObjectType
string
Possible types of CatalogObjects returned from the catalog, each containing type-specific properties in the data field corresponding to the specified object ty…
CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference
string
Standard dietary preferences for food and beverage items that are recommended on item creation.
CatalogQueryExact
object
The query filter to return the search result by exact match of the specified attribute name and value.
2 properties
2 required
ErrorCode
string
Indicates the specific error that occurred during a request to a Square API.
CreateCatalogImageRequest
object
4 properties
2 required
ArchivedState
string
Defines the values for the archivedstate query expression used in [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) to return the archived, not arc…
CatalogSubscriptionPlanVariation
object
Describes a subscription plan variation. A subscription plan variation represents how the subscription for a product or service is sold. For more information,…
6 properties
2 required
CatalogQueryPrefix
object
The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
2 properties
2 required
CatalogPricingRule
object
Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
13 properties
CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection
object
A named selection for this SELECTION-type custom attribute definition.
2 properties
1 required
ErrorCategory
string
Indicates which high-level category of error has occurred during a request to the Connect API.
CatalogQuickAmount
object
Represents a Quick Amount in the Catalog.
4 properties
2 required
BatchDeleteCatalogObjectsRequest
object
1 property
CatalogImage
object
An image file to use in Square catalogs. It can be associated with CatalogItem, CatalogItemVariation, CatalogCategory, and CatalogModifierList objects. Only th…
4 properties
CatalogItemOptionForItem
object
An option that can be assigned to an item. For example, a t-shirt item may offer a color option or a size option.
1 property
CatalogProductSet
object
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,…
7 properties
UpsertCatalogObjectRequest
object
2 properties
2 required
SearchCatalogItemsRequest
object
Defines the request body for the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.
10 properties
UpdateCatalogImageResponse
object
2 properties
CatalogItemFoodAndBeverageDetails
object
The food and beverage-specific details of a FOODANDBEV item.
3 properties
CatalogQueryRange
object
The query filter to return the search result whose named attribute values fall between the specified range.
3 properties
1 required
CatalogEcomSeoData
object
SEO data for for a seller's Square Online store.
3 properties
Product
string
Indicates the Square product used to generate a change.
CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient
string
Standard ingredients for food and beverage items that are recommended on item creation.
CatalogV1Id
object
A Square API V1 identifier of an item, including the object ID and its associated location ID.
2 properties
CatalogCustomAttributeDefinitionAppVisibility
string
Defines the visibility of a custom attribute to applications other than their creating application.
BatchRetrieveCatalogObjectsRequest
object
5 properties
1 required
CatalogItemModifierListInfo
object
References a text-based modifier or a list of non text-based modifiers applied to a CatalogItem instance and specifies supported behaviors of the application.
6 properties
1 required
CatalogDiscount
object
A discount applicable to items.
8 properties
RetrieveCatalogObjectResponse
object
3 properties
CustomAttributeFilter
object
Supported custom attribute query expressions for calling the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint to search for items or item…
6 properties
SortOrder
string
The order (e.g., chronological or alphabetical) in which results from a request are returned.
BatchDeleteCatalogObjectsResponse
object
3 properties
UpdateItemModifierListsRequest
object
3 properties
1 required
MeasurementUnit
object
Represents a unit of measurement to use with a quantity, such as ounces or inches. Exactly one of the following fields are required: customunit, areaunit, leng…
8 properties
MeasurementUnitTime
string
Unit of time used to measure a quantity (a duration).
SearchCatalogItemsResponse
object
Defines the response body returned from the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.
4 properties
ModifierLocationOverrides
object
Location-specific overrides for specified properties of a CatalogModifier object.
3 properties
CatalogDiscountType
string
How to apply a CatalogDiscount to a CatalogItem.
Error
object
Represents an error encountered during a request to the Connect API. See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) fo…
4 properties
2 required
ExcludeStrategy
string
Indicates which products matched by a CatalogPricingRule will be excluded if the pricing rule uses an exclude set.
CatalogItemFoodAndBeverageDetailsIngredient
object
Describes the ingredient used in a FOODANDBEV item.
3 properties
CatalogTax
object
A tax applicable to an item.
7 properties
CatalogObjectCategory
object
A category that can be assigned to an item or a parent category that can be assigned to another category. For example, a clothing category can be assigned to a…
2 properties
CatalogIdMapping
object
A mapping between a temporary client-supplied ID and a permanent server-generated ID. When calling [UpsertCatalogObject](api-endpoint:Catalog-UpsertCatalogObje…
2 properties
CatalogModifier
object
A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item.
6 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Square 12
Other APIs Square publishes across the network.
Square Reporting API
Square Channels API
Square Transfer Orders API
Square ApplePay API
Square BankAccounts API
Square BookingCustomAttributes API
Square Bookings API
Square Cards API
Square CashDrawers API
Square Checkout API
Square CustomerCustomAttributes API
Square CustomerGroups API
#Catalog
Where this information came from
This is an independent, third-party profile of Square Catalog API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.