Settings & Metafields

Learn how to configure Shopify metafields to store trading-card product data.

What are Metafields?

Metafields are custom data fields in Shopify that extend product information beyond the default fields (title, price, description). For card 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 Forge 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:

• custom.card_name - The name of the card
• custom.collector_number - Canonical collector/card number, preserved as text (for example, "042", "2026-4", or "A-7")
• custom.set_code - Set code (for example, "MKM")
• custom.set_name - Full set name (for example, "Murders at Karlov Manor")
• custom.rarity - Card rarity
• custom.finish - Card finish (Foil, Nonfoil)
• custom.availability_status - Product availability (for example, pre-sale, in-stock)
• custom.managed_by - Marks the product as LGS Forge-managed; collections and bulk actions key on it

custom.card_number is a legacy Shopify field. LGS Forge can still read it on older products when custom.collector_number is absent, but new and updated syncs write only custom.collector_number.

The legacy value goes stale. LGS Forge no longer writes custom.card_number, and no sync clears it — whatever value a product already has stays frozen at what it was when the product was last synced under the old behavior. If a card's number is later corrected upstream, custom.collector_number updates and custom.card_number keeps the old value with no warning. Point any theme, filter, or integration that reads custom.card_number at custom.collector_number before clearing it.

Clearing the stale values. A one-shot cleanup removes custom.card_number from the products LGS Forge manages in your store. It never touches products you created yourself, and it leaves the metafield definition in place — deleting that stays your call, in Shopify admin.

# Report what would be removed, without changing anything
npm run migrate:legacy-card-number:dry-run -- --shop=your-store.myshopify.com

# Remove them
npm run migrate:legacy-card-number -- --shop=your-store.myshopify.com

The shop is required — the cleanup never guesses a target — and it runs against one store at a time. It is safe to re-run: a second run finds nothing left to remove.

It skips products that still need a re-sync. A product only gets custom.collector_number when its set is synced under the current behavior. Until then custom.card_number is the only number that product has in Shopify, so the cleanup leaves it alone rather than blanking it, and reports how many it skipped:

Would delete custom.card_number from 947 product(s), skipping 2604 that need a re-sync first

To clear those too, re-sync the sets they belong to, then run the cleanup again. Sets synced recently are unaffected — they already carry custom.collector_number.

Optional Metafields

These metafields enhance product data but aren't required:

• custom.booster_game - The card game (e.g., "Magic: The Gathering") — on by default
• custom.year - Set release date — on by default
• custom.card_type - Card types (Creature, Instant, Sorcery, ...) — on by default
• custom.attribute - Card colors (W, U, B, R, G) — on by default
• custom.promo_types - Promo types (Raised Foil, Serialized, Vault, ...) — on by default
• custom.sealed_type - Sealed product type (Booster Box, Booster Pack, Bundle, ...) — on by default
• custom.msrp - Manufacturer's suggested retail price — on by default
• custom.era - Set type/era (expansion, core, ...) — off by default
• custom.artist - Card artist(s) — off by default
• custom.edhrec - EDHREC popularity ranking — off by default
• custom.treatment - Special treatments (Showcase, Extended Art, ...) — off by default

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 Forge creates metafield definitions in your Shopify store:

1. Checks existing metafield definitions
2. Creates missing definitions
3. Configures the custom namespace 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 custom namespace
3. You should see custom.collector_number, custom.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: collector_number is set as number instead of single-line 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 Forge
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 custom namespace metafields
6. Save and publish

Using Liquid Code:

<p>Set: {{ product.metafields.custom.set_name }}</p>
<p>Rarity: {{ product.metafields.custom.rarity }}</p>
<p>Card Number: {{ product.metafields.custom.collector_number }}</p>
<p>Card Type: {{ product.metafields.custom.card_type | join: ', ' }}</p>

Filtering and Sorting

Use metafields to create advanced product filters:

Example: Filter by Rarity

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

Example: Filter by Set

1. Use metafield custom.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 the custom namespace fields you want searchable
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 Forge
4. Sync products again

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

Metafield Data Types

LGS Forge uses specific data types for each metafield:

Metafield	Type	Example
card_name	Single line text	"Cryptic Command"
collector_number	Single line text	"042", "2026-4", or "A-7"
set_code	Single line text	"MKM"
set_name	Single line text	"Murders at Karlov Manor"
rarity	Single line text	"mythic"
finish	Single line text	"foil" or "nonfoil"
availability_status	Single line text	"in-stock"
card_type	List of single line text	"Creature", "Artifact"
attribute	List of single line text	"U", "R"
promo_types	List of single line text	"Raised Foil", "Serialized"
treatment	List of single line text	"Showcase", "Extended Art"
artist	List of single line text	"Rebecca Guay"
year	Date	"2024-02-09"
edhrec	Integer	1250
msrp	Decimal	4.99

Why text for numbers?

• Collector numbers can contain leading zeroes, suffixes, or promo formats
• Text type preserves them exactly; a number type would drop "042" to 42 and reject "A-7"

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 custom and key (for example, collector_number)
   • Set type to Single line text
3. Re-run Setup Metafields in LGS Forge

"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 custom.* metafield definitions
3. Delete them (make sure no other apps depend on them)
4. Re-run Setup Metafields in LGS Forge

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 Forge'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.

Which namespace does LGS Forge use? LGS Forge uses Shopify's custom namespace for product metafields.

What if I already have custom.* metafields from another app? LGS Forge 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 →