Connect your BuyerKiosk account to FiveStars to automatically award loyalty points to customers based on their sales and buy transactions, and let them redeem rewards at checkout.

What This Integration Does

The FiveStars integration bridges your BuyerKiosk POS activity with the FiveStars loyalty platform. It automates the points-earning process so customers accumulate rewards without any manual entry.

Feature	Description
Automatic Points Calculation	Daily sales and (optionally) buy transactions are converted to loyalty points
Points Posting	Calculated points are automatically posted to the FiveStars API
Reward Redemption	Customers can redeem available rewards during checkout
Customer Lookup	Look up FiveStars members by phone number to see points, rewards, and history
Points Report	Detailed report of all points activity filterable by date range
Member Enrollment	Add new customers to the FiveStars program directly from BuyerKiosk

Getting Started

Requirements

Before connecting, you will need:

An active FiveStars business account
Your FiveStars Store ID (provided by FiveStars)
Your FiveStars Software ID (provided by FiveStars)
FiveStars must authorize BuyerKiosk to access your store on their platform
Admin access to your BuyerKiosk store

Tip: Contact your FiveStars account representative to obtain your Store ID and Software ID. They will also need to authorize the BuyerKiosk integration on their end.

Accessing the Settings

Log into your BuyerKiosk admin panel
Click Integrations in the left sidebar
Select FiveStars Settings

Configuring FiveStars

Step 1: Enter Your Credentials

On the FiveStars Settings page:

Enter your Store ID in the Store ID field
Enter your Software ID in the Software ID field

Step 2: Configure Points Calculation

Two toggle switches control how points are calculated:

Setting	Description
Include Tax in Points	When enabled, tax amounts are included in the points total. When off, only the pre-tax sale amount counts toward points.
Allow Points on Buys	When enabled, customers earn points on buy transactions (consignment purchases). When off, only regular sales earn points.

Step 3: Save and Test

Click Save Settings to store your configuration
Click Test Connection to verify BuyerKiosk can reach the FiveStars API with your credentials

A green success message confirms the connection is working. If the test fails, double-check your Store ID and Software ID, and confirm that FiveStars has authorized BuyerKiosk for your account.

How Points Work

Daily Points Calculation

Points are calculated automatically based on daily sales data:

At the end of each day, BuyerKiosk aggregates sales data by customer phone number
For each customer, the system sums their total sales, tax, and (optionally) buy amounts
Points are calculated using your store's points ratio (dollars per point)
Positive amounts use floor rounding (e.g., $12.50 at $1/point = 12 points)
Negative amounts (returns) use ceiling rounding to properly deduct points

Points Posting

After calculation, points are queued for posting to the FiveStars API:

Non-zero point records are placed in the outgoing queue
A background job sends each record to the FiveStars API
The posting status is tracked (Pending, Posted, or Error)
Successfully posted records show a timestamp in the Points Report

Redemption Flow

When a customer wants to redeem a reward at checkout:

The cashier looks up the customer by phone number
BuyerKiosk shows available rewards the customer can afford (based on current points)
The cashier selects the reward(s) to redeem
The redemption is sent to FiveStars API first, then recorded locally
Duplicate redemptions for the same customer on the same day are automatically blocked

Points Report

The FiveStars Points Report provides a detailed view of all points activity. Access it from Integrations > FiveStars Points Report in the sidebar.

Report Features

Feature	Description
Date Range Filter	Select any date range using presets (Yesterday, Last 7 Days, Last 30 Days, etc.) or custom dates
Show/Hide Buys	Toggle to include or exclude buy-only transactions
Sortable Columns	Click column headers to sort by any field
Excel/PDF Export	Export the report data to Excel or PDF format
Search	Filter results by phone number, name, or any field

Report Columns

Column	Description
ID	Internal record identifier
Date	Transaction date (click to filter report to that single day)
Phone	Customer phone number (click to view the customer's full FiveStars profile)
Sale	Total sales amount for the day
Buy	Total buy amount for the day
Tax	Total tax amount
Points	Points earned or redeemed
Status	Posting status -- Posted, Pending, or Error

Status Indicators

Posted (green badge) -- Points were successfully sent to FiveStars
Pending (yellow badge) -- Points are calculated but not yet posted
Error (red badge) -- The posting to FiveStars failed

Row colors also provide a visual guide: green for sales earning points, blue for buy transactions, and red for returns.

Customer Lookup

Clicking a phone number in the Points Report opens the FiveStars Customer page, which shows:

FiveStars Data

Customer name, email, phone, and birthday
Current Points -- points available for redemption
Lifetime Points -- total points ever earned

BuyerKiosk Data

Local customer record (name, contact info, address)
SMS and email subscription status
First seen and last seen dates
Number of buys in the last 30 days

Buy History

A table of all buy visits for this customer, including buy ID, date, time, number of containers, and which team member handled the buy.

Buyer Alerts

Any alerts (warnings, no-buy flags, or informational notes) associated with this customer are displayed here.

Troubleshooting

"Store ID not configured" when testing connection

Cause: The Store ID field is empty or was not saved.
Solution: Enter your FiveStars Store ID and click Save Settings before testing the connection.

"API credentials not configured"

Cause: The FiveStars API environment variables are not set on the server.
Solution: Contact BuyerKiosk support to verify that the FiveStars API credentials are properly configured in your server environment.

Points show as "Pending" but never post

Cause: The background posting job may not be running, or there is a persistent API error.
Solution: Check the FiveStars Points Report for any Error status records. Contact support if the posting queue appears stuck.

"Not Enough Points" error during redemption

Cause: The customer does not have enough points for the selected reward.
Solution: Look up the customer by phone number to confirm their current point balance. Select a reward that costs fewer points.

Duplicate redemption blocked

Cause: The same reward was already redeemed for this customer today.
Solution: This is expected behavior. Each unique reward can only be redeemed once per customer per day to prevent accidental double-redemptions.

Customer not found in FiveStars

Cause: The customer's phone number is not enrolled in the FiveStars program.
Solution: Use the member enrollment feature to add the customer by phone number. They will start earning points on their next transaction.

Points amounts seem incorrect

Cause: The tax inclusion or buy inclusion settings may not match your expectations.
Solution: Review the settings on the FiveStars Settings page. Toggling Include Tax in Points or Allow Points on Buys changes how the total is calculated.

FiveStars Loyalty Integration