Metafields & metaobjects reference

Ayra writes its customer-, product- and order-level state to Shopify metafields in the ayra namespace and defines a small set of ayra_* metaobjects, so a theme, a Shopify segment, Shopify Email or another app can read a balance, a tier, a lifecycle stage, a product rating or an order’s attribution without calling Ayra. Definitions are created at install with the app as owner, which means they are visible in the admin’s metafield settings, readable from Liquid and the Storefront API, and removed by Shopify when the app is uninstalled.

TODO

This table is written from the modules’ design and the primitives each one uses. It must be replaced with the definitions exported from the app repository (the metafields and metaobjects definition files) before the public listing, and kept in sync from there. Rows marked “later” are created only when their module ships.

Conventions

• Namespace ayra for metafields; definition names prefixed ayra_ for metaobjects.
• Owner types: customer, product, variant, order, shop.
• Access: storefront read access is granted on everything a theme block needs; admin API read for all; write is Ayra only.
• Money values are JSON { amount, currencyCode } in the shop currency. Dates are ISO 8601.
• Shopify’s standard reviews.rating and reviews.rating_count product metafields are written in addition to ayra.*, because Shopify and other apps already read them.

Metafields

Customer

Key	Type	Written by	Notes
ayra.wallet_balance	json	Loyalty	{ total, points, storeCredit, vouchers } in shop currency; the Smart Wallet view
ayra.points_balance	number_integer	Loyalty	Points only, for Liquid and segments
ayra.store_credit_balance	money	Loyalty	Mirrors Shopify store credit for convenience
ayra.tier	single_line_text_field	Loyalty	Current tier name; empty when tiers are off
ayra.tier_progress	json	Loyalty	{ tier, nextTier, progress, remaining, basis }
ayra.points_expiring	json	Loyalty	{ points, expiresAt } for the next expiry batch
ayra.referral_code	single_line_text_field	Referrals	Stable code shown in the hub
ayra.referral_url	url	Referrals	Canonical share link
ayra.referrals	json	Referrals	{ invited, pending, granted } counts
ayra.lifecycle_stage	single_line_text_field	Segmentation	new, active, at_risk, lapsed, won_back
ayra.segments	list.single_line_text_field	Segmentation	Segment handles the customer is in
ayra.intent_score	number_decimal	Wishlist (later)	0–1
ayra.ltv	money	Analytics	Lifetime revenue after refunds
ayra.open_issue	boolean	Trust Recovery	True while a support issue is open
ayra.wishlist	json	Wishlist (later)	[{ variantId, addedAt }]
ayra.preferred_channel	single_line_text_field	Journey Guard	email, sms, whatsapp, push

Product and variant

Key	Owner	Type	Written by	Notes
reviews.rating	product	rating	Reviews (later)	Shopify standard; { scale_min: 1, scale_max: 5, value }
reviews.rating_count	product	number_integer	Reviews (later)	Shopify standard
ayra.review_summary	product	json	Reviews (later)	{ average, count, distribution, mediaCount, lastPublishedAt }
ayra.qa_count	product	number_integer	Reviews (later)	Answered questions
ayra.wishlist_count	variant	number_integer	Wishlist (later)	For “N people want this” blocks
ayra.restock_subscribers	variant	number_integer	Back in Stock (later)	Registrations waiting
ayra.preorder	variant	json	Pre-Order (later)	{ enabled, expectedShipDate, limit, sellingPlanId }

Order

Key	Type	Written by	Notes
ayra.attribution	json	Analytics	{ module, opportunityType, actionId, channel, window } or { module: null }; single-touch (Revenue Truth)
ayra.referral	json	Referrals	{ referrerId, code, status } on referred orders
ayra.redemption	json	Loyalty	{ points, storeCredit, vouchers, ledgerIds } applied at checkout
ayra.points_earned	number_integer	Loyalty	Points this order earned once paid

Shop

Key	Type	Notes
ayra.settings_public	json	What blocks need before a customer is identified: points label, currency display, earn ratio, tiers list
ayra.modules	json	Which modules are on, so a theme can hide blocks for modules that are off

Metaobject definitions

Definition	Fields	Written by	Notes
ayra_review	product (product reference), customer (customer reference, optional), rating (integer), title, body, media (list.file_reference), verified (boolean), status (published/unpublished), reply, reply_at, published_at, source (ayra/import:judge-me/…)	Reviews (later)	One entry per review, so themes can render reviews with Liquid and no block
ayra_question	product, customer (optional), question, answer, answered_by, answered_at, status	Reviews (later)	Q&A threads
ayra_tier	name, handle, threshold_type (spend/points), threshold (number), perks (json), badge (file_reference, optional), position	Loyalty	Tier definitions readable by themes
ayra_reward	handle, name, type (store_credit/points/voucher/percent), value, cost_points, expires_days, status	Loyalty	The reward catalogue shown in the hub
ayra_earn_rule	handle, name, event, points, ratio, enabled	Loyalty	So a “how to earn” block can be pure Liquid
ayra_opportunity_type	handle, name, priority, description, expiry_hours	Engine	Read-only catalogue of opportunity types for reporting apps

Reading from Liquid

{%- if customer -%}
  {%- assign wallet = customer.metafields.ayra.wallet_balance.value -%}
  {%- if wallet -%}
    <p>You have {{ wallet.points }} points and {{ wallet.storeCredit | money }} in store credit.</p>
  {%- endif -%}
  {%- if customer.metafields.ayra.tier -%}
    <span class="tier">{{ customer.metafields.ayra.tier }}</span>
  {%- endif -%}
{%- endif -%}

{%- assign summary = product.metafields.ayra.review_summary.value -%}
{%- if summary and summary.count > 0 -%}
  <span>{{ summary.average }} / 5 · {{ summary.count }} reviews</span>
{%- endif -%}

Customer metafields are readable in Liquid for the logged-in customer only. For anonymous visitors use the blocks, which fetch wallet state through the app embed after identification.

Related

• Theme app blocks & embeds
• Events: when each metafield is updated.
• Developers overview