The following information helps you migrate from the Connect V1 Items API code to the correct Square API counterparts. For general guidance about the differences between Connect V1 and Square APIs, see the Connect V1 Migration guide.
Migrate from the Connect V1 Items API
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.
- Deprecation: 2019-11-20
- Retirement: 2020-11-18
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.
- 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.
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.
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.
- 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 endpoint | Replacement |
---|---|
AdjustInventory | Inventory.BatchChangeInventory Use InventoryAdjustment changes to record a SALE or RECEIVE_STOCK adjustment type. Use InventoryPhysicalCount to record a MANUAL_ADJUST adjustment type. |
ApplyFee | Catalog.UpdateItemTaxes , Catalog.BatchUpsertCatalogObjects , or Catalog.UpsertCatalogObject Use the dedicated taxes endpoint or an upsert endpoint to link the tax to an item. |
ApplyModifierList | Catalog.UpdateItemModifierLists , Catalog.BatchUpsertCatalogObjects , or Catalog.UpsertCatalogObject Use the dedicated modifier list endpoint or an upsert endpoint to link the modifier list to an item. |
CreateCategory | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Use the upsert endpoints to create a new catalog object with type CATEGORY . |
CreateDiscount | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Use the upsert endpoints to create a new catalog object with type DISCOUNT . |
CreateFee | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Use the upsert endpoints to create the fee as a new catalog object with type TAX . |
CreateItem | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Use the upsert endpoints to create a new catalog object with type ITEM . |
CreateModifierList | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Use the upsert endpoints to create a new catalog object with type MODIFIER_LIST . |
CreateModifierOption | Catalog.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 . |
CreateVariation | Catalog.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. |
DeleteCategory | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated CATEGORY object. |
DeleteDiscount | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated DISCOUNT object. |
DeleteFee | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated TAX object. |
DeleteItem | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated ITEM object. |
DeleteModifierList | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated MODIFIER_LIST object. |
DeleteModifierOption | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated MODIFIER object. |
DeleteVariation | Catalog.BatchDeleteCatalogObjects or Catalog.DeleteCatalogObject Use the delete endpoints to destroy the associated ITEM_VARIATION object. |
ListCategories | Catalog.ListCatalog Set the type field to CATEGORY . |
ListDiscounts | Catalog.ListCatalog Set the type field to DISCOUNT . |
ListFees | Catalog.ListCatalog Set the type field to TAX . |
ListInventory | Inventory.BatchRetrieveInventoryCounts Provide the relevant location ID in the request body rather than the endpoint path. |
ListItems | Catalog.ListCatalog Set the type field to ITEM . |
ListModifierLists | Catalog.ListCatalog Set the type field to MODIFIER_LIST . |
RemoveFee | Catalog.UpdateItemTaxes , Catalog.BatchUpsertCatalogObjects , or Catalog.UpsertCatalogObject Use the dedicated taxes endpoint or an upsert endpoint to unlink the tax from an item. |
RemoveModifierList | Catalog.UpdateItemModifierLists , Catalog.BatchUpsertCatalogObject , or Catalog.UpsertCatalogObject Use the dedicated modifier list endpoint or an upsert endpoint to unlink the modifier list from an item. |
RetrieveItem | Catalog.BatchRetrieveCatalogObjects or Catalog.RetrieveCatalogObject Provide the Square-issued ID of a CatalogObject with type ITEM . |
RetrieveModifierList | Catalog.BatchRetrieveCatalogObjects or Catalog.RetrieveCatalogObject Provide the Square-issued ID of a CatalogObject with type MODIFIER_LIST . |
UpdateCategory | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type CATEGORY . |
UpdateDiscount | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type DISCOUNT . |
UpdateFee | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type TAX . |
UpdateItem | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type ITEM . |
UpdateModifierList | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type MODIFIER_LIST . |
UpdateModifierOption | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type MODIFIER . You should create and update modifiers by nesting them within a MODIFIER_LIST . |
UpdateVariation | Catalog.BatchUpsertCatalogObjects or Catalog.UpsertCatalogObject Provide an updated CatalogObject with type ITEM_VARIATION . You should create and update variations by nesting them within an ITEM . |
UploadItemImage | Catalog.CreateCatalogImage Supports JPEG, PJPEG, PNG, and GIF formats. |
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:
{
"id": "latte",
"name": "Whole Milk Latte 1",
"description": "A coffee drink with milk and a small amount of foam.",
"type": "NORMAL",
"color": "593c00",
"abbreviation": "LATTE",
"visibility": "PUBLIC",
"available_online": false,
"available_for_pickup": false,
"category_id": "drinks",
"variations": [
{
"id": "latte-hot",
"name": "Latte - Hot",
"item_id": "latte",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency_code": "USD"
},
"sku": "12345",
"track_inventory": true,
"inventory_alert_type": "NONE"
},
{
"id": "latte-iced",
"name": "Latte - Iced",
"item_id": "latte",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency_code": "USD"
},
"sku": "67890",
"track_inventory": true,
"inventory_alert_type": "NONE"
}
]
}
To define and build the product catalog information with the V1 Items API:
- Model each entity as their respective types (fee, category, item, and variation).
- Upload the category information with
CreateCategory
. - Upload the fee information with
CreateFee
. - Upload the item and its variations with
CreateItem
. - Apply the tax to the item with
ApplyFee
. - Fetch the completed item with
RetrieveItem
.
To define and build the same product catalog with the V2 Catalog API:
- Model each entity as an individual CatalogObject with temporary IDs to link the objects.
- 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.
- Set the
type
field of the catalog object toTAX
. - Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
- Change the rate (
rate
) from a decimal string to a percentage string (percentage
). - Change the calculation phase (
calculation_phase
) fromFEE_SUBTOTAL_PHASE
toTAX_SUBTOTAL_PHASE
. - Remove the
adjustment_type
field. The object type makes the purpose of the fee explicit. - Move everything but the ID field and adjustment type under the
tax_data
field.
- Set the
type
field of the catalog object toCATEGORY
. - Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
- Move everything but the ID field under the
category_data
field.
Set the
type
field of the parent catalog object toITEM
.Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
Change the product type (
type
) fromNORMAL
toREGULAR
(product_type
).Move the remaining object details under the
item_data
field.Link the item and tax object by populating the
tax_ids
list with the temporary tax ID.Create catalog objects for the child variations:
- Set the
type
field toITEM_VARIATION
. - Add a pound symbol (#) to the beginning of the object ID to create a temporary ID.
- Convert the
V1Money
object underprice_money
to a V2 Money object. - Move the remaining object details under the
item_variation_data
field.
- Set the
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
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.
{ 'inventories': [ { "variation_id": "<ID_of_this_item_variation_in_stock>", "quantity_on_hand": <number_of_this_item_variation_in_stock>, "item_id": "<ID_of_item_containing_this_item_variation_in_stock>", "item_name": "<name_of_item_containing_this_item_variation_in_stock>", "variation_name": "<name_of_this_item_variation_in_stock>" }, { "variation_id": "...", "quantity_on_hand": ..., "item_id": "...", "item_name": "...", "variation_name": "..." }, ... ] }
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"
}
]
}
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:
curl https://connect.squareupsandbox.com/v2/inventory/batch-change \
-X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "4269eb27-134e-4b02-95ad-c3cc3561aab3",
"changes": [
{
"adjustment": {
"catalog_object_id": "GUN7HNQBH7ZRARYZN52E7O4B",
"from_state": "NONE",
"to_state": "IN_STOCK",
"quantity": "10",
"location_id": "SNTR5190QMFGM",
"occurred_at": "2021-02-11T21:00:00Z"
},
"type": "ADJUSTMENT"
}
]
}'
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"
}
]
}
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 V2Money
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." } ] }