Add inventory batch details to product variant metafields in Shopify

Freshly can save batch details for every batch-tracked variant to a Shopify variant metafield. Use it to show batch information in your theme or pass it to other apps. This option is turned on per store by our team, so contact us at hello@getfreshly.io to request it. It needs a paid Freshly plan

Turn on variant batch metafields

1. In Freshly, go to Preferences.
2. Scroll to Inventory batch metafields.
3. Check Enable inventory batch data in metafields for all batch-tracked product variants. If you don't see this section, contact us to enable it.
4. Click Save.

Freshly starts adding the metafield to your batch-tracked variants right away. After that, it updates a variant when you edit one of its batches, and runs a check every few minutes to catch other changes.

What's in the metafield

• Namespace: freshly
• Key: inventory_batches
• Type: JSON

The value is a list of up to 100 batches for the variant, newest batch first. It includes expired and empty batches. Each batch has:

• id : Freshly batch ID
• batch_name : batch name in Freshly
• batch_number : batch number in Freshly
• barcode : batch barcode in Freshly
• invoice_number : invoice number in Freshly
• description : description in Freshly
• expiry_date : expiry date (YYYY-MM-DD )
• expired_at : date the batch was marked expired and its quantity removed from Shopify, if that happened before the expiry date (YYYY-MM-DD )
• received_date : date received (YYYY-MM-DD )
• created_at : when the batch was created (ISO 8601, for example 2026-01-29T23:18:17Z )
• discounted : whether the batch is discounted (true  or false )
• quantity : units left in the batch
• location_id : Shopify location ID
• variant_id : Shopify variant ID

Empty dates appear as an empty string.

Use it in your theme

In theme Liquid, read JSON metafields with .value . For example, inside a block or section where variant  is available (names vary by theme):

{% assign batches = variant.metafields.freshly.inventory_batches.value %}
{% for batch in batches %}
  {% if batch.quantity > 0 %}
    <p>{{ batch.batch_name }} · Expires {{ batch.expiry_date | date: "%b %d, %Y" }}</p>
  {% endif %}
{% endfor %}

To show only the next expiry date on product pages, see Displaying expiry or best before dates on your storefront.

See it in Shopify

1. In your Shopify admin, go to Settings > Metafields and metaobjects.
2. Click Variants
3. Click View unstructured metafields (or More actions > View unstructured metafields).

Don't add a definition for freshly.inventory_batches . Shopify warns that adding definitions to app metafields can stop the app from working as expected.

Read it with the API

Use the Admin GraphQL API. jsonValue  returns the parsed list.

query {
  productVariant(id: "gid://shopify/ProductVariant/1234567890") {
    metafield(namespace: "freshly", key: "inventory_batches") {
      jsonValue
    }
  }
}

See Shopify's ProductVariant and Metafield reference.