Applies to: Inventory API | Catalog API
Learn how to enable selling a product in different measurement units with a specified stock conversion.
Basic inventory tracking works when a seller manages products in a single unit, such as a wine store that buys, stocks, and sells whole bottles.
However, businesses that sell items in different units than they stock (such as a restaurant that purchases wine by the bottle but sells it both by the bottle and by the glass) require an inventory system capable of handling unit conversions.
Important
To use stock conversion, you must have a Square for Retail Plus subscription.
In the restaurant example, a bottle is the stocking unit and also a sale unit. On the other hand, a glass is only another sale unit.
The seller needs to set up conversion rates between different units of the same product. For example, if one wine bottle equals five glasses:
- Selling one bottle reduces inventory by 1 bottle (or 5 glasses).
- Selling two glasses reduces inventory by 2/5 of a bottle (or 2 glasses).
The main inventory tracks physical items (bottles), while the sellable inventory (glasses) is calculated using these conversion rates.
Use the Catalog API to create items with item variations in different units of measurement.
The following example shows how to create a Red Wine item in the Catalog API with two variations: Bottles (for stocking and selling) and Glasses (for selling only). The conversion rate is set to 5 glasses per bottle according to the rule stipulated in the stockable_conversion property of the request.
Before creating this configuration, you need:
- A CatalogTax object ID (
KBPWWOXZHOGNOSQ2LIVS4H27), unless your location is tax-free. - A wine category ID (
JXVXTYYDLZRPXMQ7SMNJXVVG). - Two CatalogMeasurementUnit IDs:
- One for bottles (
SQKOHTEZUX2QWIZXMH3Z5WGW) - One for glasses (
DPCQ2HA44EN3EIJT3WEXN5FE)
- One for bottles (
You can create these measurement units separately using UpsertCatalogObject or all at once using BatchUpsertCatalogObjects.
Important
Don't forget to replace the catalog object IDs in the example request with the IDs you create in your test account.
The category of the item, as referenced by {"category_id": "JXVXTYYDLZRPXMQ7SMNJXVVG"}, refers to wine for sale at the seller locations.
Upsert catalog object
Make sure that the two item variations subject to the stock conversion are assigned the same SKU value. Otherwise, you get two separate stockable variations.
In the example, a bottle is the unit of the stockable variation. When the seller takes delivery of bottles of the wine, the quantity must be added to the seller's inventory. The associated inventory state changes from NONE to IN_STOCK.
Note
You can add the stockable variation to the inventory in the item library in the Square Dashboard. Look for Adjust inventory or Manage stock.
To add a delivery of 24 bottles of wine to the inventory, call the BatchChangeInventory endpoint of the Inventory API on the stockable variation (PMUUU2EFXNRBKTUAMTC5SQTZ). This is shown in the following example request:
Batch change inventory
After the wine is in stock, sales can begin. When someone buys a bottle, the system updates the following:
- Reduces bottle inventory by 1
- Reduces available glasses by 5 (because each bottle equals 5 glasses)
The following example request shows a call to the BatchChangeInventory endpoint on the stockable variation (PMUUU2EFXNRBKTUAMTC5SQTZ) to adjust the inventory accordingly:
Batch change inventory
Note
In the Virtual Terminal in the Square Dashboard, the previous request corresponds to taking a payment for one bottle of wine.
In this scenario, a customer orders two glasses of wine. To update the inventory to account for this transaction, call the BatchChangeInventory endpoint on the sellable-only variation (IUD2QMXX4K62W35HW5CVQGL6), specifying the quantity 2.
This is shown in the following example request:
Batch change inventory
Note
In the Virtual Terminal in the Square Dashboard, the previous request corresponds to taking a payment for two glasses of wine.
Adjusting the inventory on the sellable-only variation involves two separate adjustments:
- The inventory adjustment on the stockable variation moves from the
IN_STOCKstate to theCOMPOSEDstate. - The inventory adjustment on the sellable-only variation moves from the
COMPOSEDstate to theSOLDstate.
The two component inventory adjustments are included in an adjustment group that represents a single inventory change event transitioning from a representative from_state of IN_STOCK to a representative to_state of SOLD.
This behavior is different from the inventory change on a stockable variation.