Support for weight-based and unit-of-measure quantities in line items

[poojithg14]

Problem

The current line_item.json schema defines quantity as an integer with a minimum of 1, and item.json defines price as a fixed unit price. This works for discrete products (1 shirt, 2 phones) but doesn't support products sold by weight or other units of measure, which is a fundamental requirement for grocery, deli, bulk goods, and hardware.

Examples that can't be represented today:

• 2.5 lbs of chicken breast at $8.99/lb
• 0.75 kg of cheddar cheese at $12.00/kg
• 3.2 meters of fabric at $15.00/m
• 1.5 liters of olive oil at $10.00/L

This is relevant given that Kroger, Walmart, and Carrefour, all with significant grocery operations, are UCP partners.

Current Schema Limitation

In line_item.json, quantity is defined as an integer so it cannot express something like 2.5 lbs. In item.json, price is a flat integer with no unit context, so there is no way to indicate whether the price is per lb, per kg, or per each.

Possible Approaches

Option A: Extend item and line_item schemas directly

Add optional fields to the existing schemas. For example, a price_unit field on item.json indicating the unit of measure for pricing (open string with well-known values like each, lb, kg, oz, g, l, ml, m, ft, yd, defaulting to each). And on line_item.json, a measured_quantity field (number type instead of integer) along with a measured_unit field for weight/measure-based items.

Option B: Extension schema (non-breaking)

Create a dev.ucp.shopping.weighted_items extension following the discount/fee pattern, keeping the base schemas untouched.

Option C: Vendor extension first

A vendor ships this under their own namespace (for example com.kroger.weighted_items) to validate the design before proposing it as a dev.ucp capability.

Use Cases

1. Grocery checkout - Agent adds "2 lbs of ground beef" to cart, business returns price based on weight
2. Deli counter - Final weight differs from estimated weight, totals update accordingly
3. Bulk goods - Hardware store sells rope by the foot, nails by the pound
4. Produce - Agent orders "3 bananas" (each) vs "1 kg of apples" (weight) in the same cart
5. Estimated vs actual weight - Customer orders 10 tomatoes, estimated at 1 lb at checkout, but the actual picked weight turns out to be 0.9 lb. The final charge should reflect the real weight, not the estimate. This means the protocol needs a way to distinguish between estimated quantity/weight at checkout time and the actual quantity/weight at fulfillment time, and the order total needs to adjust accordingly. This is standard behavior for every grocery delivery service today (Instacart, Walmart Grocery, etc.).

Questions for the Community

• Is this something other partners are running into?
• Should this be a core schema change (Option A) or an extension (Option B)?
• Are there additional unit-of-measure considerations for global markets?

[Nolpak14]

Excellent write-up. This is a foundational gap — you can't represent a grocery cart with the current schema, and with Kroger, Walmart, and Carrefour as UCP partners, this will become a blocker fast. Worth noting ACP has the same limitation (LineItem.quantity is integer there too — their WeightInfo field is for shipping logistics, not purchase quantities).

I've looked at how the major commerce standards handle this, and there's strong convergence on a pattern:

Industry precedent:

Standard	Approach	Unit vocabulary
Schema.org	UnitPriceSpecification with referenceQuantity (QuantitativeValue)	UN/CEFACT Rec 20 codes (KGM, LBR, OZA)
GS1	Measurement fields on trade items; also a Schema.org extension	UN/CEFACT Rec 20 (same)
Google Merchant Center	unit_pricing_measure + unit_pricing_base_measure	Short lowercase: kg, lb, oz, g, ml, l, etc. Mandatory in EU/UK for grocery
Shopify	UnitPriceMeasurement on ProductVariant	Uppercase short: KG, LB, OZ, G, ML, L + measuredType enum (WEIGHT, VOLUME, LENGTH, AREA)

The key design principle from both Schema.org and Shopify: separate "what you buy" from "how it's priced." Shopify's model makes this explicit — quantityValue + quantityUnit (what's in the package: 500g) vs. referenceUnit + referenceValue (how price is displayed: per 1 KG). This lets a 500g bag of rice at $3.99 show as "$7.98/kg" to the consumer (or agent).

On the three options:

I'd go with Option B (extension), for three concrete reasons:

1. Cascading breakage with Option A. quantity: integer is load-bearing across multiple schemas — line_item.json, order_line_item.json ({ total: integer, fulfilled: integer }), fulfillment_event.json (line items with integer quantity), and adjustment.json. Changing the base type cascades through all of them and breaks every existing implementation.

2. The extension pattern is proven. dev.ucp.shopping.discounts and dev.ucp.shopping.fees already augment line items without modifying base schemas, using allOf composition onto checkout.json. A dev.ucp.shopping.measured_items extension (I'd suggest "measured" over "weighted" since this covers volume, length, and area too) would follow the exact same pattern.

3. Option C solves a problem that doesn't exist. The design space is well-explored — Schema.org, GS1, GMC, and Shopify have all converged on essentially the same model. There's no uncertainty that needs a vendor pilot to resolve. Starting with a vendor namespace risks Kroger, Walmart, and Carrefour each building incompatible implementations — the opposite of what a standard should produce.

Suggested extension shape:

Drawing from the Shopify/GMC model:

{
  \"measured_quantity\": {
    \"value\": 2.5,
    \"unit\": \"lb\",
    \"type\": \"weight\"
  },
  \"price_measurement\": {
    \"unit\": \"lb\",
    \"reference_value\": 1
  },
  \"quantity_status\": \"estimated\"
}

• measured_quantity.type follows Shopify's measuredType enum (weight, volume, length, area) — helps agents reason about what kind of measurement they're handling
• unit uses short lowercase codes matching Google Merchant Center (kg, lb, oz, g, ml, l, m, ft) — UCP partners already produce these for their GMC feeds, and they're more agent-readable than UN/CEFACT 3-char codes
• quantity_status: \"estimated\" | \"actual\" addresses your use case Where is the Java adk? #5 (the tomato scenario) without overcomplicating the checkout schema
• Base quantity: integer stays as-is — set to 1 for measured items (meaning "1 unit of this measured product"), preserving backwards compatibility

On use case #5 (estimated → actual):

This is the hardest part and probably deserves its own follow-up discussion. The estimated→actual reconciliation touches the order lifecycle (adjustment.json already has a mechanism for post-order money movements, but no concept of weight-based adjustments) and webhooks (merchants need to notify agents when actual weights are finalized). Every grocery delivery service (Instacart, Amazon Fresh, Walmart Grocery) handles this with a post-checkout adjustment flow. The question is whether UCP should model that in the protocol or leave it to the order management layer. I'd suggest the extension handle the representation (estimated vs. actual flag) and leave the reconciliation flow for a follow-up proposal focused on order.json and adjustment.json.