Inventory API

Reconcile Inventory Count with Actual Physical Count

As items are sold and restocked, the quantities are automatically computed to reflect inventory changes. However, the computed quantities of an item variation in a specific inventory state can be out of sync with the physical count at a particular location. When this happens, you can reconcile the difference by overriding the computed quantity with the physical quantity.

To reconcile the computed quantity with the physical quantity using the Inventory API, call the BatchChangeInventory endpoint to update the inventory by resetting the quantity of a specific item variation in a specific location by a specified physical count or a number as reported by a trusted counting system.

For example, suppose the inventory you built in the Build and Manage a Simple Inventory topic has not been properly updated after a few additional transactions. The reported inventory quantity of the item variation for Medium Blue Shirts (6F4K33KPNUVDWKZ43KUIFH6K) at location EF6D9SACKWBKZ remains at 98 when the physical quantity has reached 95. To sync the inventory count with the actual quantity, the seller must update the inventory with the actual count. To accomplish this using the Inventory API, call BatchChangeInventory while specifying as input an InventoryPhysicalCount object with the quantity of 95. The result will be an adjustment of 3 Medium Blue Shirts with the inventor state changing from IN_STOCK to WASTE because the inventory count was reduced. If the inventory count increased, the adjustment reflects receiving the additional Medium Blue Shirts with the inventory state changing from NONE to IN_STOCK.

Request: Reset an in-stock inventory count Permalink Get a link to this section

The following cURL command shows how to reset the quantity of an item variation (6F4K33KPNUVDWKZ43KUIFH6K) with a specified change in physical_count:

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

Notice that each changes list entry in the request body consists of an InventoryChange object for InventoryPhysicalCount and an InventoryChangeType of PHYSICAL_COUNT.

Response: Reset an in-stock inventory count 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": "95",
      "calculated_at": "2020-12-29T01:30:14.12291Z"
    }
  ]
}

The inventory quantity of the item variation is now reset to 95.