Metafields Reference

Complete catalog of every Shopify metafield used in UberLotto v2. Organized by scope (product, variant, page, shop) with namespace, key, type, and purpose.

Product-Level Metafields

These metafields are set on individual Shopify products.

Namespace	Key	Full Reference	Type	Required	Description
custom	game_slug	custom.game_slug	Single line text	Yes	Unique slug linking to Supabase data (e.g., powerball)
custom	game_db_name	custom.game_db_name	Single line text	No	Legacy/unused. Stores Supabase game name but is not consumed by application logic. game_slug is the primary identifier.
custom	draw_games_schedule	custom.draw_games_schedule	Single line text	Yes	Drawing days (e.g., Mon, Wed, Sat)
custom	lottery_pool_cutoff_time	custom.lottery_pool_cutoff_time	Single line text	Yes	Entry cutoff in 24h format (e.g., 22:00)
custom	logo_image	custom.logo_image	File reference	No	Custom logo for game cards
custom	lottery_ticket_multiplier	custom.lottery_ticket_multiplier	Single line text	No	Enables multiplier display (true/false)
custom	enable_play_options	custom.enable_play_options	Single line text	No	Enables play options UI (true/false)
custom	disabled_days	custom.disabled_days	JSON	No	Days game is unavailable (e.g., ["Sun"])

GraphQL Query

All product metafields are fetched in app/graphql/game-detail/GameDetailQuery.ts:

product(handle: $handle) {
  gameSlug: metafield(namespace: "custom", key: "game_slug") { value }
  gameDbName: metafield(namespace: "custom", key: "game_db_name") { value }  # Queried but unused
  drawGamesSchedule: metafield(namespace: "custom", key: "draw_games_schedule") { value }
  lotteryPoolCutoffTime: metafield(namespace: "custom", key: "lottery_pool_cutoff_time") { value }
  logoImage: metafield(namespace: "custom", key: "logo_image") {
    reference {
      ... on MediaImage {
        image { url }
      }
    }
  }
  lotteryTicketMultiplier: metafield(namespace: "custom", key: "lottery_ticket_multiplier") { value }
  enablePlayOptions: metafield(namespace: "custom", key: "enable_play_options") { value }
  enabledDays: metafield(namespace: "custom", key: "disabled_days") { value }
}

TIP

The game_slug metafield is the only identifier that connects Shopify products to Supabase data. It replaced an earlier game_type numeric ID system.

Variant-Level Metafields

These metafields are set on individual product variants and control per-variant quantity limits.

Namespace	Key	Full Reference	Type	Status	Description
cart	max_quantity	cart.max_quantity	Integer	Current	Maximum quantity per cart for this variant
limits	max_quantity	limits.max_quantity	Integer	Legacy	Legacy max quantity (fallback only)

Priority Chain

When determining the max quantity for a variant, the system checks in this order:

1. Shopify native quantityRule (highest priority) — Set in variant inventory settings
2. cart.max_quantity metafield — Current namespace
3. limits.max_quantity metafield — Legacy fallback

GraphQL Query

variants(first: 250) {
  nodes {
    quantityRule {
      maximum
      minimum
      increment
    }
    maxQuantity: metafield(namespace: "cart", key: "max_quantity") {
      value
      type
    }
    legacyMaxQuantity: metafield(namespace: "limits", key: "max_quantity") {
      value
      type
    }
  }
}

Page-Level Metafields (Home Page)

These metafields are set on the Shopify Page with handle home and control home page behavior.

Namespace	Key	Full Reference	Type	Description
custom	banner	custom.banner	JSON	Banner configuration data (title, message, link, etc.)
custom	product_limit	custom.product_limit	Single line text	Number of products to display on home page
custom	lottery_collection_id	custom.lottery_collection_id	Single line text	Override the default lottery collection ID

GraphQL Query

Fetched in app/routes/($locale)._index.tsx:

page(handle: "home") {
  banner: metafield(namespace: "custom", key: "banner") { value }
  productLimit: metafield(namespace: "custom", key: "product_limit") { value }
  lotteryCollectionId: metafield(namespace: "custom", key: "lottery_collection_id") { value }
}

Defaults

Setting	Default	Defined In
Product limit	10 (range: 1–250)	app/lib/settings.ts
Collection ID	gid://shopify/Collection/429088702676	app/lib/settings.ts
Banner	null (no banner)	—

The parseProductLimit() and parseCollectionId() functions in app/lib/settings.ts handle validation and fallback to defaults.

Shop-Level Metafields

These metafields are set on the Shopify Shop object and define global quantity limits. See Quantity Limits for full details.

Current Namespace (cart.*)

Namespace	Key	Full Reference	Type	Description
cart	max_quantity_global	cart.max_quantity_global	Integer	Global max quantity across all product types
cart	max_quantity_lottery	cart.max_quantity_lottery	Integer	Max quantity for lottery products
cart	max_quantity_scratch_card	cart.max_quantity_scratch_card	Integer	Max quantity for scratch card products
cart	max_quantity_game	cart.max_quantity_game	Integer	Max quantity for game products

Legacy Namespace (limits.*)

Namespace	Key	Full Reference	Type	Status
limits	global_limit	limits.global_limit	Integer	Legacy fallback
limits	lottery_limit	limits.lottery_limit	Integer	Legacy fallback
limits	scratch_card_limit	limits.scratch_card_limit	Integer	Legacy fallback
limits	game_limit	limits.game_limit	Integer	Legacy fallback

Fallback Chain

For each product type, the system tries the cart.* metafield first, then falls back to limits.*:

cart.max_quantity_lottery  →  limits.lottery_limit  →  cart.max_quantity_global  →  limits.global_limit

Implementation: app/lib/shop-limits.server.ts

Customer Account Metafields

Namespace	Key	Full Reference	Type	Description
favorites	products	favorites.products	JSON	Customer's favorited product IDs

Complete Metafield Map

Summary of all metafields by scope:

Scope	Count	Namespaces Used
Product	8	custom
Variant	2	cart, limits
Page (Home)	3	custom
Shop	8	cart, limits
Customer	1	favorites
Total	22

WARNING

When creating metafield definitions in Shopify Admin, ensure the namespace and key match exactly. Metafields are case-sensitive.