Build and Manage a Simple Inventory

Applies to: Inventory APIInventory API | Catalog APICatalog API

Learn how to manage the stock level of item variations by increasing inventory amounts and changing them for spoiled items.

If you're processing itemized payments with Square APIs or hardware, quantities for item variations with inventory tracking enabled are automatically updated. For other operations that change quantities, you need to apply the adjustment manually.

• You have item variations defined in your Square product catalog. For information about working with the Catalog API, see Add a Catalog ItemAdd a Catalog Item.
• Applications using OAuth must have INVENTORY_READ permission to read inventory information and INVENTORY_WRITE permission to update inventory states.
• You need a valid access token. You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square CredentialsAccess Tokens and Other Square Credentials.

Building and maintaining an inventory amounts to specifying a quantity of stock for selected product item variations in the item library. Before setting inventory amounts, your application needs to create the item variation to track or find the existing item variation that you want to set inventory amounts for.

New products:

1. Use the UpsertCatalogObjectUpsertCatalogObject endpoint to create item variations. For information about adding item variations, see Add a Catalog ItemAdd a Catalog Item.
2. Use BatchChangeInventoryBatchChangeInventory to set their stock levels.

Existing products:

1. Use SearchCatalogItemsSearchCatalogItems to find the variation IDs. For information about searching the catalog, see Search for Items and ObjectsSearch for Items and Objects.
2. Use BatchChangeInventory to update their stock levels.

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

When the seller receives new inventory (such as 100 blue medium shirts at their store), they can update the system using the BatchChangeInventoryBatchChangeInventory endpoint. This call tells the Inventory API to add the items to stock at that location, changing their status from NONE to IN_STOCK.

The seller might find a few of the new shirts to be damaged. To track these items, the seller needs to report the shirts as damaged and deduct them from IN_STOCK inventory.

Call the BatchChangeInventory endpoint, specify a quantity of two units of the shirts, and change their inventory state from IN_STOCK to WASTE.