Point calculator on Hydrogen (headless)
Show customers how many points they'll earn on your Hydrogen product pages and cart, with the same numbers and design as the Point calculator on your Online Store theme.
Requires @joy-loyalty/hydrogen 0.4.0 or later. Headless storefronts are available on the Ultimate plan.
Overview
<JoyPointsCalculator/> is the headless version of the Point calculator block. Mount it on your product page or in your cart and customers see:
- On the product page — "Earn X points" for the selected variant and quantity. The number updates when they change either one.
- In the cart page or cart drawer — the points the whole cart will earn, after discounts.
- A join link for guests — opens the loyalty widget or goes to the login page, as you set in Joy admin.
- A Join Program button for signed-in customers who haven't joined yet.
The estimate uses the same earning programs, VIP tier rates and earning limits as your theme block, so the numbers match. Design and texts come from Joy admin, so you don't style the block in code.
Before you start
Complete Install manually first. You need:
- The
JOY_API_URL,JOY_SHOP_DOMAINandJOY_API_SECRETenvironment variables. - The
/api/joy-tokenroute. - The root loader returning
getJoyInitialData()— the samejoydata<JoyWidget/>uses. - Customer Account API login, so signed-in customers get their own tier and limits.
Install with an AI agent (recommended)
Let your AI coding agent (Claude Code, Cursor, Codex and others) add the block for you. The Joy skill walks it through the same steps as Add the block manually below, so it adapts the code to your product page and cart and checks the result with you. The skill tells the agent not to touch your headless secret and not to deploy — still review the changes before you commit.
1. Add the Joy skills to your Hydrogen project. Run this in your project root:
npx skills add tinhnv2001/joy-loyalty-hydrogen-skillsThis installs joy-headless-points-calculator next to joy-headless-install. Added the Joy skills before? Run the same command again — npx skills update only refreshes skills you already have and won't add the new one.
2. Paste this prompt into your agent:
Use the joy-headless-points-calculator skill to add the Joy Point calculator to my product page
(under the add-to-cart button) and to my cart drawer. Add the Customer Account query to my root
loader without letting it throw, and merge the Joy fragments and cart discount fields that match
my Storefront API version. Do not deploy anything.
When you are done, walk me through the verification checklist.Only want it on the product page? Drop "and to my cart drawer" from the prompt.
3. Review the changes. You should see:
package.json—@joy-loyalty/hydrogenat 0.4.0 or later.- Your root loader (
app/root.tsx) — the Customer Account query and ajoyPointsvalue. - Your product query and cart fragment with the Joy fragments added.
<JoyPointsCalculator/>rendered on your product page and in your cart.
Then run the Verify checklist on your preview store.
Joy isn't on your Hydrogen storefront yet? Do Install with an AI agent first. The calculator needs the token route and root loader that install sets up.
Add the block manually
1. Upgrade the package
npm install @joy-loyalty/hydrogen@^0.4.0 @joy-loyalty/sdk@^0.3.12. Pass customer details from your root loader
VIP tags and B2B status live in Shopify, so your root loader passes them to the block. Add this next to your existing getJoyInitialData() call:
import {getJoyInitialData} from '@joy-loyalty/hydrogen/server';
import {JOY_POINTS_CUSTOMER_ACCOUNT_QUERY, toJoyPointsCustomerInput} from '@joy-loyalty/hydrogen';
const isLoggedIn = await context.customerAccount.isLoggedIn();
const [joy, account] = await Promise.all([
getJoyInitialData({/* … your existing options … */}),
isLoggedIn
? context.customerAccount.query(JOY_POINTS_CUSTOMER_ACCOUNT_QUERY).catch(() => null)
: null,
]);
const {customerTags, isB2B} = isLoggedIn
? toJoyPointsCustomerInput(account?.data?.customer)
: {customerTags: undefined, isB2B: undefined};
return {joy, joyPoints: {customerTags, isB2B, isLoggedIn} /* , …the rest of your root data */};- Keep the
.catch(() => null)— if Shopify's Customer Account API is slow or down, your page still loads. - Pass
isLoggedInfor every visitor, guests included.
3. Add the Joy fields to your product and cart queries
The package exports GraphQL fragments. Spread them into the queries you already have:
- Product page:
...JoyPointsProducton the product and...JoyPointsVarianton the selected variant (JOY_POINTS_PRODUCT_FRAGMENT,JOY_POINTS_VARIANT_FRAGMENT). - Cart:
...JoyPointsCartLineinside your existinglines(first: $numCartLines) { nodes { … } }(JOY_POINTS_CART_LINE_FRAGMENT). - Cart discounts (required for the cart): on the cart, also select
discountCodes { code applicable }and the order discounts — the same fields as in Redeem in Cart on Hydrogen. Already added the Redeem in Cart fragment? You're covered.
Selling subscriptions? Also spread JOY_POINTS_VARIANT_SELLING_PLANS_FRAGMENT and JOY_POINTS_CART_LINE_SELLING_PLAN_FRAGMENT. They need the unauthenticated_read_selling_plans Storefront API scope. Without them, subscription products earn as one-time purchases.
4. Mount the component
On the product page, for example under the add-to-cart button:
import {JoyPointsCalculator} from '@joy-loyalty/hydrogen';
import {useRouteLoaderData} from 'react-router';
export function ProductPoints({product, selectedVariant, quantity}) {
const root = useRouteLoaderData('root');
if (!root?.joyApiUrl || !root.joyShopDomain) return null;
return (
<JoyPointsCalculator
apiUrl={root.joyApiUrl}
shopDomain={root.joyShopDomain}
initialData={root.joy ?? null}
context="product"
product={product}
selectedVariant={selectedVariant}
quantity={quantity}
customerTags={root.joyPoints?.customerTags}
isB2B={root.joyPoints?.isB2B}
isLoggedIn={root.joyPoints?.isLoggedIn}
/>
);
}In the cart page or cart drawer, use the same component with context="cart" and pass the cart instead of the product:
<JoyPointsCalculator
apiUrl={root.joyApiUrl}
shopDomain={root.joyShopDomain}
initialData={root.joy ?? null}
context="cart"
cart={cart}
customerTags={root.joyPoints?.customerTags}
isB2B={root.joyPoints?.isB2B}
isLoggedIn={root.joyPoints?.isLoggedIn}
/>For every prop, see Points calculator (opens in a new tab) on the developer docs.
Customize the design
The block uses your Point calculator settings in Joy admin — the same settings as the Online Store theme block. Go to Branding > Point calculator > Setup to change the icon, icon size, colors, text size and texts. Your Hydrogen storefront picks them up.
A few settings work differently on Hydrogen:
| Setting | On Hydrogen |
|---|---|
| Choose positions and Also use on Cart Page | Not used. Where you mount the component decides where it shows. |
| Text action link | Used as the guest join link. |
| Trigger: Point Calculator link (non-login customers) | Open loyalty widget opens the Joy widget (it must be on the page). Redirect to login page goes to your login page. See Redemption behavior. |
Who sees the block
- Guests see the estimate and the join link.
- Signed-in members see the estimate for their own VIP tier, capped by their earning limit.
- Hidden for customers who left the program or are excluded by a membership segment, for B2B customers when you exclude B2B customers from loyalty, and for members who have reached their earning limit.
- Hidden when there's nothing to earn (0 points).
Limitations
- Base currency only. When the cart or buyer currency differs from your store's base currency, the block doesn't show.
- Cart total only. The cart shows one estimate for the whole cart, not one per item.
- No counting animation. The block uses the V4 look. HTML in the calculator texts shows as plain text.
- Free gifts. A cart with a Joy free gift can show slightly more (one minor currency unit, such as 1 cent, per gift) than your theme block.
- Products in more than 20 collections can show a different estimate than your theme block.
- No Weaverse block yet. On Weaverse storefronts, use the component in code.
Verify
- As a guest, open a product page — "Earn X points" shows under the add-to-cart button.
- Change the variant and the quantity — the number updates.
- Add the product to the cart and open the cart drawer — the cart estimate shows.
- Apply a discount code — the cart estimate updates, matching your Online Store theme.
- Sign in as a VIP member — the estimate matches the same product on your Online Store theme.
- Click the guest join link — it opens the widget or the login page, as set in Joy admin.
- Change the icon or text color in Branding > Point calculator — your storefront reflects it.
Troubleshooting
| What you see | Cause | Fix |
|---|---|---|
| The cart estimate never shows | The cart query is missing the cart discount fields. | Add discountCodes and the order discount fields from step 3. |
[joy] JoyPointsCalculator: … warning in the console | A required prop or fragment is missing, or the Joy widget code failed to load. | Check the props in step 4, leave JOY_WIDGET_ASSET_URL unset in production and check your CSP. |
| A signed-in customer doesn't see the block | Their Joy balance didn't load, the token route returns 401, or they're excluded from loyalty. | Check JOY_API_SECRET matches the Headless secret in Joy admin. See Troubleshooting. |
| VIP or tag-based rules don't apply | customerTags isn't passed. | Add the Customer Account query from step 2. |
| Subscription products earn like one-time purchases | The selling-plan fragments aren't in your queries. | Add them, and the unauthenticated_read_selling_plans scope. |
| The block doesn't show in another currency | Base currency only. | Test in your store's base currency. |