Migrate from the Connect V1 Items API

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.

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:

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:

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.

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.

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.

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.

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.
   
   

   

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

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 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."
      }
    ]
  }