Inventory API

Build and Manage a Simple Inventory

To learn how to use the Square Inventory API, walk through the basic steps involved in building and managing a simple inventory, including:

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

Prerequisites and assumptions Permalink Get a link to this section

To use the Inventory API, the following must be true:

  • 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 are using Square-Version 2018-09-18 or later.

Additionally, this guide makes the following assumptions:

  • You have read the introductory review of this API.

  • You are familiar with basic web development. If you are new to web development, you should read Getting started with the Web by Mozilla.org before continuing.

Information you need Permalink Get a link to this section

To use the steps in this topic, you need:

  • A valid access token. You should test with Sandbox credentials whenever possible. For more information, see Square API Access Tokens.

  • An active location ID. Copy a developer account location ID from the Locations page of your Square application in the Developer Dashboard or set the Developer Dashboard to Sandbox mode and then copy a Sandbox location ID.

Step 1: Create or search for catalog item variations to track Permalink Get a link to this section

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.

Request: Search for item variations to track in inventory Permalink Get a link to this section

Search Catalog Items
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/catalog/search-catalog-items \
  -X POST \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_types": [
      "REGULAR"
    ],
    "text_filter": "Medium"
  }'

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

Response: Search for item variations to track in inventory Permalink Get a link to this section

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

Step 2: Increase the inventory amount of an item variation Permalink Get a link to this section

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.

Request: Increase the inventory amount of an item variation Permalink Get a link to this section

Batch Change Inventory
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareupsandbox.com/v2/inventory/batch-change \
  -X POST \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "changes": [
      {
        "adjustment": {
          "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "from_state": "NONE",
          "to_state": "IN_STOCK",
          "quantity": "100",
          "location_id": "EF6D9SACKWBKZ",
          "occurred_at": "2020-12-18T21:10:00Z"
        },
        "type": "ADJUSTMENT"
      }
    ]
  }'

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.

Response: Increase the inventory amount of an item variation Permalink Get a link to this section

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.

Step 3: Update the inventory to account for damaged product items Permalink Get a link to this section

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.

Request: Update the inventory to account for damaged item variations Permalink Get a link to this section

This 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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareupsandbox.com/v2/inventory/batch-change \
  -X POST \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "changes": [
      {
        "adjustment": {
          "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "from_state": "IN_STOCK",
          "quantity": "2",
          "to_state": "WASTE",
          "location_id": "EF6D9SACKWBKZ",
          "occurred_at": "2020-12-18T21:19:00Z"
        },
        "type": "ADJUSTMENT"
      }
    ]
  }'

Response: Update the inventory to account for damaged item variations Permalink Get a link to this section

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.