Build and Manage a Simple Inventory

Applies to: Inventory API | Catalog API

Learn how to create catalog item variations, increase inventory amounts, and update the inventory.

Overview

The following steps are used when building and managing a simple inventory with the Inventory API:

Adding a fixed number of products as item variations to inventory.
Updating inventory by removing a number of damaged item variations from stock.
Viewing inventory counts and changes.

Important

If you're processing itemized payments with Square APIs or hardware, item variation quantities are automatically transitioned from IN_STOCK to SOLD. For other operations resulting in inventory state changes of item variations, you need to apply the adjustment manually.

Link to section

Requirements and limitations

You have item variations defined in your Square product catalog. For information about working with the Catalog API, see the Build a Simple Catalog.
Applications using OAuth must have INVENTORY_READ permission to read inventory information and INVENTORY_WRITE permission to update inventory states.
You're using Square-Version 2018-09-18 or later.
You've read the introductory review of this API.
You're familiar with basic web development. If you're new to web development, you should read Getting started with the Web by Mozilla.org before continuing.

You need a valid access token. You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square Credentials.
You need an active location ID - Copy a developer account location ID from the Locations page of your Square application in the Developer Console or set the Developer Console to Sandbox mode and then copy a Sandbox location ID.

Link to section

1. Create or search for catalog item variations to track

Building and maintaining an inventory amounts to specifying a quantity of stock for selected product item variations in the item library. For new products, you must first create the corresponding item variations (of the CatalogItemVariation type) before setting stock quantities in inventory. To create item variations, call the UpsertCatalogObject endpoint of the Catalog API. For existing item variations, you must first get the IDs of the item variations. To do so, call the SearchCatalogItems endpoint of the Catalog API.

The following cURL example calls the SearchCatalogItems endpoint of the Catalog API to find previously created item variations representing Medium sized shirts:

Link to section

Request: Search for item variations to track in inventory

Search catalog items

If the item variations exist, the successful response similar to the following is returned.

Link to section

Response: Search for item variations to track in inventory

The SearchCatalogItems request returns items containing matched item variations.

{
  "items": [
    {
      "type": "ITEM",
      "id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
      "updated_at": "2020-10-17T00:08:15.13Z",
      "version": 1602893295130,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Shirt",
        "description": "Shirt",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "F3P54C436KUEUGMRCUFYBEIZ",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Small red shirt",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "IJBAQDICELYUAUTHM352X3AI",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Medium red shirt",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "5JMHD2SBPVG3A7ZFN5HDXSY6",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Large red shirt",
              "ordinal": 2,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "FQZGFI5ZQZY4RYK3H5X3QG2X",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Small blue shirt",
              "ordinal": 3,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "6F4K33KPNUVDWKZ43KUIFH6K",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Medium blue shirt",
              "ordinal": 4,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "H6QGZ6Q3XBEIL672DZYQW5SH",
            "updated_at": "2020-10-17T00:08:15.13Z",
            "version": 1602893295130,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
              "name": "Large blue shirt",
              "ordinal": 5,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              }
            }
          }
        ],
        "product_type": "REGULAR"
      }
    }
  ],
  "matched_variation_ids": [
    "IJBAQDICELYUAUTHM352X3AI",
    "6F4K33KPNUVDWKZ43KUIFH6K"
  ]
}

Notice that the previous example result includes item variations for Small *, Medium *, and Large * shirts, even though Medium is specified on the text_filter of the request body. This is because they're part of the item containing the Medium * variations, as their sibling item variations.

However, the matched_variation_ids at the end of the response body refers to only the item variations for Medium * shirts, namely, the Medium blue shirt item variation ID is 6F4K33KPNUVDWKZ43KUIFH6K, whereas the Medium red shirt item variation ID is IJBAQDICELYUAUTHM352X3AI.

Make note of the matched item variation IDs. You need them to set their inventory counts or to track their stock levels next.

Link to section

2. Increase the inventory amount of an item variation

After receiving 100 medium-sized blue shirts at one seller location, the seller or one of the staff members can proceed to add stock for the item variation to account for the inventory. Using the Inventory API, this amounts to calling the BatchChangeInventory endpoint, while specifying the quantity of the item variation in a specified location and changing the inventory state from NONE to IN_STOCK.

Link to section

Request: Increase the inventory amount of an item variation

Batch change inventory

You must specify the ID of the CatalogItemVariation object on the catalog_object_id attribute to reference the desired product. The location_id and occurred_at values are also required.

Link to section

Response: Increase the inventory amount of an item variation

When the previous request is successful, a response similar to the following is returned:

{
  "counts": [
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "100",
      "calculated_at": "2020-12-18T21:10:34.12189Z"
    }
  ]
}

The inventory now shows 100 IN_STOCK units of the product item variation referenced by 6F4K33KPNUVDWKZ43KUIFH6K at the location identified by EF6D9SACKWBKZ.

Link to section

3. Update the inventory to account for damaged product items

On further inspection, the seller might find that two shirts they received were damaged.To track these two items, the seller must register the two shirts as damaged and deduct them from the IN_STOCK quantity.

Using the Inventory API, this can be accomplished by calling the BatchChangeInventory endpoint, specifying a quantity of two units of the item variation, and changing their inventory state from IN_STOCK to WASTE.

Link to section

Request: Update the inventory to account for damaged item variations

The following cURL examples shows how to update the inventory to account for two units of damaged item variation (of Medium blue shirt) as unsellable:

Batch change inventory

Link to section

Response: Update the inventory to account for damaged item variations

If the request is successful, a response similar to the following is returned:

{
  "counts": [
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "98",
      "calculated_at": "2020-12-18T21:19:51.12189Z"
    },
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "WASTE",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "2",
      "calculated_at": "2020-12-18T21:19:51.12189Z"
    }
  ]
}

The result shows that the previous 100 IN_STOCK medium blue shirts have been updated to 98 IN_STOCK shirts and 2 WASTE shirts.

Docs

Build and Manage a Simple Inventory

On this page

Overview

Important

Requirements and limitations

1. Create or search for catalog item variations to track

Request: Search for item variations to track in inventory

Response: Search for item variations to track in inventory

2. Increase the inventory amount of an item variation

Request: Increase the inventory amount of an item variation

Response: Increase the inventory amount of an item variation

3. Update the inventory to account for damaged product items

Request: Update the inventory to account for damaged item variations

Response: Update the inventory to account for damaged item variations

On this page