Gift & Tiered Banner for Hydrogen

A copy-paste package that renders Abra's gift & tiered banner in your Hydrogen storefront. It reacts to the live cart, showing tier progress and unlocked gifts, and adds gifts to the cart.

To get access to the package message Abra support outlining your use case.

Supports: gift and tiered promotions (MultiEffectTiers), single currency/locale.

How it works

The package reads your active Abra promotion from the shop's metafields through your Storefront API, computes the tier/gift state from the live cart, and renders a prebuilt web component. You wire it up in two places: a route loader (fetches the promotion) and a component (renders + handles "add gift").

Prerequisite

Tapcart must be enabled for the shop in Abra — that's what publishes the promotion to the storefront-readable metafields. If the promotion was set up before Tapcart was enabled, re-save it in Abra.

1. Copy the files

Copy everything in package/ and the two reference files in examples/hydrogen/ into app/lib/abra/ in your project. The .js is a prebuilt web component, don't edit it.

2. Fetch the promotion in a route loader

import {loadAbraBannerData} from '~/lib/abra/product-route-loader';

export async function loader({context}: LoaderFunctionArgs) {
	const abraData = await loadAbraBannerData(context); // {abraBanner} | null
	return {...(abraData ?? {abraBanner: null})}; // spread it — keep `abraBanner` at top
}

• ABRA_APP_ID is already filled in (1795063809) at the top of product-route-loader.ts — leave it as is.

• promotionKey is the second argument (defaults to PUBLIC, an auto-applied promotion). Pass a promotion code — or a value read from a link param — to target a specific promotion.

3. Render the banner

import {GiftTieredBanner} from '~/lib/abra/GiftTieredBanner';

<GiftTieredBanner
	promotionConfig={abraBanner} // from the loader (+ priceLookup — see usage.tsx)
	hydrogenCart={cart} // your useOptimisticCart() cart
	money={{currencyCode: 'AUD', symbol: '$', zeroLabel: '$0.00', freeLabel: 'Free'}}
	onAddGift={handleAddGift}
/>

See examples/hydrogen/usage.tsx for the full component (cart wiring + priceLookup reconstruction).

4. Add gifts to the cart

onAddGift(variantId) adds the gift via a normal CartForm LinesAdd to /cart. The added line must include an __abra attribute with the discount title — this is how the banner knows the gift is claimed:

attributes: [{key: '__abra', value: JSON.stringify({discount: discountTitle})}]