Track Inventory Costs and Vendors

Applies to: Inventory API | Catalog API | Vendors API

Sellers that track what they pay for their stock can answer questions like "What is my inventory worth?" and "What did I pay this vendor last quarter?" The Inventory API lets your application record that information the same way first-party Square products do:

• Record the amount paid (cost_money) and the vendor (vendor_id) when receiving stock.
• Update the quantity, cost, vendor, or reason of a past adjustment with UpdateInventoryAdjustment.

Default costs and vendors for an item variation come from the variation's vendor_information in the catalog. See Manage Vendor Information.

cost_money and vendor_id can be written only on stock-receiving adjustments - adjustments whose from_state is NONE or UNLINKED_RETURN. cost_money is the total amount paid to the vendor for the units in the adjustment, and vendor_id references a vendor managed with the Vendors API.

The following BatchChangeInventory request receives 100 units purchased for $250.00 from a known vendor:

curl https://connect.squareup.com/v2/inventory/changes/batch-create \
  -X POST \
  -H 'Square-Version: 2026-07-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "42c1a557-2b31-4b8b-8ecb-6dcf10ffb2b2",
    "changes": [
      {
        "type": "ADJUSTMENT",
        "adjustment": {
          "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "from_state": "NONE",
          "to_state": "IN_STOCK",
          "from_location_id": "EF6D9SACKWBKZ",
          "to_location_id": "EF6D9SACKWBKZ",
          "quantity": "100",
          "occurred_at": "2026-07-16T14:20:00.000Z",
          "cost_money": { "amount": 25000, "currency": "USD" },
          "vendor_id": "5ZW5RVANNKV3B3RB",
          "reason_id": { "type": "RECEIVED" }
        }
      }
    ]
  }'

Cost and vendor values then appear on the adjustment in change-history responses. Reading these fields doesn't require a subscription; adjustments written without cost information simply omit the fields.

Sellers sometimes need to correct a received quantity, a cost, or a vendor after the fact. UpdateInventoryAdjustment (PUT /v2/inventory/adjustments/update, INVENTORY_WRITE) supports sparse updates of a past adjustment, with the same restrictions that apply in the Square Dashboard:

• quantity must always be provided, but it can be identical to the current quantity if only cost, vendor, or reason changes are desired.
• cost_money and vendor_id can be changed only on adjustments that add stock (from_state of NONE or UNLINKED_RETURN) and on untracked sale adjustments.
• reason_id can be changed to any reason that's valid for the adjustment's state transition. The reason of a system-generated adjustment (such as SALE or RECOUNT) can't be changed. See Inventory Adjustment Reasons.
• Adjustments that Square generates from other records can't be updated: inferred adjustments from physical counts, transfer-like cross-location adjustments, and component adjustments.
• Adjustments linked to purchase orders can't be updated. Adjustments linked to sales can only have cost and vendor updated, and only for untracked sales.
• Restock adjustments linked to an itemized return can have their quantity updated, up to the quantity remaining on the return.
• Adjustments older than 1 year cannot be updated.

curl https://connect.squareup.com/v2/inventory/adjustments/update \
  -X PUT \
  -H 'Square-Version: 2026-07-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "d6f1cf4e-6d90-4a2b-9df7-2f0ab9a78ee1",
    "adjustment": {
      "id": "HA4STFR47RAEORFWXHOYPRG5",
      "quantity": "100",
      "cost_money": { "amount": 27500, "currency": "USD" },
      "vendor_id": "5ZW5RVANNKV3B3RB"
    }
  }'

The endpoint is available only to sellers with an active Square for Retail Plus, Square for Restaurants Plus, or Square for Restaurants Premium subscription.