Hyperse
  • Pricing
  • FAQs
Newsletter

Subscribe to our newsletter

Receive weekly updates with latest collections and exclusive offers, straight to your inbox.

Hyperse

Headless commerce solutions for brands, developers, and modern ecommerce teams.

Explore

  • Home
  • About Us
  • Partners
  • FAQs

Legal & resources

  • Proposal
  • Privacy Policy
  • Terms & Conditions

© 2026 Hyperse. All rights reserved.


  1. Home
  2. Vendure Plugins
  3. hps-plugin-reward-points
hps-plugin-reward-points

hps-plugin-reward-points

By Hyperse

hps-plugin-reward-points is a Reward Points plugin in the Hub Pay group.hps-plugin-reward-points provides Reward Points plugin capabilities for Hub Pay. Payments, billing, invoicing, and money-related capabilities. It is especially useful for payment workflows.

CoreVendure Plugins

Specifications

Technical details and package information for this product.

Package

@hyperse-hub/hps-plugin-reward-points

Support by

Hyperse

Support languages

TypeScript, JavaScript, Prolog, Shell, CSS

Integration type

Core

Category

Vendure Plugins

Compatible with

^3.0.0

Latest version

1.0.14

Downloads

0

Repository

ssh://git@github.com/hyperse-hub/hub-pay

Last published

July 13, 2026

Description
Changelog
loading...

@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

  • Vendure >= 3.0.0
  • Node.js >= 20
  • @hyperse-hub/hps-plugin-payment-core — register it alongside this plugin for shared shop payment APIs and reward-points payment resolution.

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'; // plugins: [ // HpsPluginPaymentCore.init({}), // HpsPluginRewardPoints.init({ // newCustomerRegister: { enabled: true, getRewardPoints: 200 }, // // rewardsViolationHandlers: [facetsRewardsViolationHandler, /* ... */], // // rewardPointsEarningAdjusters: [membershipTierEarningAdjuster, /* ... */], // }), // // ...other plugins // ],

HpsPluginRewardPoints.init(options)

OptionDescription
newCustomerRegisterOptional welcome bonus. enabled (default false) and getRewardPoints (default 200) — when enabled, a job grants points after customer registration.
rewardsViolationHandlersArray 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.
rewardPointsEarningAdjustersOptional 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:
    1. Customer applies points via applyRewardPointsToActiveOrder → rewardPointsUsed is stored on the order.
    2. PSP plugins create a payment intent for totalWithTax - totalCoveredByPayments - rewardPointsUsed (see getOrderAmountDue in hps-plugin-payment-core).
    3. 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.
    4. 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:

  1. Base points = earnedPointsFromCents(order.subTotalWithTax) (100 USD → 100 points when money is in cents).
  2. Each adjuster runs in registration order; basePoints is the running total after prior adjusters.
  3. 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

On this page

  • @hyperse-hub/hps-plugin-reward-points
    • Requirements
    • Install
    • Vendure registration
      • HpsPluginRewardPoints.init(options)
    • What the plugin does
      • Data model and custom fields
      • Earning and spending
      • Payment stack integration
      • Admin API (high level)
      • Shop API (high level)
    • Earning adjusters (extension point)
    • Exports
    • License