Loyalty Porgram

This guide explains how to set up and operate the Hivive loyalty feature for your store. Loyalty lets customers collect points on paid orders, save a QR loyalty card, and redeem points for rewards when staff attach the customer to a sale.

Availability

The loyalty menu appears in the merchant dashboard only when loyalty is enabled for your store.

If you do not see Loyalty in the admin sidebar, contact Hivive support to enable it.

Where To Manage Loyalty

Use the merchant dashboard:

• Customers: Create customers, send loyalty welcome emails, view customer points, and make manual point adjustments.
• Loyalty > Earn Rules: Define how customers earn points.
• Loyalty > Rewards: Define what customers can redeem with points.

Recommended Setup

1. Go to Loyalty > Earn Rules and create your earn rule.
2. Go to Loyalty > Rewards and create one or more rewards.
3. Go to Customers and add existing regulars if needed.
4. Train staff to attach the customer before payment so points can be earned and rewards can be redeemed.

Customer Joining Flow

Customers can join loyalty in several ways.

From The Dashboard

Go to Customers > Add Customer.

Enter at least one contact field. To send a loyalty card, turn on Join Loyalty Program and enter the customer's email address. Hivive sends a welcome email with a downloadable loyalty card and QR code. The email also includes wallet links for supported devices.

From Online Checkout

When loyalty is enabled, customers can choose Use loyalty instead during checkout. They enter an email or phone number:

• If a matching customer exists, the order is linked to that loyalty profile.
• If no match is found, the customer can finish joining on the checkout page.
• If the customer continues as a guest, the order is not linked to loyalty.

Online checkout currently focuses on identifying or joining customers so they can collect points. Reward redemption is handled through staff-assisted POS flows.

From Kiosk

When loyalty is enabled for the store, the kiosk cart includes Loyalty & details before checkout. Customers can continue as a guest or choose Sign in or join loyalty.

Kiosk loyalty lookup accepts an email, phone number, or loyalty card barcode. A customer can type the identifier on screen, or scan their loyalty card when a barcode scanner is connected to the kiosk. If a matching member is found, the kiosk attaches that customer profile to the order before checkout. If no member is found, the customer can join loyalty on the kiosk by entering their first name and email, with phone number optional.

Kiosk loyalty currently links the customer so the order can earn points after payment. Loyalty reward redemption is handled through the staff-assisted POS flow.

From POS

Staff can select an existing customer, create a customer, or scan the customer's loyalty QR code with the POS camera or a connected barcode scanner. Once the customer is attached to the sale, staff can view available points and apply eligible rewards before payment.

Attaching A Customer To An Order

Attaching a customer means linking the order to a customer profile before the order is paid. This is the step that lets Hivive know which loyalty balance should earn points or spend points.

There are several common ways to attach a customer.

Attach From POS

Use this flow for in-store orders.

1. Start the order as normal.
2. Open the customer action from the POS cart or customer area.
3. Search for an existing customer, create a new customer, or scan the customer's loyalty QR code with the POS camera or connected barcode scanner.
4. Confirm the selected customer appears on the order.
5. Apply any available loyalty rewards if the customer wants to redeem points.
6. Take payment.

The customer must be attached before payment for the order to earn points automatically. If the customer is attached and rewards are selected, the POS sends the selected reward IDs with the order so the backend can validate the redemption and deduct points after payment.

Attach From Online Checkout

Use this flow for online orders where the customer identifies themselves before paying.

1. The customer opens the checkout page.
2. They choose Use loyalty instead.
3. They enter the email or phone number linked to their loyalty profile.
4. If Hivive finds a match, the checkout page marks the loyalty profile as connected.
5. If no profile is found, the customer can enter their name and email to join loyalty before paying.
6. Once payment succeeds, the order is linked to that customer profile.

If the customer chooses guest checkout, Hivive stores the guest name and phone for that order only. Guest checkout does not earn loyalty points because no loyalty customer profile is attached.

Attach From Kiosk

Use this flow for self-service kiosk orders.

1. The customer adds items to the kiosk cart.
2. In Loyalty & details, the customer chooses Sign in or join loyalty.
3. The customer enters their email, phone, or loyalty card barcode. If a barcode scanner is connected to the kiosk, the customer can scan their loyalty card instead of typing.
4. If Hivive finds a matching customer, the kiosk shows loyalty as connected.
5. If no matching customer is found, the customer can create a loyalty profile before checkout.
6. When checkout starts, the kiosk sends the attached customer profile with the order.

Kiosk guest checkout can include a guest name and phone number, but it does not attach a loyalty profile and does not earn loyalty points.

Attach From The Dashboard

The dashboard is mainly used to create and manage customer profiles, not to attach a customer to an in-progress sale. If a regular customer is missing, create the profile from Customers first, then staff can select that customer or scan their loyalty QR code in POS.

If a customer was not attached before payment, use a manual point adjustment from the customer profile when you need to correct the balance.

Earn Rules

Each store can have one active earn rule at a time. Points are awarded after an order is paid and a customer is attached to the order.

Earn rule	How it works	Common use
Amount Spent	Award points for every configured spend threshold. You can apply it to all items, selected products, selected menus, or both. Surcharges and card fees are excluded from the spend calculation.	"Earn 1 point for every $10 spent."
Visit Based	Award a fixed number of points per paid visit when the order reaches the minimum purchase amount.	"Earn 5 points on every visit over $20."
Item Based	Award points for each selected product purchased.	"Earn 2 points for each coffee."
Menu Based	Award points for each purchased item from selected menus.	"Earn 3 points for lunch menu items."

If an order is refunded, earned points from that order are reversed automatically.

Rewards

Rewards define how customers spend points. You can create multiple rewards.

Reward type	How it works
Discount on Sale	Applies a percentage or fixed amount discount to the sale. Percentage rewards can have a maximum discount cap.
Discount on Menu Item	Applies a percentage or fixed amount discount to eligible items from selected menus.
Discount on Item	Applies a percentage or fixed amount discount to selected products.
Free Item	Makes one eligible selected product free per redemption.

Each reward has a Points Required value. Customers must have enough points for the selected rewards. If an order is refunded, points spent on loyalty rewards are returned automatically.

Redeeming Rewards In POS

1. Attach the customer to the sale by selecting the customer or scanning their loyalty QR code.
2. Open the customer's reward area.
3. Use the reward controls to add or remove rewards.
4. Check the previewed loyalty discount.
5. Complete payment.

The POS validates that the customer has enough points and that the cart contains eligible products or menu items for the selected reward.

Point Deduction Timing

Loyalty reward points are checked before payment, but deducted only after the order is paid.

When a loyalty reward is selected at checkout, Hivive checks the customer's current points balance and the cart's reward eligibility. If the customer has enough points, Hivive applies the reward discount to the order and stores the selected loyalty redemptions on that order.

At this point, the customer's points balance has not changed yet. The points are spent only when the order reaches the paid state. After payment succeeds, Hivive records a loyalty SPENT event, deducts the reward points from the customer's balance, then records any points earned from the same paid order.

This means points earned from the current order cannot be used to redeem a reward on that same order. They become available for future orders.

If Points Are Available At Checkout But Not At Payment

This edge case can happen if the same customer's points are used or adjusted somewhere else between checkout and successful payment. For example, a reward is selected on one unpaid order, then the customer redeems points on another order before the first payment completes.

Current behavior:

• Hivive validates the customer has enough points when the reward is applied to the order.
• Hivive does not reserve those points at checkout.
• When the order is paid, Hivive honors the loyalty redemptions already stored on the order and deducts those points.
• If the customer's balance dropped before payment, the paid order can push the customer's points balance below zero.

How to handle it operationally:

• Keep the time between reward selection and payment as short as possible.
• Avoid applying rewards to multiple unpaid orders for the same customer at the same time.
• If the wrong reward was applied before payment, remove or change the reward before taking payment.
• If the order has already been paid and the customer's balance is now incorrect, use the customer profile's manual loyalty adjustment with a clear reason.
• If the paid order is refunded, Hivive reverses earned points and returns spent reward points for that order automatically.

Managing Customers

The Customers page lets you:

• Search and open customer profiles.
• View loyalty points, total visits, total spend, last visit, and order history.
• Resend the loyalty welcome email if the customer has an email address.
• Add or deduct points manually with a reason for the audit trail.

Manual adjustments require a whole number of points and a short reason. Use this for service recovery, migration corrections, or goodwill credits.

Customer Loyalty Card

The welcome email includes a loyalty card image with a QR code. Customers can save the image or add the card to a supported wallet. Staff can scan this QR code in POS with the device camera or a connected USB barcode scanner to find the customer quickly.

If a customer cannot find their card, open their profile in Customers and resend the welcome email.

Apple Wallet Integration

Apple Wallet lets an iPhone customer save a loyalty pass that contains their QR code and current points balance.

Email Flow

The Apple Wallet flow starts from the loyalty welcome email.

1. A customer is created with Join Loyalty Program turned on, or staff resend the welcome email from the customer profile.
2. Hivive sends the customer a welcome email.
3. The email includes an attached loyalty card image, plus an Add to Apple Wallet link.
4. When the customer taps the Apple Wallet link, Hivive verifies the signed link and generates a .pkpass file for that customer.
5. The customer adds the pass to Apple Wallet.

If Apple Wallet is not configured for the loyalty program, the customer still receives the loyalty card image and can use the QR code in store.

What The Apple Wallet Pass Shows

The Apple Wallet pass includes:

• The store name.
• The customer's name.
• The customer's loyalty QR code.
• The customer's member ID.
• The current points balance.
• Basic store and contact details on the back of the pass.

The QR code uses the same customer barcode as the email card image. Staff scan it in POS, using the device camera or a connected barcode scanner, to attach the customer to the order.

Point Balance Updates And Notifications

When a customer adds the pass to Apple Wallet, Apple registers the device with Hivive for pass updates. Hivive stores the Apple device registration and push token for that customer's pass.

Hivive queues an Apple Wallet pass update when the customer's points change because of:

• Points earned from a paid order.
• Points spent on a loyalty reward.
• Points reversed or returned after a refund.
• A manual point adjustment from the customer profile.

After the points change, Hivive sends Apple a background pass update notification. The iPhone then asks Hivive for the latest pass, and Apple Wallet refreshes the points balance on the pass.

The pass includes the Apple Wallet change message: You now have %@ points. Apple controls exactly when and how that update appears on the customer's device. This is a Wallet pass update, not a marketing push notification or a separate email.

If Apple reports that a device token is no longer valid, Hivive removes that stale registration so future updates are only sent to active passes.

Future Wallet Support

Hivive plans to extend loyalty wallet support beyond Apple Wallet so more customers can save a scannable loyalty card on their phone.

Google Wallet

Planned Google Wallet support will let supported Android customers save a Hivive loyalty pass from the welcome email. The pass is expected to use the same customer barcode as the loyalty card image, so POS and kiosk barcode scanning flows can continue using the same loyalty identifier.

The intended flow is:

1. The customer joins loyalty or receives a resent welcome email.
2. The email shows an Add to Google Wallet option when Google Wallet is enabled.
3. The customer saves the loyalty pass to Google Wallet.
4. The customer opens the pass in store and scans the QR/barcode to attach their profile to an order.

Point balance display and update behavior may differ from Apple Wallet because Google controls how and when saved wallet objects refresh on each device.

Samsung Wallet / Samsung Pass

Hivive also plans to support Samsung wallet flows for supported Samsung devices. The customer-facing naming may be finalized as Samsung Wallet or Samsung Pass depending on the supported provider flow and device behavior.

The intended flow is similar:

1. The customer joins loyalty or receives a resent welcome email.
2. The email shows an Add to Samsung Wallet or Samsung pass option when enabled.
3. The customer saves the loyalty card to their Samsung device.
4. The saved pass contains the customer's loyalty barcode for POS or kiosk scanning.

As with Google Wallet, balance refresh and customer notification behavior will depend on Samsung's wallet capabilities and device support.

Rollout Notes

Apple Wallet remains the primary documented wallet integration today. Google Wallet and Samsung wallet support should be treated as planned future support until provider setup, testing, and merchant rollout are complete.

Even after these wallet options are added, the fallback loyalty card image in the welcome email remains important. Customers can always save or reopen that image and scan the QR code in store.

Best Practices

• Keep the earn rule simple so staff and customers can explain it easily.
• Create at least one low-point reward so new members can redeem sooner.
• Attach the customer before taking payment.
• Use product or menu targeting when you want to promote specific items.
• Add a clear internal reason for every manual point adjustment.
• Test each reward with a sample cart before announcing it to customers.

Troubleshooting

Issue	What to check
Loyalty menu is missing	Loyalty may not be enabled for the store. Contact Hivive support.
Customer does not earn points	Make sure the customer was attached before payment, the order is paid, and an earn rule exists. Also check minimum spend or selected product/menu conditions.
Customer cannot be found	Search by the email or phone, or scan the QR code again with the POS camera or connected barcode scanner.
Welcome email cannot be sent	The customer needs an email address and a generated loyalty barcode.
Reward cannot be applied	Check the customer's point balance and whether the cart contains eligible products or menu items.
Points changed after refund	Refunds automatically reverse earned points and return spent reward points for the refunded order.