This article explains how to create and manage metafields — custom fields that attach to products and batches. Metafields are how you surface additional information (lot number, distributor, disclaimer, expiration date, or anything else) to consumers when they authenticate a product and to your team in reports.

Prerequisites

Admin or Editor role.

About Metafields

A metafield is a custom key-value attribute you define once and reuse across products and batches. Metafields live under the Metadata section of the left sidebar — today, Metafields is the only feature in this section, but Metadata is the long-term home for all custom data types you attach to products and batches.

Metafields are associated with a batch during the BatchMaker process. Once associated, they may appear:

On the consumer's authentication page (alongside product information, and inside the Show More digital label)
On the Batch Details screen (in the Attributes panel)
On individual Scan Details screens
In merge-tag syntax for templates (see #{{metafields.keyName}} in Customizing Templates with Advanced Custom CSS)

Typical uses:

Regulatory or compliance fields (control numbers, certifications)
Distributor or retailer name
Destination region
Production disclaimer text
Contact details for that specific batch
Batch Control or Product Lot Identification Purposes
Internal Product IDs and Attributes

Opening the Metafields Page

In the left sidebar, click Metadata under the Management section. The Metafields page opens.
The page displays a list of existing metafields, with columns for Favorite, Key, Type, and List Options.

Reviewing Existing Metafields

Each row shows:

Column	Description
Favorite	Toggle to mark frequently-used metafields. Favorites appear at the top of dropdowns in BatchMaker.
Key	The metafield name. This is the identifier used in merge tags (`#{{metafields.key}}`).
Type	Single Text, Number, True/False, or List
List Options	For List type, the available dropdown values
Actions	Edit or delete the metafield

Creating a New Metafield

On the Metafields page, click Create New Metafield in the top-right corner.
In the Create Metafield modal, fill in:

Field	Details
Key	The metafield name. Keys are case-sensitive and used in merge tags. Use camelCase or lowercase-with-hyphens for consistency (for example, `retailer` or `lot_number`).
Type	See the type table below.
Favorite	Optional. Check to prioritize this metafield in BatchMaker dropdowns.

Click Add Metafield. The metafield is now available in BatchMaker when operators start a new batch.

Metafield Types

Type	When to Use
Single Text	Free-form short strings — distributor name, disclaimer, custom code
Number	Numeric values — a servings count, a lot size, a revision number
True / False	Boolean flags — whether a batch is organic, whether it contains an allergen
List	A dropdown of predefined values — for example, a list of retailers or regions. The BatchMaker operator picks from your list rather than typing free-form.

Tip: Use List type for any field where you want consistent values across batches. Free-form text leads to typos that break reporting and merge tags.

Creating a List Metafield

In the Create Metafield modal, set Type to List.
A list input appears. Type each option and press Enter to add it.
Add as many options as you need — for example, Store One, Store Two, Store Three.
Click Add Metafield to save.

In the BatchMaker app, operators will see a dropdown populated with these exact values.

Using Metafields in Templates

Once a metafield is saved, you can reference its value in your product template or Show More content using the merge-tag syntax:

#{{metafields.keyName}}

For example, if you created a metafield with key retailer, you can display it in Show More as:

<p>Sold at: <strong>#{{metafields.retailer}}</strong></p>

At scan time, the Dashboard replaces #{{metafields.retailer}} with the value that was associated with the scanned tag's batch.

Note: Merge-tag keys are case-sensitive. #{{metafields.retailer}} and #{{metafields.Retailer}} are different — they must match exactly how the key was saved on the Metafields page.

Editing or Deleting a Metafield

On the Metafields page, find the metafield and click the edit icon (pencil) or the delete icon (trash) in the Actions column.
Editing lets you change the type, list options, or favorite status. The key cannot be renamed because existing batches reference it — if you need a different key, create a new metafield and retire the old one.
Deleting removes the metafield for all future batches. Batches that already have the metafield associated retain their values.

Troubleshooting

Issue	Solution
A metafield I created does not appear in BatchMaker	Restart the BatchMaker app to refresh its settings cache. New metafields require a BatchMaker reload to pick up.
My merge tag `#{{metafields.foo}}` renders literally on the authentication page	Check that the key is exactly `foo` (case-sensitive) on the Metafields page, and that the batch was created after the metafield was defined.
I renamed a metafield and my merge tags broke	Keys are immutable. If you need a different key, create a new metafield with the new key, update your templates, and retire the old metafield.
A List metafield only shows one option in BatchMaker	Confirm you pressed Enter after each option when creating the list. Options that were typed but not submitted are discarded on save.
I need to bulk-update metafield values across many batches	Metafield values are set at batch creation time. Existing batches cannot be bulk-updated — create a new batch with the corrected values.