Settings & Metafields

Learn how to configure Shopify metafields to store MTG-specific product data.

What are Metafields?

Metafields are custom data fields in Shopify that extend product information beyond the default fields (title, price, description). For MTG products, metafields store:

• Card number
• Set code and name
• Rarity (Common, Uncommon, Rare, Mythic)
• Mana cost
• Card type (Creature, Instant, Sorcery, etc.)
• Power and toughness
• Finish (Foil, Nonfoil, Etched)

This data is crucial for accurate product listings and can be displayed on your storefront.

Why Metafields are Required

LGS Ledger cannot sync products without metafields being set up first. Metafields ensure:

1. Data integrity - MTG-specific attributes are stored correctly
2. Searchability - Customers can filter by rarity, set, etc.
3. Compatibility - Works with Shopify's native metafield system
4. Future-proofing - Enables advanced features (filtering, sorting, analytics)

Required vs Optional Metafields

Required Metafields

These metafields must be set up before syncing:

• mtg.card_number - Collector number (e.g., "042")
• mtg.set_code - 3-letter set code (e.g., "MKM")
• mtg.set_name - Full set name (e.g., "Murders at Karlov Manor")
• mtg.rarity - Card rarity (common, uncommon, rare, mythic)
• mtg.finish - Foil or nonfoil

Optional Metafields

These metafields enhance product data but aren't required:

• mtg.mana_cost - Mana cost (e.g., "{2}{U}{U}")
• mtg.type - Card type (e.g., "Creature - Human Wizard")
• mtg.power - Creature power (e.g., "3")
• mtg.toughness - Creature toughness (e.g., "4")
• mtg.colors - Card colors (e.g., "Blue, Red")
• mtg.keywords - Abilities (e.g., "Flying, Haste")

You can enable or disable optional metafields based on your needs.

Setting Up Metafields

First-Time Setup

1. Go to the Settings tab

2. Find Metafield Setup section

3. You'll see the current status:

   • Not Setup (Red) - Metafields haven't been created
   • Partial Setup (Yellow) - Some metafields are missing
   • Complete (Green) - All required metafields exist
   • Out of Sync (Orange) - Metafield types don't match expected

4. Click Setup Metafields button

5. Wait 10-30 seconds for the setup to complete

6. Status changes to Complete with a green checkmark

What Happens During Setup

LGS Ledger creates metafield definitions in your Shopify store:

1. Checks existing metafield definitions
2. Creates missing definitions
3. Configures namespace (mtg) and keys
4. Sets correct data types (text, number, boolean)
5. Marks required fields as mandatory
6. Enables storefront visibility (optional fields)

Verifying Setup

After setup completes:

1. Status badge shows Complete
2. All required metafields show checkmarks
3. You can now sync products

To verify in Shopify Admin:

1. Go to Settings → Custom data → Products
2. Look for metafield definitions under the mtg namespace
3. You should see mtg.card_number, mtg.set_code, etc.

Configuring Optional Metafields

After initial setup, you can customize which optional metafields are used:

Enabling Optional Metafields

1. In Metafield Setup, scroll to the optional metafields list

2. Each optional field has a toggle switch

3. Enable the fields you want to use:

   • Mana Cost - For displaying mana symbols on product pages
   • Type - Show card type (useful for filtering)
   • Power/Toughness - Essential for creature cards
   • Colors - For color-based filtering
   • Keywords - Highlight special abilities

4. Click Save Configuration

Disabling Optional Metafields

To disable optional metafields:

1. Toggle OFF the fields you don't need
2. Click Save Configuration
3. Future syncs won't populate those fields

Note: Disabling a field doesn't delete existing data from already-synced products. It only affects future syncs.

Metafield Status Indicators

Complete (Green)

• All required metafields exist
• Metafield types match expected configuration
• Ready to sync products

Not Setup (Red)

• No metafields have been created
• Click Setup Metafields to create them
• Cannot sync until setup is complete

Partial Setup (Yellow)

• Some required metafields are missing
• Check the list to see which fields are missing
• Click Re-run Setup to create missing fields

Out of Sync (Orange)

• Metafield definitions exist but have wrong data types
• Example: card_number is set as number instead of text
• Click Re-run Setup to fix type mismatches

Why does this happen?

• You manually created metafields with different types
• A different app created conflicting metafields
• Shopify changed metafield definitions

How to fix it:

1. Delete conflicting metafield definitions in Shopify Admin
2. Re-run Setup Metafields in LGS Ledger
3. Verify status shows Complete

Using Metafields in Your Store

Displaying Metafields on Product Pages

Metafields can be shown on product pages using Shopify themes:

Using Theme Customizer:

1. Go to Shopify Admin → Online Store → Themes
2. Click Customize on your active theme
3. Navigate to a product page
4. Add a Custom Liquid or Metafield block
5. Select the mtg namespace metafields
6. Save and publish

Using Liquid Code:

<p>Set: {{ product.metafields.mtg.set_name }}</p>
<p>Rarity: {{ product.metafields.mtg.rarity }}</p>
<p>Card Number: {{ product.metafields.mtg.card_number }}</p>
<p>Mana Cost: {{ product.metafields.mtg.mana_cost }}</p>

Filtering and Sorting

Use metafields to create advanced product filters:

Example: Filter by Rarity

1. Create a collection with filters
2. Use metafield mtg.rarity
3. Show only "mythic" cards

Example: Filter by Set

1. Use metafield mtg.set_code
2. Filter for "MKM" to show only Murders at Karlov Manor

Search and Discovery

Shopify search can index metafield values:

1. Go to Shopify Admin → Settings → Apps and sales channels → Search
2. Enable metafield indexing for mtg namespace fields
3. Customers can search by set name, card number, etc.

Updating Metafield Configuration

Adding New Optional Fields

To enable additional optional metafields after syncing products:

1. Enable the new optional fields in Metafield Setup
2. Save configuration
3. Run a Force Re-sync on your sets
4. New fields will be populated on existing products

Changing Required Fields

You cannot modify required fields without re-syncing all products.

If you must change required fields:

1. Delete all synced products (use Delete All Products)
2. Update metafield definitions manually in Shopify Admin
3. Re-run Setup Metafields in LGS Ledger
4. Sync products again

Warning: This is a destructive operation. Backup your store first.

Metafield Data Types

LGS Ledger uses specific data types for each metafield:

Metafield	Type	Example
card_number	Single line text	"042"
set_code	Single line text	"MKM"
set_name	Single line text	"Murders at Karlov Manor"
rarity	Single line text	"mythic"
mana_cost	Single line text	"{2}{U}{U}"
type	Multi-line text	"Legendary Creature - Human Detective"
power	Single line text	"3"
toughness	Single line text	"4"
finish	Single line text	"foil" or "nonfoil"
colors	Multi-line text	"Blue, White"
keywords	Multi-line text	"Flying, Vigilance, Ward"

Why text for numbers?

• Card numbers like "042a" or "★123" aren't pure numbers
• Power/toughness can be "*" or "X"
• Text type handles all cases

Troubleshooting

"Metafields not set up" error when syncing

Problem: You tried to sync without setting up metafields.

Solution:

1. Go to Settings → Metafield Setup
2. Click Setup Metafields
3. Wait for completion
4. Try syncing again

"Partial Setup" status won't clear

Problem: Some metafields are missing even after running setup.

Solution:

1. Check the metafield list to see which are missing
2. Manually create missing definitions in Shopify Admin:
   • Settings → Custom data → Products
   • Add definition → Enter namespace mtg and key (e.g., card_number)
   • Set type to Single line text
3. Re-run Setup Metafields in LGS Ledger

"Out of Sync" status

Problem: Metafield types don't match expected configuration.

Solution:

1. Go to Shopify Admin → Settings → Custom data → Products
2. Find conflicting mtg.* metafield definitions
3. Delete them (make sure no other apps depend on them)
4. Re-run Setup Metafields in LGS Ledger

Metafields not showing on product pages

Problem: Metafields exist but aren't visible on the storefront.

Solution:

1. Check if metafields are set to "Storefront visible"
2. In Shopify Admin → Settings → Custom data → Products
3. Edit each metafield definition
4. Enable Storefront access
5. Update your theme to display metafields (see Using Metafields in Your Store)

Setup button is disabled

Problem: Setup Metafields button is grayed out.

Reasons:

• Setup is already in progress
• Status is already Complete
• You don't have required permissions

Solution:

• Wait a few seconds if setup is in progress
• If status is Complete, no action needed
• Verify you're logged in with admin permissions

Best Practices

Initial Setup

1. Setup metafields before your first sync - Required
2. Enable all optional fields initially - You can disable later
3. Verify status shows Complete - Don't skip this step
4. Test with a small sync - Ensure metafields populate correctly

Ongoing Maintenance

1. Don't manually edit metafield definitions - Use LGS Ledger's setup tool
2. Re-run setup after Shopify updates - If status changes to Out of Sync
3. Enable optional fields before syncing - Easier than re-syncing later
4. Check metafield data occasionally - Verify data is populating correctly

Theme Integration

1. Display key metafields on product pages - Set name, rarity, card number
2. Use metafields in search - Enable indexing for better discovery
3. Create filtered collections - Group by set, rarity, color
4. Show mana cost with symbols - Use custom Liquid or apps for mana symbols

Common Questions

Do I need to set up metafields for each store? Yes, metafield definitions are per-store. If you manage multiple stores, run setup for each one.

Can I use custom namespace instead of mtg? Not currently. LGS Ledger uses the mtg namespace for all metafields.

What if I already have mtg.* metafields from another app? LGS Ledger will use existing definitions if types match. If types don't match, you'll see "Out of Sync" status.

Do metafields affect my Shopify plan limits? No. Metafields don't count toward product limits or resource usage.

Can I export metafield data? Yes. Use Shopify's CSV export or GraphQL API to export products with metafields.

---

Previous: Pricing Configuration ← | Next: Multi-Store Management →