MeasuraData

Object

The MeasuraData object is the canonical measurement payload stored as a JSON string in the _measura_data hidden cart line-item property.

Fields

Field	Type	Description
`measurement`	object	Authoritative measurement payload for the line item.
`measurement.type`	MeasurementType	Measurement domain (weight, length, area, volume, or time).
`measurement.dimensions`	array of object	Measurement dimensions. The first entry is treated as the primary dimension.
`measurement.dimensions[].unit`	MeasurementUnit	Measurement unit label (for example kg, m, L).
`measurement.dimensions[].value`	number	Measured value for the dimension. Must be positive.
`unitMeasurement`	Measurement \| undefined	Optional base unit context used for unit-aware pricing, inventory, or shipping flows.
`properties`	Record<string, string> \| undefined	Optional display-facing line item properties (for example net measurement labels).
`price`	number \| undefined	Optional explicit/override line-item price.
`presetIndex`	number \| undefined	Optional preset index when the chosen measurement came from a preset list.
`unitPrice`	string \| undefined	Optional formatted unit-price text for display use.
`itemId`	string \| undefined	Optional client-side identifier for measured item flows.

Note

The cart property value for _measura_data must be a JSON string containing this object.

New integrations should always populate measurement.type and measurement.dimensions[0] (unit + value).

When updating existing payloads, preserve unknown fields unless there is an explicit reason to remove them.

This object is used in the _measura_data hidden cart property. See the Cart integration guide for end-to-end payload assembly and Shopify cart examples.

Example structure

Example MeasuraData payload before stringifying into _measura_data:

{
  "measurement": {
    "type": "weight",
    "dimensions": [
      { "unit": "lb", "value": 1.25 }
    ]
  },
  "unitMeasurement": { "unit": "lb", "value": 1 },
  "properties": {
    "Unit price": "$12.00 / lb",
    "Net weight": "1.25 lb"
  },
  "price": 15,
  "presetIndex": 0,
  "unitPrice": "$12.00 / lb",
  "itemId": "example-item-id"
}