JavaScript API

The Ayra app embed exposes a small storefront JavaScript API as window.Ayra, so theme code can read the signed-in customer’s wallet, open the wallet launcher, add a variant to the wishlist or register for a restock alert, and react to changes through DOM events, without scraping Ayra’s blocks. The API is available after the ay:ready event, is read-mostly by design (every write goes through Ayra’s authenticated endpoint and is validated server-side), and is versioned: Ayra.version is 1 for the private beta, and breaking changes get a new major with both versions served for a release cycle.

Loading and readiness

The API is attached by the core bundle (defer), so it may not exist when inline theme scripts run. Wait for it:

window.addEventListener('ay:ready', ({ detail }) => {
  console.log(Ayra.version, detail.modules); // 1, { loyalty: true, referrals: true, ... }
});

// Or, if your script runs after the bundle:
if (window.Ayra?.isReady) start();

Ayra.ready() returns a promise that resolves once the bundle has loaded the shop settings and identified the customer (or confirmed there is none).

Reference

Status: live for beta merchants; planned ships with the module named.

Core

Method / property	Status	Returns	Notes
Ayra.version	Live	number	API major version
Ayra.isReady	Live	boolean	True after ay:ready
Ayra.ready()	Live	Promise<void>	Resolves when ready
Ayra.modules	Live	{ [module]: boolean }	Which modules are on for this shop
Ayra.settings	Live	object	The public settings (ayra.settings_public): labels, earn ratio, tiers
Ayra.on(event, handler)	Live	() => void	Sugar for addEventListener on the ay:* DOM events; returns an unsubscribe function

Customer

Method / property	Status	Returns	Notes
Ayra.customer	Live	{ id, tier, stage, preferredChannel } | null	The signed-in customer, or null for guests
Ayra.customer.identify({ email })	Live	Promise<boolean>	Attaches a guest’s actions to an email after an explicit action (newsletter form, restock registration). Never call it without the customer typing their email

Wallet (Loyalty)

Method	Status	Returns	Notes
Ayra.wallet.get()	Live	Promise<{ total, points, storeCredit, vouchers, tier, nextTier }>	Cached 60 s; ay:wallet.updated fires when it changes
Ayra.wallet.pointsFor({ amount })	Live	number	Points a cart or product total would earn, tier multiplier applied; pure, no request
Ayra.wallet.openLauncher(tab?)	Live	void	Opens the floating wallet launcher on wallet, earn, tiers or referrals
Ayra.wallet.redeem(rewardHandle)	Live	Promise<{ ok, storeCreditIssued }>	Converts points to store credit from the catalogue; the customer must be signed in

Referrals

Method	Status	Returns	Notes
Ayra.referrals.get()	Live	Promise<{ code, url, invited, pending, granted }>	Signed-in customers only
Ayra.referrals.share(channel)	Live	Promise<void>	Opens the native share sheet or the channel’s share URL and records ay:referral.shared

Wishlist, back in stock, pre-order, subscriptions, reviews

Method	Status	Returns	Notes
Ayra.wishlist.add(variantId) / .remove(variantId)	Planned (Wishlist)	Promise<void>	Guests get a cookie-backed list merged on login
Ayra.wishlist.has(variantId)	Planned (Wishlist)	boolean	Synchronous from local state
Ayra.wishlist.list()	Planned (Wishlist)	Promise<Item[]>
Ayra.restock.register(variantId, { channel, email })	Planned (Back in Stock)	Promise<void>	email only for guests
Ayra.preorder.info(variantId)	Planned (Pre-Order)	{ enabled, expectedShipDate, limit }	From the variant metafield; synchronous
Ayra.subscriptions.plans(productId)	Planned (Subscriptions)	Promise<Plan[]>	Selling plans with the save offers
Ayra.reviews.summary(productId)	Planned (Reviews)	{ average, count, distribution }	From the product metafield; synchronous
Ayra.reviews.open(productId)	Planned (Reviews)	void	Opens the review form modal

Events

All ay:* DOM events are listed on the Events page. Ayra.on is the preferred way to subscribe:

const off = Ayra.on('ay:wallet.updated', (wallet) => {
  document.querySelector('[data-points]').textContent = wallet.points;
});

Errors

Methods that talk to Ayra reject with an AyraError carrying code (not_signed_in, module_off, rate_limited, invalid, network) and a human-readable message. Read code, never the message, in your logic.

What the API will not do

• Expose another customer’s data, or any data for a guest beyond what they created in this session.
• Grant points or credit. Earning is decided by rules on the server; there is no client method for it.
• Bypass Journey Guard. Nothing in the API sends a message.

Related

• Storefront bundle & performance: how the bundle loads.
• Theme app blocks & embeds: the no-code route.
• REST API: server-to-server access after private beta.