@hyperse-hub/hps-plugin-reward-points
Vendure plugin for customer reward points: balance tracking, earning on paid orders, redemption as a payment method, admin-adjustable ledgers, and configurable violation rules (for example, blocking points on certain product facets).
It works with @hyperse-hub/hps-plugin-payment-core so the storefront can mix reward points with PayPal, Stripe, digital cards, and other handlers.
Requirements
Install
yarn add @hyperse-hub/hps-plugin-reward-points
Vendure registration
import { HpsPluginPaymentCore } from '@hyperse-hub/hps-plugin-payment-core';
import { HpsPluginRewardPoints } from '@hyperse-hub/hps-plugin-reward-points';
HpsPluginRewardPoints.init(options)
| Option | Description |
|---|
newCustomerRegister | Optional welcome bonus. enabled (default false) and getRewardPoints (default 200) — when enabled, a job grants points after customer registration. |
rewardsViolationHandlers | Array of RewardsViolationHandler instances. Defaults include facetsRewardsViolationHandler: orders containing variants tagged with configured facet IDs cannot use or earn points as configured. Add your own handlers for custom rules. |
rewardPointsEarningAdjusters | Optional array of RewardPointsEarningAdjuster instances (default []). Growth/loyalty plugins register multipliers or bonuses here; the host wires them at init time. See Earning adjusters. |
What the plugin does
Data model and custom fields
Customer.customFields.rewardPointsTotal — Current balance (int, public, maintained by the plugin).
Order.customFields.rewardPointsUsed — Points reserved for the active checkout (int, public), reconciled when moving to payment.
Entities: RewardPointsTransaction (ledger), RewardPointsViolationMethod (admin-defined rules with translations).
Earning and spending
- Earn — When an order reaches
PaymentSettled from ArrangingPayment or PaymentAuthorized, points are credited from order.subTotalWithTax using the built-in rate (money in smallest units → points; see src/utils/reward-points-rate.ts). Registered rewardPointsEarningAdjusters run in order on that base amount (for example membership tier multipliers). Only registered customers (customer.user present) earn points.
- Estimate — Shop field
Order.estimatedRewardPointsEarned uses the same estimatePointsEarnedOnOrder pipeline as settlement, so the storefront preview matches what will be credited after payment.
- Redeem — Shoppers call Shop API
applyRewardPointsToActiveOrder(amount: Int!) to allocate points to the cart (partial amount is supported — for example up to half the order total on the storefront). This sets Order.customFields.rewardPointsUsed only; it does not settle payment by itself. At AddingItems → ArrangingPayment, the order process re-validates violation methods and reconciles rewardPointsUsed.
- Mixed / partial checkout — Typical flow with PayPal or Stripe:
- Customer applies points via
applyRewardPointsToActiveOrder → rewardPointsUsed is stored on the order.
- PSP plugins create a payment intent for
totalWithTax - totalCoveredByPayments - rewardPointsUsed (see getOrderAmountDue in hps-plugin-payment-core).
- On webhook/callback, the PSP controller first calls
addPaymentToOrder for the reward-points handler (if rewardPointsUsed > 0), then adds the PayPal/Stripe payment for the remainder.
- The reward-points handler deducts the ledger and records
USED_ON_ORDER; the PSP handler settles the cash portion.
- Full points checkout — Shop mutation
addRewardPointsPaymentToOrder when reward points cover the entire remaining total (no PSP needed).
- Refunds — On refund settlement (
Pending → Settled), points tied to the refunded amount are reversed via RewardsService.removePointsFromRefundedOrder.
Payment stack integration
RewardsPaymentIntegrationService implements RewardPointsPaymentIntegration from hps-plugin-payment-core. PayPal, Stripe, and other PSP plugins inject this service to resolve the reward-points PaymentMethod during mixed checkout and to settle the points portion before the external payment.
The reward-points PaymentMethodEligibilityChecker answers whether the customer can redeem (logged in, positive balance, no violation). It does not require rewardPointsUsed > 0 — that field is set later via applyRewardPointsToActiveOrder. The storefront uses eligiblePaymentMethods for the reward-points method as a signal to show the redeem widget; the method itself is hidden from the PSP radio list. Actual settlement still requires rewardPointsUsed > 0 (enforced by the payment handler).
On bootstrap, if no payment method exists for the reward-points handler code, the plugin creates one (checker + handler, English name “Reward points payment”).
Admin API (high level)
- List/query
rewardPointsTransactions, createPointsAdjustment, deleteRewardPointsTransaction.
- CRUD for
rewardPointsViolationMethods, channel assignment, and listing rewardPointsViolationMethodHandlers (configurable operations you can attach to violation methods).
Custom permission: RewardPoints (CRUD) is merged into authOptions.customPermissions.
Shop API (high level)
applyRewardPointsToActiveOrder, addRewardPointsPaymentToOrder.
Order.rewardPointsEarned, Order.estimatedRewardPointsEarned, OrderLine.isRewardPointsViolated.
myRewardPointsTransactions for the authenticated customer.
Earning adjusters (extension point)
Use RewardPointsEarningAdjuster when another plugin (membership tier, campaign bonus, referral uplift, and so on) should change how many points an order earns. Implementations live outside this package; the host registers them via HpsPluginRewardPoints.init({ rewardPointsEarningAdjusters: [...] }).
Pipeline:
- Base points =
earnedPointsFromCents(order.subTotalWithTax) (100 USD → 100 points when money is in cents).
- Each adjuster runs in registration order;
basePoints is the running total after prior adjusters.
- Final value is
Math.max(0, Math.round(points)).
The same pipeline powers RewardsService.estimatePointsEarnedOnOrder (checkout preview) and addPointsFromCompletedOrder (ledger credit on PaymentSettled).
Full interface details, lifecycle (init / destroy), and an example implementation: docs/earning-adjusters.md.
Exports
The package re-exports the plugin, RewardsService, RewardsPaymentIntegrationService, payment handler / eligibility checker symbols, events, RewardsViolationHandler and built-in handlers (for example facetsRewardsViolationHandler), RewardPointsEarningAdjuster / RewardPointsEarningAdjusterInput, and REWARD_POINTS_PAYMENT_INTEGRATION / RewardPointsPaymentIntegration from hps-plugin-payment-core.
License
MIT