Unit Items

Unit items are products that are picked and sold as discrete units—like packaged goods, beverages, and CPGs (consumer packaged goods). This is distinct from items sold by weight; for those, see the weighted_item_info object in the Catalog Management API Reference.

Required Fields

merchant_supplied_item_id is the only field the API requires. Omitting it returns a 400 with Object has missing required properties (["merchant_supplied_item_id"]).

• merchant_supplied_item_id: Required. Must be unique within the business across all stores

Fields Required for Catalog Approval

The fields below are accepted when omitted—the request returns 202 and the item is ingested incomplete—but an item missing them is held at catalog review rather than published. Supply them for every unit item. Requirement levels vary by vertical; see Pass-Through Catalog API Requirements for the table that applies to your categories.

• name: Item name as sold

• images: At least one image

• other_identifiers: The UPC per SKU, using identifier_type: "UPC"

• brand_info: Brand name as sold

• item_categorizations: Category path for browsing and search. Three levels are expected in most verticals and four in some—supply as many as your vertical's requirements table lists

• size: Supply product_specific_size_definition (value and unit of measurement) for every unit item—it is required for merchandising and search. Dimensions are strongly recommended and improve fulfillment accuracy

• product_traits: Omit WEIGHTED for unit items

Field Formats

The following formats are enforced on submission. A value outside the accepted set returns a 400 and the request is not ingested.

• Accepted units of measurement:

  Field	Accepted values
  size.details.weight.unit	lbs, gm, kg, ea, oz
  size.details.dimensions.*.unit	inch, ft, cm, m
  size.details.volume.unit	oz, mL, L

• Accepted other_identifiers[].identifier_type values: UPC, PLU, NSC2, GTIN

• Accepted product_traits values: ALCOHOL, MEDICATION, WEIGHTED

• Category levels are nested, not siblings. sub_category is a recursive field inside category, spelled with an underscore. Supplying sub_category alongside category returns Object instance has properties which are not allowed by the schema: ["sub_category"]

• Integer fields: images[].sort_id and size.pack_size_details.count_per_pack must be integers. A quoted value such as "1" returns Instance type (string) does not match any allowed primitive type (allowed: ["integer"])

• String fields: product_specific_size_definition.value must be a string. An unquoted 1 returns Instance type (integer) does not match any allowed primitive type (allowed: ["string"])

Conventions

These are not enforced at submission—a payload that ignores them returns 202—but they determine how the item is merchandised.

• product_specific_size_definition: value is the numeric size only, description is the unit of measurement—for example "value": "1" with "description": "lb". Do not combine the number and the unit into value

• Values for dimensions, weight, and volume should not exceed two decimal places

Example: Standard Packaged Item

{
  "merchant_supplied_item_id": "item-1024",
  "name": "Organic Multigrain Bread",
  "description": "Freshly baked organic multigrain bread made with whole wheat, oats, and flaxseed.",
  "other_identifiers": [
    {
      "identifier_type": "UPC",
      "identifier_value": "012345678905"
    }
  ],
  "images": [
    {
      "url": "https://cdn.grocerystore.com/images/items/multigrain-bread-front.jpg",
      "sort_id": 0
    }
  ],
  "brand_info": {
    "name": "Grain & Hearth"
  },
  "size": {
    "details": {
      "dimensions": {
        "length": { "value": 11, "unit": "inch" },
        "width": { "value": 5, "unit": "inch" },
        "height": { "value": 4, "unit": "inch" }
      },
      "weight": {
        "value": 1,
        "unit": "lbs"
      },
      "product_specific_size_definition": {
        "value": "1",
        "description": "lb"
      }
    }
  },
  "item_categorizations": [
    {
      "category": {
        "name": "Bakery",
        "sub_category": {
          "name": "Bread",
          "sub_category": {
            "name": "Sliced Bread"
          }
        }
      }
    }
  ]
}

Example: Multi-Pack Item

{
  "merchant_supplied_item_id": "item-2048",
  "name": "Sparkling Water - Lime, 12 pk",
  "other_identifiers": [
    {
      "identifier_type": "UPC",
      "identifier_value": "098765432109"
    }
  ],
  "images": [
    {
      "url": "https://cdn.grocerystore.com/images/items/sparkling-lime-12pk.jpg",
      "sort_id": 0
    }
  ],
  "brand_info": {
    "name": "Clearwell"
  },
  "size": {
    "details": {
      "product_specific_size_definition": {
        "value": "144",
        "description": "fl oz"
      }
    },
    "pack_size_details": {
      "count_per_pack": 12,
      "per_item_size_details": {
        "volume": { "value": 12, "unit": "oz" },
        "product_specific_size_definition": {
          "value": "12",
          "description": "fl oz"
        }
      }
    }
  },
  "item_categorizations": [
    {
      "category": {
        "name": "Beverages",
        "sub_category": {
          "name": "Water",
          "sub_category": {
            "name": "Sparkling Water"
          }
        }
      }
    }
  ]
}

Notes

• Prepackaged fixed-weight items: Omit "WEIGHTED" from product_traits and do not include weighted_item_info. Set their static weight in the size object only.

• Multi-pack items: Use pack_size_details and, if each pack component has size/weight, use per_item_size_details. Omit pack_size_details for single units.

• Completeness is not enforced by the API. Apart from merchant_supplied_item_id, none of the catalog-approval fields are rejected when missing—the request returns 202 and the item is ingested incomplete. Only the formats above fail at submission, so validate your payloads against this page before you send them.