Getting Started with Rivo Headless Integration
Overview
Rivo’s Headless Architecture enables developers to use the full power of Rivo on custom storefronts – built with frameworks like Hydrogen, Remix, or Next.js while keeping loyalty data perfectly synchronized with Shopify.
This guide will walk you through end-to-end setup, from metafield definitions to Hydrogen environment variables, with all configuration details and code snippets you’ll need to get running in minutes.
What Is “Headless” in Rivo’s Context?
In Rivo’s headless architecture, the frontend presentation layer (your Hydrogen or Remix app) is decoupled from Shopify’s standard Liquid theme, but still powered by the same loyalty data.
Your storefront communicates with:
Shopify’s Storefront API → to fetch metafields that define Rivo’s configuration and translations.
Rivo’s REST API → to securely access customer data like points, tiers, and rewards via a Bearer Token.
Example:
A Hydrogen app queries the rivo_headless storefront metafields to render translations and reward settings, and calls Rivo’s API to show live points or redeem rewards.
Architecture Diagram
Here’s how all the pieces fit together:
Data Flow Summary
Storefront API Query: Hydrogen fetches Rivo metafields (
ba_loy,ba_global,rivo_translation) for configuration and translation data.Bearer Token Auth: Rivo REST API validates secure tokens for customer actions.
Server-side Sync: The Rivo backend synchronizes with Shopify and third-party tools (Klaviyo, Gorgias, etc.) so loyalty data remains in sync.
Requirements
Before getting started, make sure the following are in place:
Requirement | Description |
Rivo Plus or developer plan | Headless support begins on Rivo’s Plus plan |
Developer Toolkit Access | You’ll need to enable Rivo’s Developer Toolkit from your Rivo admin dashboard to generate API keys. |
Shopify Partner Account | Required for Hydrogen or custom storefront development. |
Node.js v18+ | Needed to run Hydrogen and its development server. |
Step 1: Install Hydrogen (skip if you've already installed)
Step 1: Install Hydrogen (skip if you've already installed)
Hydrogen is Shopify’s React-based framework for building custom storefronts.
Run the following in your terminal to install the Hydrogen CLI:
npm create @shopify/hydrogen@latest
Follow the prompts to name your project and select a template (we recommend hello-world for setup testing).
Once created, navigate into your project folder:
cd my-hydrogen-storefront npm run dev
You’ll now have a local Hydrogen storefront running at http://localhost:3000.
Step 2: Confirm Rivo Metafield Definitions
In your Shopify Admin, navigate to:
Settings → Custom data → Shop → Add definition
You’ll create three metafields under the namespace rivo_headless – these act as your storefront’s configuration data source. These should be added automatically but please reach out to support if not present.
1. Rivo Global Config
Field | Value |
Name | Rivo Global Config |
Namespace | rivo_headless |
Key | ba_global |
Type | JSON |
Description | Rivo global config |
Storefront API access | ✅ Enabled |
Customer Account API access | ❌ No access |
2. Rivo App Config
Field | Value |
Name | Rivo App Config |
Namespace | rivo_headless |
Key | ba_loy |
Type | JSON |
Description | Rivo loyalty configuration |
Storefront API access | ✅ Enabled |
3. Rivo Translations
Field | Value |
Name | Rivo Translations |
Namespace | rivo_headless |
Key | rivo_translation |
Type | JSON |
Description | Rivo translations |
Storefront API access | ✅ Enabled |
Note: Do not add a JSON schema unless you need validation – Rivo automatically syncs valid data into these metafields.
You should now see all three listed like this in your Shopify metafield definitions list:
Step 3: Set Environment Variables in Hydrogen
Inside your Hydrogen dashboard (Settings → Environments and variables), you’ll need to add two custom variables.
Add Variable #1 – RIVO_API_BASE_URL
Key | Value |
|
|
Leave this public, since it points to Rivo’s REST endpoint.
Add Variable #2 – RIVO_STOREFRONT_API_TOKEN
Key | Value |
|
|
Assign to all environments (
Production,Preview, etc)Optionally mark as secret to protect token visibility.
These two variables allow Hydrogen to authenticate with Rivo’s REST API for all customer-facing operations.
Your Hydrogen settings page should now look similar to this:
Step 4: Query Shopify Metafields in Hydrogen
In Hydrogen, fetch Rivo’s metafields using the Shopify Storefront API.
Example GraphQL query:
query RivoConfigs {
shop {
metafields(
identifiers: [
{ namespace: "rivo_headless", key: "ba_global" }
{ namespace: "rivo_headless", key: "ba_loy" }
{ namespace: "rivo_headless", key: "rivo_translation" }
]
) {
key
value
type
}
}
}
Hydrogen code example:
import { useShopQuery, gql } from '@shopify/hydrogen';
export function useRivoConfig() {
const { data } = useShopQuery({
query: gql`
query {
shop {
metafields(
identifiers: [
{ namespace: "rivo_headless", key: "ba_global" }
{ namespace: "rivo_headless", key: "ba_loy" }
{ namespace: "rivo_headless", key: "rivo_translation" }
]
) {
key
value
}
}
}
`,
});
return data.shop.metafields.reduce((acc, m) => {
acc[m.key] = JSON.parse(m.value);
return acc;
}, {});
}
This gives you immediate access to all Rivo configuration data on the storefront.
Step 5: Connect to Rivo REST API
For dynamic data like points, rewards, referrals, and VIP tiers, make authenticated calls to Rivo’s REST API.
Step 6: Validate Your Setup
Before going live, confirm the following:
Step | Check |
Storefront API queries return valid metafield JSON | ✅ |
Rivo REST API returns 200 with valid token | ✅ |
Hydrogen environment variables exist across all environments | ✅ |
Metafield namespace and keys exactly match | ✅ |
Customer data (points, rewards, tiers) display correctly | ✅ |
Test using a dummy customer account and verify points and tiers sync in real-time. Or open the console and type window.RivoJS to see if it loads.
Summary
By completing this setup, your Hydrogen storefront will:
Display Rivo loyalty content (tiers, points, rewards) dynamically.
Fetch translations and config directly from Shopify metafields.
Stay in sync with Rivo’s backend and third-party integrations.
Maintain secure, token-based authentication – with no sensitive data exposed client-side.