Migrate from the Connect V1 Items API

Link to section

What you need to know

The Connect V1 Items API lets you manage product catalogs and inventory information. Square APIs split product catalog functionality and inventory management between the Catalog API and the Inventory API.

Link to section

Important dates

  • Deprecation: 2019-11-20
  • Retirement: 2020-11-18
Link to section

Get help

If you need help migrating to Connect V2 or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

General behavioral differences

  • Everything is a catalog object - The V2 Catalog API packages all information as a CatalogObject, which is a generalized wrapper for the various subclasses in the Catalog object model. Valid subclasses include items, item variations, modifiers, modifier lists, categories, discounts, taxes, and images. For more information about designing an effective product catalog with the V2 Catalog API, see Design a Catalog.
  • Location-based data vs account-based data - The V1 Items API is location based, which means all product catalog information is associated with a specific Square location. The V2 Catalog API is account based, which means the product catalog is associated with a particular Square account. Catalog objects can have an optional location assignment, but the object itself is global.
  • Fees are now taxes - The V1 Items API refers to taxes as fees. The V2 Catalog API equivalent is a tax object, which includes similar fields as the v1Fee object.
  • Images are first-class entities - The V1 Items API forced catalog images to be linked to a specific item as a master image. As a result, any item sharing the same image had to include its own copy of the image file. In the V2 Catalog API, images exist as a top-level data object and multiple items can reference the same image object. For more information about using the CreateCatalogImage endpoint, see Create a Catalog Image.
  • Object IDs are server generated - The V1 Items API allows client-generated permanent IDs. The V2 Catalog API generates permanent IDs on the server. You can provide temporary IDs (such as #drinks) during V2 Catalog creation calls if you want to create related objects (such as a category, items, and the associated item variations) in a single call and link them. Square replaces the temporary ID with a unique permanent ID in the response object that must be used to reference the object in subsequent calls (for example, when recording line items in a transaction). For more information about creating new catalog objects, see Build a Simple Catalog.
  • Inventory API supports additional states and history - The V1 Items API only allows adjustments to the current stock count. The V2 Inventory API supports adjustments and additional inventory states (such as WASTE) and provides a history of inventory changes for individual item variations.
Link to section

Discontinued functionality

Neither the V2 Catalog API nor the V2 Inventory API support management of Favorites pages for the Square Point of Sale UI. Code relying on the following endpoints will break when the V1 Items API retires:

  • CreatePage - Creates a Favorites page in the Square Point of Sale UI.
  • DeletePage - Deletes an existing Favorites page and all its cells from the Square Point of Sale UI.
  • DeletePageCell - Deletes a cell from a Favorites page in Square Register.
  • ListPages - Lists all of a location's Favorites pages in Square Register.
  • UpdatePage - Modifies the details of a Favorites page in Square Register.
  • UpdatePageCell - Modifies a cell of a Favorites page in Square Register.

Favorites pages can still be managed directly in the Square Point of Sale application.

Link to section

Webhook and endpoint mapping

Link to section

Webhooks

inventory.count.updated replaces INVENTORY_UPDATED. The V2 Webhooks expands on information returned by the V1 Webhooks by including count details for all available inventory states. If your application only uses the IN_STOCK state, you must filter out the other states.

Link to section

Endpoints

  • Square Catalog API endpoints replace the product management endpoints in the V1 Items API - The Catalog API supports batching and supports individual calls for creating, retrieving, updating, and deleting catalog entities (such as items, item variations, modifiers, discounts, and taxes).
  • Square Inventory API endpoints replace the inventory management endpoints in the V1 Items API - The Inventory API supports batching and supports individual calls for auditing inventory adjustment histories and adjusting inventory quantities for Square Catalog item variations.

Code relying on the following endpoints must be updated to avoid breaking when the V1 Items API retires:

V1 Items endpointReplacement
AdjustInventoryInventory.BatchChangeInventory

Use InventoryAdjustment changes to record a SALE or RECEIVE_STOCK adjustment type. Use InventoryPhysicalCount to record a MANUAL_ADJUST adjustment type.
ApplyFeeCatalog.UpdateItemTaxes, Catalog.BatchUpsertCatalogObjects, or Catalog.UpsertCatalogObject

Use the dedicated taxes endpoint or an upsert endpoint to link the tax to an item.
ApplyModifierListCatalog.UpdateItemModifierLists, Catalog.BatchUpsertCatalogObjects, or Catalog.UpsertCatalogObject

Use the dedicated modifier list endpoint or an upsert endpoint to link the modifier list to an item.
CreateCategoryCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type CATEGORY.
CreateDiscountCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type DISCOUNT.
CreateFeeCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create the fee as a new catalog object with type TAX.
CreateItemCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type ITEM.
CreateModifierListCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type MODIFIER_LIST.
CreateModifierOptionCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type MODIFIER. You should create and update modifiers by nesting them within a MODIFIER_LIST.
CreateVariationCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type ITEM_VARIATION. You should create and update variations by nesting them within an item.
DeleteCategoryCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated CATEGORY object.
DeleteDiscountCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated DISCOUNT object.
DeleteFeeCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated TAX object.
DeleteItemCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated ITEM object.
DeleteModifierListCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated MODIFIER_LIST object.
DeleteModifierOptionCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated MODIFIER object.
DeleteVariationCatalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject

Use the delete endpoints to destroy the associated ITEM_VARIATION object.
ListCategoriesCatalog.ListCatalog

Set the type field to CATEGORY.
ListDiscountsCatalog.ListCatalog

Set the type field to DISCOUNT.
ListFeesCatalog.ListCatalog

Set the type field to TAX.
ListInventoryInventory.BatchRetrieveInventoryCounts

Provide the relevant location ID in the request body rather than the endpoint path.
ListItemsCatalog.ListCatalog

Set the type field to ITEM.
ListModifierListsCatalog.ListCatalog

Set the type field to MODIFIER_LIST.
RemoveFeeCatalog.UpdateItemTaxes, Catalog.BatchUpsertCatalogObjects, or Catalog.UpsertCatalogObject

Use the dedicated taxes endpoint or an upsert endpoint to unlink the tax from an item.
RemoveModifierListCatalog.UpdateItemModifierLists, Catalog.BatchUpsertCatalogObject, or Catalog.UpsertCatalogObject

Use the dedicated modifier list endpoint or an upsert endpoint to unlink the modifier list from an item.
RetrieveItemCatalog.BatchRetrieveCatalogObjects or Catalog.RetrieveCatalogObject

Provide the Square-issued ID of a CatalogObject with type ITEM.
RetrieveModifierListCatalog.BatchRetrieveCatalogObjects or Catalog.RetrieveCatalogObject

Provide the Square-issued ID of a CatalogObject with type MODIFIER_LIST.
UpdateCategoryCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type CATEGORY.
UpdateDiscountCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type DISCOUNT.
UpdateFeeCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type TAX.
UpdateItemCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type ITEM.
UpdateModifierListCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type MODIFIER_LIST.
UpdateModifierOptionCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type MODIFIER. You should create and update modifiers by nesting them within a MODIFIER_LIST.
UpdateVariationCatalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type ITEM_VARIATION. You should create and update variations by nesting them within an ITEM.
UploadItemImageCatalog.CreateCatalogImage

Supports JPEG, PJPEG, PNG, and GIF formats.
Link to section

Example migration

Link to section

Simple V1 Items product catalog

Consider a product catalog built with the V1 Items API that includes the following entities:

State sales tax of 7.25%:

{ "id": "sales-tax", "name": "State Sales Tax", "rate": "0.0725", "calculation_phase": "FEE_SUBTOTAL_PHASE", "adjustment_type": "TAX", "applies_to_custom_amounts": true, "enabled": true, "inclusion_type": "ADDITIVE" }

"Drinks" category:

{ "id": "drinks", "name": "Drinks" }

"Latte" item with two variations:

To define and build the product catalog information with the V1 Items API:

  1. Model each entity as their respective types (fee, category, item, and variation).
  2. Upload the category information with CreateCategory.
  3. Upload the fee information with CreateFee.
  4. Upload the item and its variations with CreateItem.
  5. Apply the tax to the item with ApplyFee.
  6. Fetch the completed item with RetrieveItem.
Link to section

Building with the V2 Catalog API

To define and build the same product catalog with the V2 Catalog API:

  1. Model each entity as an individual CatalogObject with temporary IDs to link the objects.
  2. Combine the objects as a batch request and upload the information in a single call to batch upsert catalog objects. The return set includes all completed entities as well as a mapping between the client-assigned temporary IDs and the permanent Square-generated IDs assigned during object creation.

Important

Because temporary IDs are only valid during object creation, it is important to batch related information rather than constructing the objects independently.

Link to section

Model the fee (tax) information

  1. Set the type field of the catalog object to TAX.
  2. Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
  3. Change the rate (rate) from a decimal string to a percentage string (percentage).
  4. Change the calculation phase (calculation_phase) from FEE_SUBTOTAL_PHASE to TAX_SUBTOTAL_PHASE.
  5. Remove the adjustment_type field. The object type makes the purpose of the fee explicit.
  6. Move everything but the ID field and adjustment type under the tax_data field.

A diagram showing two JSON blocks representing tax/fee information with arrows illustrating how fields in the v1 object translate to a v2 CatalogObject.

Link to section

Model the category information

  1. Set the type field of the catalog object to CATEGORY.
  2. Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
  3. Move everything but the ID field under the category_data field.

A diagram showing two JSON blocks representing category information with arrows illustrating how fields in the V1 object translate to a V2 CatalogObject.

Link to section

Model the item and variation information

  1. Set the type field of the parent catalog object to ITEM.

  2. Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.

  3. Change the product type (type) from NORMAL to REGULAR (product_type).

  4. Move the remaining object details under the item_data field.

  5. Link the item and tax object by populating the tax_ids list with the temporary tax ID.

  6. Create catalog objects for the child variations:

    1. Set the type field to ITEM_VARIATION.
    2. Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
    3. Convert the V1Money object under price_money to a V2 Money object.
    4. Move the remaining object details under the item_variation_data field.

    A diagram showing two JSON blocks representing an item and variations with arrows illustrating how fields in the v1 object translate to a set of v2 CatalogObject.

Link to section

Batch and upload the catalog objects

Finally, you can upload the product catalog information with a single call to the batch upsert catalog objects endpoint (/v2/catalog/batch-upsert):

Batch upsert catalog objects

Link to section

List or retrieve inventory

In the V1 Items API, to retrieve the in-stock counts of a seller's inventory, you would call the ListInventory endpoint while specifying the seller ID (also known as merchant token) as the seller_id path parameter in the request URL. An example of such a request is shown as follows:

GET /v1/{seller_id}/inventory

The endpoint allows you to specify the limit parameter to set the result page size to override the default value of 100.

GET /v1/{seller_id}/inventory?limit=50

The successful response returns a list of inventory objects representing item variations in stock. The quantity_on_hand attribute value corresponds to the in-stock quantity.

In the V2 Inventory API, the same operation amounts to calling the BatchRetrieveInventoryCounts endpoint of the Inventory API, with the following input:

curl https://connect.squareupsandbox.com/v2/inventory/batch-retrieve-counts \ -X POST \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "states": [ "IN_STOCK" ] }'

You no longer explicitly specify the seller ID in the call.

In addition, you can also add other query filters in the input to specify inventory states, object IDs, and seller's location IDs to return quantities of item variations in matching the specified filtering criteria.

curl https://connect.squareupsandbox.com/v2/inventory/batch-retrieve-counts \ -X POST \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "states": ["IN_STOCK"], "catalog_object_ids": [ "C6MGLXXDLJ6I4QYZ6NHWOHO4" ], "location_ids": [ "SNTR5190QMFGM" ], "updated_after": "2020-11-16T00:00:00.000Z" }'

The successful response has a different format, returning a list of inventory count objects. An example is shown as follows:

{ "counts": [ { "catalog_object_id": "C6MGLXXDLJ6I4QYZ6NHWOHO4", "catalog_object_type": "ITEM_VARIATION", "state": "IN_STOCK", "location_id": "SNTR5190QMFGM", "quantity": "100", "calculated_at": "2020-12-16T23:23:47.121611Z" } ] }
Link to section

Adjust or change inventory

In the V1 Items API, to add 10 in-stock quantity of a given item variation to the inventory of a seller, you would call the AdjustInventory endpoint and specify the seller ID (also known as merchant token) as the seller_id attribute value in the request payload. An example of such a request is shown as follows:

POST /v1/{seller_id}/inventory/{variation_id}/adjustment { "quantity_delta": 10, "adjustment_type": "RECEIVE_STOCK" }

In the V2 Inventory API, the same operation amounts to calling the BatchChangeInventory endpoint and specify the following input:

In V2, you must specify the location ID, instead of the seller ID as in V1, as part of the request input.

If you retrieve the inventory count on this item variation, you get the following output:

{ "counts": [ { "catalog_object_id": "GUN7HNQBH7ZRARYZN52E7O4B", "catalog_object_type": "ITEM_VARIATION", "state": "IN_STOCK", "location_id": "SNTR5190QMFGM", "quantity": "10", "calculated_at": "2021-02-11T21:04:55.2119Z" } ] }
Link to section

Common migration issues

  • Forgetting to preserve location assignments - Items and item variations are shared at the account level. If keeping the location assignment is important, make sure to set the present_at_location_ids field to configure the available locations; otherwise, the entities created are universal.

  • Forgetting to convert percentage notation - Tax (fee) objects in the V1 Items API use decimal notation to define percentages (such as 0.0725) while tax objects in V2 use the percentage directly (such as 7.25).

  • Forgetting to convert V1Money objects to V2 Money objects - The two money structures have the same construction (an integer amount and a string to indicate the currency), but the field names are different.

  • Assigning locations to categories - Categories cannot be assigned to a specific location because they could be linked to items across multiple locations. If you try to assign a location, you get the following error:

    { "errors":[ { "category" : "INVALID_REQUEST_ERROR", "code" : "INVALID_VALUE", "detail" : "This object type is automatically enabled globally, set 'present_at_all_locations' to true or leave blank, and leave 'present_at_location_ids', and 'absent_at_location_ids' blank." } ] }