Connect v1 Migration

Migrate from Connect v1 Items API

The information below will help you migrate from the Connect v1 Items API to the correct Square API counterparts. For general guidance on the differences between Connect v1 and Square APIs, see the Connect v1 Migration guide.

Catalog API
Inventory API
cURL (Command Line)

What you need to know
Permalink Get a link to this section

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

Important dates
Permalink Get a link to this section

  • Deprecation: 2019-11-20

  • Retirement: 2020-11-18

Get help
Permalink Get a link to this section

If you need help migrating to Connect v2 or need more time to complete your migration, please contact Developer Support, join our Slack, or reach out to your Square Account Manager.

General behavioral differences
Permalink Get a link to this section

  • 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. See Design a Catalog for more detailed guidance on designing an effective product catalog with the v2 Catalog API.

  • Location-based data vs account based data — The v1 Items API is location based, which means that 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 their 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. See the catalog image recipe for more information on using the CreateCatalogImage endpoint.

  • 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 may provide temporary IDs (e.g., #drinks) during v2 Catalog creation calls if you want to create related objects (e.g., a category, items, and the associated item variations) in a single call and link them together. 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. See the Catalog API build guide for more detailed guidance on creating new catalog objects.

  • 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, additional inventory states (e.g,. WASTE), and provides a history of inventory changes for individual item variations.

Discontinued functionality
Permalink Get a link to this section

Neither the v2 Catalog AP 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 of 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 app.

Webhook and endpoint mapping
Permalink Get a link to this section

Webhooks
Permalink Get a link to this section

  • inventory.count.updated replaces INVENTORY_UPDATED. The v2 webhook expands on information returned by the v1 webhook as it includes count details for all available inventory states. If your application only cares about the IN_STOCK state, you must filter out the other states.

Endpoints
Permalink Get a link to this section

  • Square Catalog API endpoints replace the product management endpoints in v1 Items API. Catalog API supports batching as well as 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 v1 Items API. Inventory API supports batching as well as 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.BatchUpsertCatalogObject, or Catalog.UpsertCatalogObject

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

Use the dedicated modifier list endpoint or an upsert endpoint to link the modifier list to an item.
CreateCategory Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

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

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

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

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

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

Use the upsert endpoints to create a new catalog object with type MODIFIER. We recommend that you create and update modifiers by nesting them within a MODIFIER_LIST.
CreateVariation Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Use the upsert endpoints to create a new catalog object with type ITEM_VARIATION. We recommend that you 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.BatchUpsertCatalogObject, 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.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type CATEGORY.
UpdateDiscount Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type DISCOUNT.
UpdateFee Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type TAX.
UpdateItem Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type ITEM.
UpdateModifierList Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type MODIFIER_LIST.
UpdateModifierOption Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type MODIFIER. We recommend that you create and update modifiers by nesting them within a MODIFIER_LIST.
UpdateVariation Catalog.BatchUpsertCatalogObject or Catalog.UpsertCatalogObject

Provide an updated CatalogObject with type ITEM_VARIATION. We recommend that you create and update variations by nesting them within an ITEM.
UploadItemImage Catalog.CreateCatalogImage

Supports JPEG, PJPEG, PNG, and GIF formats.

Example migration
Permalink Get a link to this section

A simple v1 Items product catalog
Permalink Get a link to this section

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 2 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 v1 Items API:

  1. Model each of the entities 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.

Building with v2 Catalog API
Permalink Get a link to this section

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

  1. Model each of the entities 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

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

Model the fee (tax) information
Permalink Get a link to this section

  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.

2 JSON blocks representing tax/fee informtion with arrows illustrating how fields in the v1 object translate to a v2 CatalogObject

Model the category information
Permalink Get a link to this section

  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.

2 JSON blocks representing category informtion with arrows illustrating how fields in the v1 object translate to a v2 CatalogObject

Model the item and variation information
Permalink Get a link to this section

  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.

2 JSON blocks representing an item plus variations with arrows illustrating how fields in the v1 object translate to a set of v2 CatalogObject

Batch and upload the catalog objects
Permalink Get a link to this section

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

# Create the request body
# Assumes each data object is a JSON blob as outlined above
REQUEST_BODY='{
  "idempotency_key":  "'$(uuidgen)'",
  "batches": [
    {
      "objects": [
        '${TAX_DATA}',
        '${CATEGORY_DATA}',
        '${ITEM_DATA}'
      ]
    }
  ]
}'

# Call the endpoint
# Assumes AUTHZ_TOKEN is set to a valid access token for the Square account
curl                                        \
  -X POST                                   \
  -H "Authorization: Bearer ${AUTHZ_TOKEN}" \
  -H "Content-Type: application/json"       \
  -d "${REQUEST_BODY}"                      \
  https://connect.squareup.com/v2/catalog/batch-upsert | json_pp

Common migration pitfalls
Permalink Get a link to this section

  • 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 will be universal.

  • Forgetting to convert percentage notation — Tax (fee) objects in v1 use decimal notation to define percentages (e.g., 0.0725) while tax objects in v2 use the percentage directly (e.g., 7.25).

  • Forgetting to convert V1Money objects to v2 Money objects — The 2 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 since they could be linked to items across multiple locations. If you try to assign a location, you will 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."
        }
      ]
    }