# Loyalty points

> Turn on loyalty points, set earning and redemption rules, redeem points for a package on a subscriber's page, read the report and use the webhook field.

Source: https://docs.centipidbilling.com/billing/loyalty-points

Subscribers earn points when a payment activates or renews their package. Staff spend those points on a package for the subscriber. Points are never spent automatically, and the subscriber cannot redeem them from the portal.

## Turn it on

1. Open **Settings → Loyalty points** (under Billing & messaging).
2. Switch **Enable loyalty points** to **Enabled**.
3. Set the earning and redemption rules below.
4. Select **Save**.

The earning and redemption sections appear only while the switch is on. Saving needs permission to update packages. Administrators always have it.

## Earning rules

These settings sit under **Earning rules**.

| Setting | What it does | Default |
|---|---|---|
| **Spend per point** | Currency amount that counts as one threshold. Whole numbers from 1 to 1,000,000. | 100 |
| **Points per threshold** | Points credited each time the threshold is crossed. Whole numbers from 1 to 1,000. | 1 |
| **Subscriber type** | **Hotspot**, **PPPoE**, or both. All off means every subscriber earns. | All off |
| **Routers** | The routers whose payments earn. All off means every router. Shown only when the workspace has routers. | All off |

Points for a payment are:

```text
floor(payment amount ÷ Spend per point) × Points per threshold
```

The amount is rounded down to whole thresholds. Any part of a threshold is ignored, so a payment below **Spend per point** earns nothing.

### Who earns

- **Hotspot** means every subscriber who is not PPPoE.
- The router is the one the payment came through. If that is unknown, the subscriber's assigned router is used. With a router selected and neither known, the payment earns nothing.
- If every selected router has since been deleted, the router filter is treated as unset and all routers earn.
- Only a confirmed payment that activates or renews a package earns. Points are added shortly after, by a background job.
- These payments earn nothing, even when confirmed: an invoice marked paid, an invoice payment that doesn't renew the plan (a part-payment, or an installation, plan-change or custom invoice), a wallet top-up or unmatched payment banked to the wallet, an installation fee, a manual payment saved with renewal off, and an agent float top-up.
- A wallet auto-renewal earns when the plan renews, not when the wallet was topped up.
- A payment earns once. A retried callback does not add points twice.
- Payments made before loyalty was turned on do not earn points later.
- Redemptions are recorded as zero-amount payments with the method `LOYALTY`. They earn nothing.

## Redemption rules

These settings sit under **Redemption rules**.

| Setting | What it does | Default |
|---|---|---|
| **Minimum to redeem** | Points a subscriber must hold before any redemption. Whole numbers from 1 to 100,000. | 100 |
| **Value per point** | Currency value of one point. Whole numbers from 1 to 1,000,000. | 1 |

A package costs:

```text
ceil(package price ÷ Value per point)
```

The cost is rounded up, so a redemption never buys more than the points cover. Free packages cannot be bought with points.

A subscriber can redeem only when their balance is at least the package cost and at least **Minimum to redeem**. The minimum applies to the balance, not to the package cost.

**Note:**
The settings page describes redemption as "account credit", but points buy a whole package. No credit is added to the wallet.

## Redeem points for a subscriber

1. Open the subscriber's page. **Loyalty points** shows their balance.
2. Select the ⋯ (**More actions**) button, then **Redeem points**.
3. Pick a **Package**. Each option shows its cost in points. Packages the balance cannot cover are greyed out. If the balance is below **Minimum to redeem**, every package is greyed out.
4. Select **Redeem**.

The package activates the same way a paid one does. The points come off the balance. If the subscriber has a phone number and the workspace has an SMS gateway, they get a text with the points used and the points left. If there is no phone or gateway, the confirmation says "No SMS: no phone number or SMS gateway." If the text fails, it says "The SMS failed to send." The redemption still went through in both cases.

If the package fails to activate, the points are returned and the activity shows a refund entry.

The package list holds only packages that subscriber can take. You need permission to update the subscriber.

## Worked example

Settings: **Spend per point** 50, **Points per threshold** 2, **Minimum to redeem** 100, **Value per point** 5.

1. A subscriber pays 1,250 to renew their package. Points earned: floor(1,250 ÷ 50) × 2 = 25 × 2 = 50.
2. They renew with another 1,250 payment. The balance is now 100.
3. They want a package priced at 400. It costs ceil(400 ÷ 5) = 80 points.
4. The balance of 100 covers 80 and meets the minimum of 100, so staff can redeem. The balance drops to 20.

With the same settings, a balance of 90 could not redeem a package costing 80 points. It is below the minimum.

## Loyalty points report

Open **Billing → Loyalty points**. You need permission to view subscribers. The totals at the top are **Points issued**, **Points redeemed** and **Outstanding points**. **Outstanding value** is outstanding points times **Value per point**, and shows only to staff with the financials view permission.

Use the **Subscribers** and **Activity** tabs under the totals to change the table.

- **Subscribers**: one row per subscriber with a **Balance**, **Earned**, **Redeemed** and **Last activity**. Highest balance first.
- **Activity**: every entry, newest first, with **Date**, **Subscriber**, **Type**, **Points** and **Payment** (the receipt number).

Search by name or phone. The report lists only subscribers the signed-in staff member may see, so router-restricted staff see their own router's subscribers. Until the first entry exists, the page shows an empty state.

## The loyalty_points webhook field

Subscriber events and `payment.received` webhook payloads carry `loyalty_points`, the subscriber's balance.

- On `payment.received`, the value already includes the points that payment earns, even though they are added a moment later.
- It is `null` while loyalty is off, and for payloads with no subscriber account.

See [Settings](https://docs.centipidbilling.com/getting-started/settings#webhooks) for webhook setup and handling the payload safely.

## When loyalty is off

- No payment earns points, and no job is queued.
- The **Loyalty points** report page returns "not found" and its **Billing** menu entry is hidden.
- The subscriber's **Loyalty points** figure and the **Redeem points** action are hidden. The redeem request is refused.
- `loyalty_points` in webhooks is `null`.
- Existing balances are kept. They show again, and can be spent, when loyalty is turned back on.

## Support checklist

If a subscriber says they did not get points, check these in order.

1. Is **Enable loyalty points** on?
2. Was the payment confirmed? Pending payments earn nothing.
3. Did the payment activate or renew a package? Invoice payments that only settle an invoice, and wallet top-ups, do not earn. A full payment of a package invoice that renews the plan does earn.
4. Is the payment at least **Spend per point**?
5. Do **Subscriber type** and **Routers** include this subscriber and the router they paid through?
6. Search the subscriber in the report's **Activity** view for an entry with the payment's receipt number.
