Manage Vendor Information on Item Variations

Applies to: Catalog API | Inventory API | Vendors API

An item variation's vendor_information describes how the seller purchases that product: which vendors supply it, the usual cost per unit, and the product's identifier in each vendor's system. Square uses this information to prefill purchase orders and as the default cost when inventory movements need one - for example, when a physical count increases the in-stock quantity or when an untracked variation with a default cost is sold.

CatalogItemVariation has a repeated vendor_information field. Each entry contains:

Two rules give the list its meaning:

• The first entry is the default. When Square needs a default cost or vendor for the variation (physical count increases, untracked sales with cost tracking, purchase order prefill), it uses the first entry in the list.
• An entry can omit vendor_id. A single cost-only entry supports sellers who track what they pay for a product without tracking a vendor. Use this when the seller isn't tracking vendors for the variation - don't combine a vendorless cost entry with vendor-specific entries.

Write vendor_information as part of the variation in an UpsertCatalogObject (or batch upsert) request:

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2026-07-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "0a3d5bfb-8325-4a7b-8dcc-2f0a4b3b9c66",
    "object": {
      "type": "ITEM_VARIATION",
      "id": "#small-leather-collar",
      "item_variation_data": {
        "item_id": "W62UWFY35CWMTGPTTVGXAMPL",
        "name": "Small",
        "pricing_type": "FIXED_PRICING",
        "price_money": { "amount": 2500, "currency": "USD" },
        "vendor_information": [
          {
            "vendor_id": "5ZW5RVANNKV3B3RB",
            "vendor_code": "LC-SM-0042",
            "unit_cost_money": { "amount": 1050, "currency": "USD" }
          },
          {
            "vendor_id": "V6C8QK4M2WX9YB7R",
            "vendor_code": "8890-SM",
            "unit_cost_money": { "amount": 1200, "currency": "USD" }
          }
        ]
      }
    }
  }'

In this example, the variation can be purchased from two vendors. The first entry is the default: Square uses vendor 5ZW5RVANNKV3B3RB and its $10.50 unit cost when it needs a single default cost or vendor for the variation. The second entry (vendor V6C8QK4M2WX9YB7R at $12.00 per unit) appears on the variation in the Square Dashboard and prefills the unit cost when the seller creates a purchase order for that vendor.

As with other variation fields, the entire vendor_information list is replaced on write. To add or remove an entry, read the variation, modify the list, and upsert it back with the variation's current version.

Vendor information supplies defaults; the actual cost of received stock is recorded on inventory adjustments:

• When your application receives stock with the Inventory API, it can record the actual cost_money and vendor_id on the receiving adjustment. See Track Inventory Costs and Vendors.
• When Square generates stock-increasing adjustments itself (for example, from a physical count), it uses the variation's default cost.