Overview
This guide walks through the complete end-to-end setup of the Rivo x Gladly Lookup Adapter. When correctly configured, Gladly CS agents see a customer's Rivo loyalty data — points balance, loyalty status, VIP tier, referral URL, and date of birth — directly in the customer profile sidebar the moment they open a conversation.
There are two distinct parts to the setup. Both are required:
Part A — Rivo Custom App: Configures how Gladly calls the Rivo API and which attributes it maps.
Part B — Customer Profile Definition: Registers those attributes in Gladly so they actually render in the agent sidebar. This step is not accessible from the normal admin UI and must be done via a browser console call.
⚠️ IMPORTANT: Skipping Part B will result in the Rivo API returning data but nothing displaying in the agent sidebar. Both parts must be completed.
Prerequisites
Gather the following before starting. All items are required.
Item | Where to get it |
Rivo REST API key | Rivo Admin → Settings → API Keys |
Gladly admin access | Must have permission to create/edit Apps under Admin → App Developer Tools |
A real customer email | Any customer who exists in both Shopify and Gladly — used to test the integration |
Part A — Create and Configure the Rivo Custom App
A1. Navigate to Apps
In Gladly, click the gear icon to open Settings.
In the left sidebar under App Developer Tools, click Apps.
Click the Lookup Adapters tab.
Click Add App in the top-right corner.
Select Custom App from the options.
A2. Basic App Settings
Field | Value |
Name |
|
Lookup URL | |
Request Method |
|
📝 NOTE: Do not add a trailing slash to the URL. Use exactly: https://loyalty.rivo.io/api/integrations/gladly
A3. Authentication — HTTP Headers
Scroll to the HTTP Headers section. Add one header:
Header Name | Header Value |
|
|
⚠️ CRITICAL: Include the word "Bearer" followed by a space before pasting the API key. The value must be: Bearer <your_api_key_here> (replace with the merchant's actual key).
A4. Search Query Attributes
These attributes are sent to the Rivo API when Gladly looks up a customer. Scroll to the Search Query Attributes section.
Delete any existing entries. Then add exactly these five rows in order:
Attribute (case-sensitive) | Label (display name) |
| Points Balance |
| Loyalty Status |
| VIP Tier |
| Referral URL |
| Date of Birth |
⚠️ CRITICAL: Attribute names are case-sensitive. rivoPointsBalance is correct. rivopointsbalance, loyalty_status, vip_tier_name, and customer_identifier are all wrong and will silently fail.
A5. Search Results Attributes
These attributes are displayed alongside customer search results. Scroll to the Search Results Attributes section.
Delete any existing entries. Then add the exact same five rows as in A4:
Attribute (case-sensitive) | Label (display name) |
| Points Balance |
| Loyalty Status |
| VIP Tier |
| Referral URL |
| Date of Birth |
A6. Auto-Linking Fields
Scroll to the Auto-Linking Fields section. Ensure both checkboxes are checked:
Customer Email ✓
Phone Number ✓
📝 NOTE: Auto-Linking tells Gladly which fields to use when automatically matching a Gladly customer profile to a Rivo record. Both Email and Phone Number must be enabled.
A7. Save the App
Scroll to the bottom of the modal.
Click Save App.
Confirm the app appears in the Lookup Adapters list with the toggle enabled (green).
Confirm the Autolink Fields column shows:
Emails, Phones.mobile.
✅ SUCCESS CHECK: If the Autolink Fields column shows only "Emails" (no phone), go back and enable Phone Number in A6 and save again.
Part B — Update the Customer Profile Definition
This is the most important — and most commonly missed — step. The Customer Profile Definition controls which custom attributes are registered in Gladly and therefore visible in the agent sidebar. It is not editable from the normal admin UI and must be updated via a browser console API call.
⚠️ WHY THIS IS NEEDED: Even after correctly configuring Part A, Rivo data will NOT appear in the agent sidebar until the 5 Rivo attributes are registered in the Customer Profile Definition. The Lookup Adapter Debugger will show yellow warnings ("Customer attribute X is not configured in the profile") until this step is complete.
B1. Find the Merchant's Gladly Org ID
In Gladly, navigate to Admin → App Developer Tools → Lookup Adapter Debugger.
Click the Custom Attributes link. (If you don't see it, look for a "View Custom Attributes" link on the Lookup Adapter Debugger home page — it may be inside a shadow DOM component.)
Once the Custom Attributes page loads, open browser DevTools (
F12orCmd+Option+Ion Mac).Go to the Network tab and reload the page (
Cmd+R/Ctrl+R).In the Network tab, filter requests by typing:
customer-profile-defClick the GET request to
/api/v1/orgs/{orgId}/configuration/customer-profile-def.Copy the
orgIdvalue from the URL — this is the merchant's Gladly Org ID. Save it for the next step.
Example URL: /api/v1/orgs/WsC9W2ZZTQam0qVbfUw9IA/configuration/customer-profile-def
Org ID in this example: WsC9W2ZZTQam0qVbfUw9IA
B2. Run the Profile Definition Update
With the Custom Attributes page still open, open the browser console (DevTools → Console tab) and paste the following script. Replace YOUR_ORG_ID with the org ID from B1.
(async () => {
const orgId = 'YOUR_ORG_ID'; // replace this
const url = `/api/v1/orgs/${orgId}/configuration/customer-profile-def`; // Step 1: GET current definition
const getResp = await fetch(url);
const current = await getResp.json(); // Step 2: Define the 5 Rivo attributes to add
const rivoAttrs = [
{ attr: 'rivoPointsBalance', type: 'STRING', label: 'Points Balance (Rivo)', presentation: 'VISIBLE' },
{ attr: 'rivoLoyaltyStatus', type: 'STRING', label: 'Loyalty Status (Rivo)', presentation: 'VISIBLE' },
{ attr: 'rivoVipTierName', type: 'STRING', label: 'VIP Tier (Rivo)', presentation: 'VISIBLE' },
{ attr: 'rivoReferralUrl', type: 'STRING', label: 'Referral URL (Rivo)', presentation: 'VISIBLE' },
{ attr: 'rivoDateOfBirth', type: 'STRING', label: 'Date of Birth (Rivo)', presentation: 'VISIBLE' },
]; // Step 3: Merge (skip any already present)
const existing = current.attributes.map(a => a.attr);
const toAdd = rivoAttrs.filter(a => !existing.includes(a.attr));
if (toAdd.length === 0) { console.log('All Rivo attributes already present.'); return; }
const updated = { ...current, attributes: [...current.attributes, ...toAdd] }; // Step 4: PUT the updated definition
const putResp = await fetch(url, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(updated),
});
console.log('Status:', putResp.status, '| Added:', toAdd.map(a => a.attr).join(', '));
})()
✅ SUCCESS: A response of Status: 204 means the update was applied. If you see 401 or 403, confirm you are running the script while logged into Gladly admin in the same browser tab.
🔁 SAFE TO RE-RUN: The script checks for existing attributes before adding them, so it is safe to run multiple times. Duplicate attributes will never be added.
Verification — Confirming the Integration is Live
Step 1: Run the Lookup Adapter Debugger
In Gladly, go to Admin → App Developer Tools → Lookup Adapter Debugger.
Click Test Workflow under Autolinking + Detailed Workflow.
In the Email field, enter the email address of a real customer who exists in both Shopify and Gladly.
In the Lookup Adapter dropdown, select Rivo.
Click Test.
What you should see after a successful run:
Autolinking response: "returned 1 result — No errors were detected!"
Detailed response: "returned 1 result" with no yellow warnings about rivoPointsBalance, rivoLoyaltyStatus, rivoVipTierName, rivoReferralUrl, or rivoDateOfBirth
⚠️ STILL SEEING YELLOW WARNINGS? Yellow warnings saying "Customer attribute X is not configured in the profile" mean Part B was not completed or did not succeed. Re-run the console script from B2 and confirm you see Status: 204.
Step 2: Verify in the Live Agent View
Navigate to the Gladly agent view (not the admin panel).
Use the search icon to find the same customer you tested with.
Click to open their profile.
In the customer sidebar on the left, scroll down past the Shopify fields.
You should see the following Rivo fields populated:
Sidebar Label | Expected Value |
Points Balance (Rivo) | A number (0 if the customer has no points yet) |
Loyalty Status (Rivo) | "member" or the customer's specific tier status |
VIP Tier (Rivo) | Tier name, or blank if the merchant has no VIP tiers |
Referral URL (Rivo) | A hyperlink to the customer's unique referral URL |
Date of Birth (Rivo) | Customer's date of birth if collected, otherwise blank |
Troubleshooting
Symptom | Fix |
Debugger returns 0 results or an API error | The Authorization header is wrong. Confirm the value is |
Debugger returns data but nothing shows in the agent sidebar | Part B was not completed. Run the browser console script from B2. Confirm the PUT response is 204. |
Yellow warnings: "Customer attribute X is not configured in the profile" | Same as above — Part B is incomplete. Re-run the script. |
Autolink Fields column shows only "Emails" (no phone) | Phone Number auto-linking was not enabled. Re-open the Rivo app config, check the Phone Number box, and save. |
Attribute keys like | These are the old wrong keys. Delete them and replace with the exact rivo-prefixed keys from section A4/A5. |
Console script returns 401 or 403 | Run the script from the same browser tab where you are logged into Gladly admin. Do not run from a different tab or browser window. |
Rivo fields appear but are all blank / empty | The customer exists in Gladly but not in Rivo — they have never engaged with the loyalty program. Try a different customer who has made a purchase from the merchant's store. |
Quick Reference
Item | Value |
Rivo API Endpoint | |
Required HTTP Header |
|
Required Attribute Keys (exact, case-sensitive) |
|
Customer Profile Definition API |
|
This endpoint is not linked from the Gladly admin nav. Discover the orgId by loading the Custom Attributes page and watching network requests.
Setup Checklist
☐ Rivo app created under Admin → Apps → Lookup Adapters → Custom App
☐ Lookup URL set to:
https://loyalty.rivo.io/api/integrations/gladly☐ Authorization header set:
Bearer <key>☐ Search Query Attributes: all 5 rivo-prefixed keys added
☐ Search Results Attributes: all 5 rivo-prefixed keys added
☐ Auto-Linking: Customer Email ✓ and Phone Number ✓ both checked
☐ App saved and toggle is enabled (green)
☐ Customer Profile Definition updated via browser console (Part B)
☐ Debugger returns 1 result with no yellow warnings
☐ Rivo fields visible in live agent sidebar