# FiveStars Loyalty Integration

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

1. Log into your BuyerKiosk admin panel
2. Click **Integrations** in the left sidebar
3. Select **FiveStars Settings**

---

## Configuring FiveStars

### Step 1: Enter Your Credentials

On the FiveStars Settings page:

1. Enter your `Store ID` in the Store ID field
2. 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

1. Click `Save Settings` to store your configuration
2. 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:

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

### Points Posting

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

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

### Redemption Flow

When a customer wants to redeem a reward at checkout:

1. The cashier looks up the customer by phone number
2. BuyerKiosk shows available rewards the customer can afford (based on current points)
3. The cashier selects the reward(s) to redeem
4. The redemption is sent to FiveStars API first, then recorded locally
5. 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.

---

## Related Articles

- [QuickBooks Integration](/support/articles/quickbooks-integration)
- [Shopify Integration](/support/articles/shopify-integration)
- [When I Work Integration](/support/articles/whenIwork-integration)