Applies to: Catalog API
Learn how to build a simple product catalog for a cafe that serves coffee in small and large sizes, with skim or whole milk.
The Catalog API manages the item library in the Square Dashboard. Use it to add, update, or delete items. An item is made up of related catalog objects like taxes, modifiers, and options.
- You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit squareup.com/activation.
- You're familiar with HTTPS. If this is your first time working with HTTPS, see TLS and HTTPS before continuing.
- You need a valid access token. You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square Credentials.
The Catalog API includes several objects that enable efficient and standardized definitions of item variations in the seller's inventory. These objects include the following:
- Items - Generalized items such as "Shirt".
- Item variation - Specific items for sale such as "Polo shirt: Lg, red".
- Item options - Standardized attributes such as color, size, and style.
To add an item to a seller's library, use the UpsertCatalogObject endpoint to create catalog objects for the item (for example, a cup of coffee). For information about using item options to set variation characteristics, see Define Item Variations Using Options.
Before selling coffee, the catalog needs an item called "Cup of Coffee" without a size, a price, or modifiers. To charge for the coffee, include variations specifying the size, the price, and any modifiers. Add two variations (Small Coffee and Large Coffee), a CatalogTax object for taxes, and two optional CatalogModifier objects (with Skim Milk and Whole Milk). These include:
- A CatalogItem object named
Coffeefor coffee drinks. - Two CatalogItemVariation objects named
SmallandLargefor the coffee drink size variations. - A CatalogTax object for the sales tax applied when a payment is made on the coffee drink order.
- Two CatalogModifier objects for the two milk choices.
- A CatalogModifierList object to hold the two CatalogModifier objects to apply the milk choices to the coffee item.
The following steps apply to creating other types of catalog objects, except for image uploads. For details about uploading and attaching images to items, variations, or categories, see Work with Images.
Important
When creating an item, you must specify at least one variation. Otherwise, you get an INVALID_REQUEST error.
To add a coffee item to a catalog as a product offering of a seller, call the UpsertCatalogObject endpoint to create a CatalogItem object in the catalog. This is shown in the following REST API example:
In this example, the Coffee item has two variations (Small and Large).
#coffee is a temporary ID used as a placeholder for the permanent ID generated by Square. In the same request, you can use this temporary ID to reference the new object. The two variations in this example use #coffee to identify their parent item. If created in a separate request, use their Square-generated permanent IDs instead.
Because the UpsertCatalogObject endpoint creates various catalog objects, the data object must match the specified type. For example:
- Item - Set the
item_dataproperty to a CatalogItem object for theITEMtype. - Item Variation - Set
item_variation_datato a CatalogItemVariation object for theITEM_VARIATIONtype. - Item Discount - Set
discount_datato a CatalogDiscount object for aDISCOUNT.
Important
The type property must match the {object_type}_data property. Otherwise, the request fails.
In most locales, a sales tax must be levied on a sold product. To support taking taxes on an order, you must first create a CatalogTax object to set up the tax to be applied when the payment is made on the order.
The following code example shows how to create a tax object and add it to the catalog:
In this example, the drink tax is 7.5% of the pretax subtotal of an order and it applies to catalog-item-based line items and ad hoc order line items. If you don't specify the property, the new tax is created with "applies_to_custom_amounts": true.
Alternatively, you can combine the calls to create the Coffee item with the Small and Large variations and the Drink Tax object into a single call to the BatchUpsertCatalogObjects endpoint, as shown:
In the previous example, note that the catalog item item_data property includes the tax_ids sub-property:
"tax_ids": [ "#sales_tax" ]
This property connects the new CatalogTax to the CatalogItem created in the batch request. In an Orders API CreateOrder request, that tax is automatically applied to the coffee if the CreateOrder request includes the pricing_options property as shown in the following example:
"pricing_options": { "auto_apply_discounts": false, "auto_apply_taxes": true }
To enable sellers to offer the choices of adding skim milk and whole milk to the coffee drink, you can create two catalog modifiers to apply to the Coffee item. One way to add the modifiers is to create a modifier list containing individual modifiers as its entries.
The following example shows how to call the UpsertCatalogObject endpoint to create the CatalogModifierList object with two CatalogModifier objects for Skim Milk and Whole Milk:
For the modifiers in the modifier list to be applied to the Coffee item, you must have the resultant modifier list applied to the Coffee item, as explained in step 4.
To apply the modifier list created in step 3, call the UpdateItemModifierLists endpoint as shown in the following example:
Alternatively, you can call the BatchUpsertCatalogObjects endpoint to create a modifier list with appropriate modifier entries and add the modifier list to the Coffee item, together with the required item variations, in a single call to create all related CatalogObject instances at once.
After building your catalog, you can view and verify it by calling the ListCatalog endpoint to inspect the catalog items. The following request shows an example:
You can set product_type to FOOD_AND_BEV to create a food and beverage item with product-specific details. This is useful if you want to include details such as the calorie count, ingredients, or dietary preferences.
For example, the following request recreates the coffee item with an explicit product_type of FOOD_AND_BEV to contain information about the calorie count and dietary preference in the food_and_beverage_details property: