PIING
Rivo integration
Read a customer's live Rivo points balance and VIP tier onto their wallet pass. Awarding points on check-in is a separate switch, and it starts off.
Browse documentation
Setup
Integrations
Reference
FAQ
Questions or hardware orders: contact@piing.io
Rivo reads first. Connect it to Piing and Piing pulls each member's live Rivo points balance and VIP tier and shows them on their Apple or Google wallet pass, keeping the pass up to date when the balance changes, whether they earned in store or online. Recording a check-in back to Rivo as a points event is a second, separate switch, and it starts off: connecting Rivo to put a balance on the pass never, on its own, changes that balance.
Scope. This walkthrough covers Rivo in the Piing Shopify app, where each check-in resolves against your Shopify customers. The connector set differs between Shopify and a Retail ID implementation, so if you are not on Shopify, check Supported platforms first.
You will need a Rivo REST API key from the Rivo Developer Toolkit. Access to the toolkit depends on your Rivo plan.
How it works
- 01
A customer checks in: a tap on the door reader or an NFC reader beside any till, a pass held up to the tablet kiosk, the Piing tile in Shopify POS, a printed QR sign scanned with their own phone, or the QR on their pass read by the barcode scanner already at the till.
- 02
Piing matches the check-in to their Shopify profile and reads their live Rivo points balance and VIP tier.
- 03
Piing keeps the customer's wallet pass in sync with that balance and tier, and pushes a pass update when either changes, including points earned online.
- 04
Optionally, if you switch awarding on, Piing also records the visit back to Rivo as a points event, and your own Rivo earning rules decide what it is worth. That switch starts off.
Step 1: Get your Rivo API key
- 01
Open Rivo Loyalty & Referrals.
- 02
Go to Settings then Developer Toolkit.
- 03
Under REST API keys, click Generate API key, then copy it.
Access to the Developer Toolkit depends on your Rivo plan. If you cannot see it in Settings, your plan does not include it, and Rivo will ask you to upgrade or speak to your account manager. Rivo keeps one REST API key per store, so clicking Regenerate API key stops the old one working everywhere at once, including in Piing.
Step 2: Select Rivo as your loyalty platform
- 01
Open Piing and go to Integrations.
- 02
On the Loyalty Platform card, click Configure (or Manage if you have set one before).
- 03
Choose Rivo in the Loyalty platform dropdown.
- 04
Click Save.
Step 3: Add your API key
- 01
In Integrations, open Loyalty platforms.
- 02
On the Rivo card, click Connect.
- 03
Set Status to Active and leave Dispatch Mode on Direct API (recommended).
- 04
Paste your key into the API Key / Secret field.
- 05
Click Save, then Test Connection to confirm Piing can reach your Rivo account.
Your key is encrypted at rest and never shown again after saving.
Step 4 (optional): Choose what earns points
This step is optional and the master switch starts off, so nothing is written back to Rivo until you turn it on. If all you want is the balance and tier on the pass, you are already done at Step 3, and Rivo can stay connected as a read-only source for as long as you like. Note that three triggers ship ticked, so check-in, first-time customer and wallet pass installed will start awarding the moment the master switch goes on. To let Piing write visits back, on the same Rivo card switch on Let Piing award points in Rivo, then tick each event that should award. Set a value in the Points override field, or leave it blank to use the suggested one, and use the test button beside a trigger to fire it once:
Trigger
Suggested value
Customer checks in
Suggested10 points
First-time customer identified
Suggested50 points
Customer adds wallet pass
Suggested100 points
Purchase after check-in
Suggested25 points
Visit milestone reached
Suggested100 points
New store visited
Suggested30 points
To run a live test, enter a real customer email in the Test customer email field and click Send Test Reward (or Test fire next to an individual trigger). The result, including Rivo's response, appears in the Recent Reward Actions table at the bottom of the page.
While you're trialling, the Test mode (dry run, no actual dispatch) checkbox logs production events to the history without sending anything to Rivo. Explicit test fires always send live so you can verify the real call.
Points and tier on the wallet pass
Once Rivo is active, Piing reads each pass holder's Rivo points balance and VIP tier, shows them on the pass, and refreshes the pass whenever they change, including points earned online. If a customer moves up a VIP tier, the pass switches to the matching tier design on its next refresh.
Configure Wallet messages under Settings then Notifications then Triggers. Supported moments include accepted check-ins, a first recorded visit with your brand and visit milestones. Tier changes, birthdays and win-backs remain reserved events; refreshing a balance or tier does not enable those automations.
Enable the event, template and Wallet channel for your programme. Messages need an installed pass and the customer's device settings to allow them. Messages held by the frequency budget are not queued for the next day. See the Wallet messaging guide for limits and delivery results.
Common questions
How many points is a visit worth?
Whatever you set on the "Customer checks in" trigger (default 10). If you prefer the points value to live in Rivo, create a Custom Action there and put its exact name in the Custom action name field on the Rivo card. Piing then fires that action instead, and it appears natively in Rivo's widget and analytics.
Can customers earn more than once a day?
Piing applies the cooldown and daily check-in limit configured for that store before a visit qualifies. The default is one accepted check-in per customer, per store, per day, with a 15-minute cooldown. Each resulting award also carries an idempotency key, so a delivery retry cannot pay out twice. Rivo's own earning rule remains the final authority on what the accepted activity is worth.
Where do customers redeem points?
In Rivo, through the customer's account or your configured Rivo POS workflow. Showing the balance on a Piing pass does not itself redeem points or change the balance.
Do I need new cards or passes?
Your existing Piing-issued passes can show the connected Rivo balance on their next refresh, when the design includes that field. Customers use a Piing pass; you do not need to issue them a Rivo pass.
What happens if I disconnect?
Piing stops reading the Rivo balance and tier onto passes, and stops recording check-ins to Rivo if you had awarding switched on. Passes keep working as before.
Need a hand? Email contact@piing.io or use the in-app chat.