Styxis
Company
Knowledge

Shopify DraftOrderLineItem weight: carrying the unit through the grams migration

A field-name migration is also a unit-contract migration. Normalize the new value and unit together before comparing the business weight.

Shopify DraftOrderLineItem weight: carrying the unit through the grams migration

Replacing a single grams field with a value-unit pair separates copying a number from preserving a weight. Ignoring the new unit can pass a different magnitude to shipping calculations despite a successful field migration. Hand over the raw pair together with its conversion into the business reference unit. [1, 2, 3]

What the primary source establishes

Shopify announced removal of DraftOrderLineItem.grams and directs integrations to weight, which returns both value and unit, from API 2026-07. The new field addresses the single-unit and representation limits of the old grams integer. [1]

The handover decision

Create small draft orders using different units. Convert each explicitly declared unit into the business reference unit and reconcile the weight sent to shipping calculations. Retain weight_value, weight_unit, canonical_grams, and source_grams so a successful renamed query does not conceal a scaling change. [1, 3]

A reference defined before the output

The illustrative weight is 1 kilogram, equivalent to 1000 grams. The normal canonical result is 1000; copying only the new value and interpreting it as 1 gram fails the migration contract. The reference conversion follows the declared units, not the magnitude of the response. [1, 3]

The scoped Truthound check

Truthound Core 3.3.2 can compare canonical_grams after an approved conversion with the reference weight using ColumnPairValidator. Verify the conversion function and interpretation of the source unit earlier. This does not validate shipping charges or the accuracy of a physical scale. [1, 2, 3]

Limits and alternative choices

Unit conversion does not establish actual packaging or measured weight, or the correctness of shipping prices. Declare the business reference unit and retain the original value-unit pair. If a particular contract guarantees only GRAMS from the new API, mixed-unit fixtures are an additional-use experiment. [1, 3]

Application conditions

Prepare both raw value and unit, then independently normalize them to the agreed gram reference for each line item.

Alternatives

Declare the business reference unit and retain the original value-unit pair.

Limitations

  • Unit conversion does not establish actual packaging or measured weight, or the correctness of shipping prices.

Evidence

Event checked
Subject checked
Modified