Install with an AI agent (recommended)

Let your AI coding agent install Joy Loyalty on your Hydrogen or Weaverse storefront end to end — packages, environment, widget, Loyalty Page, deploy and verification — while you keep control of the secrets and the deploy button.

Headless storefronts are available on the Ultimate plan.

Overview

Installing a loyalty program on a headless storefront touches a lot of places: packages, server environment variables, a token route, the root loader, Content Security Policy, caching rules, the widget, the Loyalty Page and — if you use Weaverse — the block registry. None of it is hard, but it is easy to miss one step and spend an afternoon wondering why the widget is stuck on a skeleton.

So we packaged the whole procedure as an agent skill. Your coding agent (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI — any agent that reads Markdown skill files) follows the same step-by-step playbook our own team uses, reads your project, adapts the code to your routes and cart, and then verifies the result with you.

You stay in charge of the three things an agent should never do on its own: handling your headless secret, setting production environment variables, and pressing deploy.

How it works

You install the skill into your Hydrogen project once.
You paste one prompt telling the agent what you want (widget, Loyalty Page, Weaverse blocks).
The agent does the code work: installs @joy-loyalty/hydrogen (and @joy-loyalty/weaverse-hydrogen on Weaverse), wires the token route, root loader, CSP, cache rules, <JoyWidget/> with cart actions, and the Loyalty Page.
The agent stops and asks you whenever it needs a value only you have (your headless secret, your store domain) or before anything that touches production.
You verify together using the checklist at the end of this page.

Before you start

Make sure you have:

Joy Loyalty installed on your Shopify store, on the Ultimate plan.
Custom storefront development enabled: Settings > Developers > Enable Custom Storefront development.
A working Hydrogen project (or Weaverse Pilot theme) with Customer Account API login set up — without it every shopper is treated as a guest.
A Loyalty Page V2 if you want the Loyalty Page (Joy admin > On-site content > Loyalty page).
An AI coding agent open in your Hydrogen project folder.

Step 1: Add the Joy skill to your project

Run this in your Hydrogen project root:

npx skills add avada/joy-loyalty-skills

The command detects which coding agents you use and installs the joy-headless-install skill for each of them. You only do this once per project.

Step 2: Ask the agent to install Joy

Copy one of these prompts into your agent.

Hydrogen storefront (widget + Loyalty Page):

Use the joy-headless-install skill to install Joy Loyalty on this Hydrogen storefront.
I want the floating loyalty widget on every page and a Loyalty Page at /pages/rewards.
Wire the widget to my existing cart so redeemed coupons apply automatically.
Ask me for any value you need and do not deploy anything.
When you are done, walk me through the verification checklist.

Weaverse storefront:

Use the joy-headless-install skill to install Joy Loyalty on this Weaverse Hydrogen storefront.
Add the floating loyalty widget to every page and register the Joy blocks
so I can build my loyalty page in Weaverse Studio.
Ask me for any value you need and do not deploy anything.
When you are done, walk me through the verification checklist.

Already installed and something is wrong:

Use the joy-headless-install skill to diagnose my Joy Loyalty integration.
Symptom: <describe what you see, e.g. the widget stays on a loading skeleton>.

Step 3: Give the agent your Joy values

The agent will ask for these. Here is where to find each one:

Value	Where to find it
`JOY_API_URL`	`https://api.joy.so/app/api/v1/headless`
`JOY_SHOP_DOMAIN`	Your myshopify domain, e.g. `your-store.myshopify.com` — not your custom domain
`JOY_API_SECRET`	Joy admin > Settings > Manage keys > Headless secret — click Generate headless secret, then copy it. The Secret key on the same page does not work for headless.

Your headless secret is a password. Put it only in your local .env file and in Oxygen environment variables. Never commit it, never paste it into a public chat, and never give it a PUBLIC_ prefix — Hydrogen sends PUBLIC_* variables to the browser. A good agent will refuse to hard-code it; if yours tries, stop it. If you click Revoke and regenerate headless secret, the old secret stops working immediately — update JOY_API_SECRET everywhere.

Step 4: Review what the agent changed

Before you commit, ask the agent for a summary of its changes. You should see:

package.json — @joy-loyalty/hydrogen added (plus @joy-loyalty/weaverse-hydrogen on Weaverse).
.env and env.d.ts — JOY_API_URL, JOY_SHOP_DOMAIN, JOY_API_SECRET. The .env file must stay out of git.
app/routes/api.joy-token.ts — the route that signs customers in to Joy.
app/root.tsx — Joy data in the root loader and <JoyWidget/> in the layout.
app/entry.server.tsx — Joy domains added to your Content Security Policy, and logged-in pages marked private, no-store.
A Loyalty Page route, or the Joy components added to app/weaverse/components.ts.

If something on this list is missing, ask the agent why — sometimes your project already handles it, sometimes a step was skipped.

Step 5: What you do yourself

The agent prepares everything; these steps are yours:

Add JOY_API_URL, JOY_SHOP_DOMAIN and JOY_API_SECRET in Shopify admin > Hydrogen > your storefront > Storefront settings > Environment variables, for both Preview and Production. Mark JOY_API_SECRET as secret.
Commit the code (without .env).
Deploy with shopify hydrogen deploy or your GitHub integration — deploy to Preview first.
Run the verification checklist below on the preview URL, then promote to production.

Step 6: Verify the installation

Ask your agent to run through this with you, or do it yourself on the preview URL.

As a guest (incognito window):

The loyalty launcher appears on every page.
The browser console shows no Content Security Policy errors mentioning joy.so.
Opening the widget shows your programs and a Sign in button that goes to your login page.
Your Loyalty Page shows the guest sections (ways to earn, rewards, VIP tiers).

As a logged-in customer:

The widget shows the customer's real points balance and tier — compare with the customer in Joy admin.
Redeem a reward: the coupon is applied to the cart automatically.
Log out: the widget returns to the guest view.
Switch your storefront language (if you have several): Joy texts follow.

If every box is ticked, you are live.

Common problems

What you see	What to tell your agent
Widget stuck on a loading skeleton	"The Joy widget is stuck on a skeleton — check CSP and the widget asset URL."
Logged-in customers still see "Sign in"	"Logged-in customers see the guest widget — check `/api/joy-token` and full-page caching."
Works locally, broken after deploy	Environment variables are missing in that Oxygen environment (Preview and Production are separate).
Images or icons missing in the widget	"Joy images are blocked — merge all Joy CSP directives."
Loyalty Page block is empty	Your store is still on Loyalty Page V1 — switch to V2 in Joy admin.

Still stuck? Contact us through the in-app chat with your storefront URL and a screenshot of the browser console — we are happy to look.

Prefer to do it by hand?

The agent follows the same steps documented in Install manually. You can also mix: let the agent do the setup, then fine-tune the widget yourself using Loyalty widget and Loyalty Page.

Joy on Hydrogen & Weaverse Install manually