Weighted Items

Weighted items are sold by weight, either because the customer selects a count (for example, bananas) but is charged by actual weight, or because the customer selects a weight directly (for example, deli meat). An item is weighted when WEIGHTED is present in product_traits and the weighted_item_info object describes how it is measured, shopped, and priced. A prepackaged item whose weight varies pack to pack is still a weighted item — see Measured by each, sold by weight.

For items sold as discrete units, see Unit Items.

Where Pricing Is Set

Prices are never set on the catalog item. Every field in weighted_item_info names a unit, not an amount. The amount is a separate request to the Inventory API, per store:

Request	Endpoint	Carries
Catalog	POST /marketplace/api/v2/items	product_traits, weighted_item_info — how the item is measured, shopped, and priced by
Inventory and pricing	POST /marketplace/api/v2/stores/{store_location_id}/items	price_info — the actual amount, in cents

Each item type below shows both requests. Inventory API price fields for weighted items:

Parameter Name	Type	Description
base_price_per_measurement_unit	integer	Price in cents per measurement unit, for example 69 for $0.69 per the unit named in price_by_measurement_unit
sale_price_per_measurement_unit	integer	Promotional price in cents per measurement unit
loyalty_price_per_measurement_unit	integer	Loyalty price in cents per measurement unit

All values are integers in cents; a decimal such as 4.50 returns Instance type (number) does not match any allowed primitive type (allowed: ["integer"]). For a weighted item, use the per-measurement-unit fields rather than base_price — see Inventory and Pricing Reference.

Item Types

Four setups cover how retail items are picked, sold, and priced. The first is not a weighted item and is included for contrast — everything after it is. Each setup determines the purchase_type DoorDash sends on the order line item, and what the customer sees on the storefront. See Support Weighted Items via Merchant Pick for the order-side contract.

Picked and sold by each

Not a weighted item. The customer buys a discrete unit at a fixed price. purchase_type: UNIT.

Omit WEIGHTED and omit weighted_item_info.

Catalog API — POST /marketplace/api/v2/items

{
  "merchant_supplied_item_id": "item-milk-001",
  "name": "Whole Milk",
  "product_traits": [],
  "size": {
    "details": {
      "product_specific_size_definition": {
        "value": "1",
        "description": "gal"
      }
    }
  }
}

Inventory API — POST /marketplace/api/v2/stores/{store_location_id}/items

{
  "merchant_supplied_item_id": "item-milk-001",
  "item_availability": "ACTIVE",
  "price_info": {
    "base_price": 299
  }
}

base_price is the amount the customer pays for one unit — 299 renders as $2.99.

Picked by each, sold by weight

The customer selects a count, and is charged by the weight actually picked — loose produce is the common case. purchase_type: UNIT_TO_MEASUREMENT.

Catalog API — POST /marketplace/api/v2/items

{
  "merchant_supplied_item_id": "item-banana-001",
  "name": "Banana",
  "product_traits": ["WEIGHTED"],
  "weighted_item_info": {
    "average_weight_per_each": 0.5,
    "average_weight_measurement_unit": "lb",
    "price_by_measurement_unit": "lb"
  }
}

Inventory API — POST /marketplace/api/v2/stores/{store_location_id}/items

{
  "merchant_supplied_item_id": "item-banana-001",
  "item_availability": "ACTIVE",
  "price_info": {
    "base_price_per_measurement_unit": 69
  }
}

base_price_per_measurement_unit is $0.69/lb. The storefront multiplies it by average_weight_per_each for the per-each estimate: 0.5 lb at $0.69/lb displays as $0.35/ea. An inaccurate average_weight_per_each makes that estimate wrong.

Measured by each, sold by weight

Prepackaged items whose weight varies pack to pack — a value pack of steak, a whole fish. The customer buys one package and is charged by its actual weight, so this is still a weighted item. purchase_type: UNIT_TO_MEASUREMENT.

Catalog API — POST /marketplace/api/v2/items

{
  "merchant_supplied_item_id": "item-steak-vp-001",
  "name": "Beef Eye of Round Steak USDA Choice Value Pack",
  "product_traits": ["WEIGHTED"],
  "weighted_item_info": {
    "average_weight_per_each": 2.0,
    "average_weight_measurement_unit": "lb",
    "price_by_measurement_unit": "lb"
  }
}

Inventory API — POST /marketplace/api/v2/stores/{store_location_id}/items

{
  "merchant_supplied_item_id": "item-steak-vp-001",
  "item_availability": "ACTIVE",
  "price_info": {
    "base_price_per_measurement_unit": 899
  }
}

base_price_per_measurement_unit is $8.99/lb. The storefront shows the estimated total for the average weight: Est $17.98 • 2.0 lb.

Either omit shop_by_measurement_unit for this type or set it to ea. Do not send an empty string — "" is not a member of the enum and returns a 400.

Measured by weight, sold by weight

The customer selects a weight and is charged for the weight cut — deli and meat service counters. purchase_type: MEASUREMENT.

Catalog API — POST /marketplace/api/v2/items

{
  "merchant_supplied_item_id": "item-deli-turkey-001",
  "name": "Dietz & Watson Fully Cooked Oven Roasted Sliced Turkey Breast",
  "product_traits": ["WEIGHTED"],
  "weighted_item_info": {
    "average_weight_per_each": 1.0,
    "average_weight_measurement_unit": "lb",
    "shop_by_measurement_unit": "lb",
    "price_by_measurement_unit": "lb"
  },
  "product_attributes": [
    {
      "attribute_name": "service_counter",
      "attribute_value": {
        "single_select_bool": true
      }
    }
  ]
}

Inventory API — POST /marketplace/api/v2/stores/{store_location_id}/items

{
  "merchant_supplied_item_id": "item-deli-turkey-001",
  "item_availability": "ACTIVE",
  "price_info": {
    "base_price_per_measurement_unit": 1399
  }
}

base_price_per_measurement_unit is $13.99/lb. Because shop_by_measurement_unit is lb, the storefront shows Sold by weight rather than a per-each estimate.

Setting shop_by_measurement_unit to lb is what makes the customer shop in pounds rather than in units — the storefront shows Sold by weight instead of a per-each estimate. Add the service_counter attribute for items cut to order behind a counter.

Summary

Setup	product_traits	shop_by_measurement_unit	Priced with (Inventory API)	purchase_type
Picked and sold by each	[]	—	base_price	UNIT
Picked by each, sold by weight	["WEIGHTED"]	omit	base_price_per_measurement_unit	UNIT_TO_MEASUREMENT
Measured by each, sold by weight	["WEIGHTED"]	omit or ea	base_price_per_measurement_unit	UNIT_TO_MEASUREMENT
Measured by weight, sold by weight	["WEIGHTED"]	lb (or the unit you sell in)	base_price_per_measurement_unit	MEASUREMENT

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"]).

Nothing enforces the pairing of WEIGHTED with weighted_item_info: product_traits: ["WEIGHTED"] with no weighted_item_info, and weighted_item_info: {} with every field omitted, are both accepted and return 202.

Fields Required for Catalog Approval

Supply these for every weighted item. They 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. Requirement levels vary by vertical; see Pass-Through Catalog API Requirements for the table that applies to your categories.

• product_traits: Must include WEIGHTED

• weighted_item_info: All four fields, described below

• name: Item name as sold

• images: At least one image

• other_identifiers: The UPC per SKU, or the PLU for loose produce

• brand_info: Brand name as sold, where the item has one

• item_categorizations: Category path for browsing and search. Three levels are expected in most verticals and four in some

• size: Optional for weighted items, but per-unit dimensions help cart estimation

weighted_item_info Object

All four fields are units or numbers. No price belongs in this object — per-unit pricing is set through the Inventory API, described below.

Parameter Name	Type	Required	Description	Accepted Values
average_weight_per_each	number	For approval	Estimated average weight of a single unit, for example 0.5 for a banana	Number; a quoted "0.5" is rejected
average_weight_measurement_unit	string	For approval	The unit average_weight_per_each is expressed in. Defaults to ea when omitted, so set it explicitly for any item measured by weight	ea, kg, lb, gm, oz
shop_by_measurement_unit	string	For approval	Unit displayed to the customer for price and selection	kg, lb, gm, oz, ea
price_by_measurement_unit	string	For approval	The unit the item is priced by. This is the unit, not the price	kg, lb, gm, oz, ea

Values are case-sensitive and must match the enum exactly. each in place of ea returns a 400 with Instance value ("each") not found in enum (possible values: ["kg","lb","gm","oz","ea"]).

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
  weighted_item_info.average_weight_measurement_unit	ea, kg, lb, gm, oz
  weighted_item_info.shop_by_measurement_unit	kg, lb, gm, oz, ea
  weighted_item_info.price_by_measurement_unit	kg, lb, gm, oz, ea
  size.details.weight.unit	lbs, gm, kg, ea, oz
  size.details.dimensions.*.unit	inch, ft, cm, m
  size.details.volume.unit	oz, mL, L — capital L in both; ml, ML, l, and OZ are all rejected

• Omit a unit rather than blanking it. An empty string returns Instance value ("") not found in enum (possible values: ["kg","lb","gm","oz","ea"]). There is no blank member in any of these enums

• lb and lbs are not interchangeable. lb is valid in weighted_item_info and invalid in size.details.weight, which takes lbs. Sending lb there returns Instance value ("lb") not found in enum (possible values: ["lbs","gm","kg","ea","oz"])

• 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. 6.5 returns Instance type (number) does not match any allowed primitive type (allowed: ["integer"])

Conventions

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

• average_weight_measurement_unit describes a weight. Leaving it at its ea default states that the average weight of one banana is "0.5 each," which carries no weight information. Set it to the weight unit you measured in

• product_specific_size_definition: value is the numeric size only, description is the unit of measurement — for example "value": "1" with "description": "lb"

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

Notes

• Prepackaged items: A pack whose weight varies pack to pack is weighted — set WEIGHTED and weighted_item_info, and price it per unit of measure. Only an item sold at one fixed price per package is non-weighted; set its static weight in size.details.weight.

• Multi-pack items: Use pack_size_details and, where each pack component has its own size or weight, 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.