Connect v1 Migration

Migrate from the Connect v1 Items API

cURL (Command Line)

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.

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

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.

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, 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. 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.

Discontinued functionality Permalink Get a link to this section

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.

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 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.

Endpoints Permalink Get a link to this section

  • 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.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. You should 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. 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.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. You should 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. You should 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

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 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.

Building with the 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 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.

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