Line item properties

Use the shared storefront runtime to build Measura-compatible line item properties from Shopify theme code.

Availability

These shared storefront methods are available as long as the Measura shared runtime is loaded.

window.Measura is loaded when at least one Measura app block or app embed is rendered on the page.

Both line item property methods are asynchronous. Theme code should await them.

await window.Measura.buildLineItemProperties({
  productId: 9904458072362,
  productHandle: "sample-product",
  variantId: 50661130010922,
  measurement: {
    dimensions: [{ value: 1, unit: "lb" }]
  }
});

window.Measura.buildLineItemProperties(options)

Builds Measura line item properties for a single line item.

Returns

Promise<Array<{ name: string; value: string }>>

Input

{
  productId: string | number;
  productHandle: string;
  variantId: string | number;
  measurement: {
    dimensions?: Array<{
      value: number | string;
      unit: string;
    }>;
  };
  baseProperties?:
    | Record<string, string | number | boolean>
    | Array<{ name: string; value: string | number | boolean }>;
  includeDataFields?: boolean;
}

Behavior

  • Hydrates the product state from the product page if the product is not already in window.AtomicPOS.
  • Uses the stored product measurement type from Measura product state.
  • Builds visible Measura properties such as localized Unit price and Net weight or Net length.
  • Merges any provided baseProperties.
  • Optionally includes hidden .measura-data-field inputs for the product when includeDataFields is not set to false.
  • Always emits canonical _measura_data.

Returns [] when

  • The product is not a Measura product after hydration.

Throws when

  • productId, productHandle, or variantId is missing.
  • measurement.dimensions[0].value is missing or not a positive number.
  • measurement.dimensions[0].unit is missing.
  • The stored Measura measurement type cannot be resolved.
  • The provided measurement unit does not match the product's stored measurement type.
  • The product state or variant state cannot be hydrated correctly.

Example

const properties = await window.Measura.buildLineItemProperties({
  productId: 9904458072362,
  productHandle: "sample-backpack-4",
  variantId: 50661130010922,
  measurement: {
    dimensions: [{ value: 1, unit: "lb" }]
  },
  baseProperties: {
    Note: "Buy again"
  }
});

Example response:

[
  { name: "Unit price", value: "$12.00 / lb" },
  { name: "Net weight", value: "1 lb" },
  {
    name: "_measura_data",
    value: "{\"properties\":{\"Note\":\"Buy again\"},\"measurement\":{\"type\":\"weight\",\"dimensions\":[{\"unit\":\"lb\",\"value\":1}]}}"
  }
]

window.Measura.buildLineItemPropertiesBulk(items)

Builds Measura line item properties for multiple items.

Returns

Promise<Array<Array<{ name: string; value: string }>>>

Input

Array<{
  productId: string | number;
  productHandle: string;
  variantId: string | number;
  measurement: {
    dimensions?: Array<{
      value: number | string;
      unit: string;
    }>;
  };
  baseProperties?:
    | Record<string, string | number | boolean>
    | Array<{ name: string; value: string | number | boolean }>;
  includeDataFields?: boolean;
}>

Behavior

  • Returns results in the same order as the input array.
  • Processes items in batches of 5 at a time.
  • Reuses the same underlying single-item builder logic.
  • Returns [] for individual non-Measura products.
  • Throws if items is not an array or if any item fails with an invalid-input or hydration error.

Example

const results = await window.Measura.buildLineItemPropertiesBulk([
  {
    productId: 9904458072362,
    productHandle: "sample-backpack-4",
    variantId: 50661130010922,
    measurement: {
      dimensions: [{ value: 1, unit: "lb" }]
    }
  },
  {
    productId: 1234567890,
    productHandle: "non-measura-product",
    variantId: 987654321,
    measurement: {
      dimensions: [{ value: 1, unit: "lb" }]
    }
  }
]);

In this example

  • results[0] contains the built Measura properties.
  • results[1] is [] if the second product is not Measura-enabled.

Notes

  • measurement.type is not accepted by the public API. Measura uses the stored product measurement type and validates it against the provided dimension unit.
  • productHandle is required on every call so the runtime can hydrate product state when needed.
  • The returned properties are intended to be attached to Shopify cart add requests or forms by theme code.
  • The API does not add items to cart for you. It only builds Measura line item properties.
  • Preset products are supported. If the requested measurement matches a preset value, the preset label is used in the visible net measurement property and the preset index is written into _measura_data.

When to use this:

Use these methods from Shopify theme code. If you are building an external system, mobile app, or custom checkout that cannot access the storefront runtime, follow the cart integration guide instead.