Adding batch details in metafields to Shopify orders

Freshly can save each order's batch details to a Shopify order metafield, so you can use them in Shopify packing slips, notification emails, or send them to a 3PL or ERP. This is available on all paid Freshly plans (not on the free Essential plan).

Turn on order metafields

1. In Freshly, go to Preferences.
2. In Order fulfillment, check Enable inventory batch metafields on customer orders.
3. Click Save.

From then on, Freshly updates the metafield whenever batches on an order change: when batches are assigned automatically, when you assign or unassign them, when the order is edited or refunded, and when batches are assigned through the Freshly API. Orders from before you turned this on aren't updated until their batches change.

What's in the metafield

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

The value is a list, with one entry per batch assigned to the order:

[
  {
    "id": 6016,
    "expiry_date": "2026-03-21",
    "received_date": "2026-03-19",
    "created_at": "2026-03-19T00:49:18Z",
    "location_id": 61234567890,
    "location_name": "Main warehouse",
    "batch_name": "Batch 2026-03-18",
    "batch_number": "L-1042",
    "barcode": null,
    "invoice_number": null,
    "description": null,
    "line_item_id": 13456789012345,
    "quantity": 2,
    "variant_id": 41234567890123,
    "sku": "JAM-250"
  }
]

• location_id , line_item_id  and variant_id  are Shopify IDs.
• quantity  is how many units of that line item come from this batch.
• Dates are YYYY-MM-DD . created_at  is ISO 8601.

See the metafield in Shopify

1. In your Shopify admin, go to Settings > Metafields and metaobjects.
2. Click Orders.
3. Click View unstructured metafields (or More actions > View unstructured metafields). You'll see freshly.inventory_batches  listed.

Shopify advises against adding a definition for metafields an app relies on, since it can stop the app working as expected. Leave this one without a definition.

Read the metafield with the API

Use the Admin GraphQL API. jsonValue  returns the list already parsed. value  returns it as a string you'll need to parse.

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

See Shopify's Order and Metafield reference.

Use it in Shopify templates

• Packing slips: Add batch details to Shopify packing slips using order metafields
• Emails: Displaying batch info in order confirmation emails

If you have questions about metafields or connecting Freshly to other apps, contact us at hello@getfreshly.io.