Skip to content

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:

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:

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.

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 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.