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-referral
hps-plugin-reward-referral

hps-plugin-reward-referral

By Yingchun Tian

hps-plugin-reward-referral is a Reward Referral plugin in the Hub Growth group.hps-plugin-reward-referral provides Reward Referral plugin capabilities for Hub Growth. Growth, campaigns, loyalty, and customer engagement features. It is especially useful for growth workflows.

CoreVendure Plugins

Specifications

Technical details and package information for this product.

Package

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

Support by

Yingchun Tian

Support languages

TypeScript, JavaScript, CSS, Prolog, Shell

Integration type

Core

Category

Vendure Plugins

Compatible with

^3.0.0

Latest version

1.0.13

Downloads

0

Repository

https://github.com/hyperse-hub/hub-growth

Last published

July 14, 2026

Description
Changelog
loading...

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

Vendure plugin for customer referral programs: share codes, attribution binding, invitation emails, and reward points for inviter and first-time invitee on qualifying orders (via @hyperse-hub/hps-plugin-reward-points).

Requirements

  • Vendure >= 3.6 (plugin compatibility: '>=3.0.0')
  • Node >= 16
  • Companion Hyperse plugins at runtime:
    • @hyperse-hub/hps-plugin-core (i18n, utilities)
    • @hyperse-hub/hps-plugin-email (invitation email handler and templates)
    • @hyperse-hub/hps-plugin-reward-points (point transactions)

Install the usual Vendure peer stack: @vendure/core, NestJS, GraphQL, TypeORM, rxjs, etc.

Installation

Add the package to your Vendure server and ensure peer dependencies are satisfied.

Registering the plugin

Import HpsPluginRewardReferral and register it together with HpsPluginCore, HpsPluginEmail, and HpsPluginRewardPoints (this plugin declares them as imports).

import { HpsPluginCore } from '@hyperse-hub/hps-plugin-core'; import { HpsPluginEmail } from '@hyperse-hub/hps-plugin-email'; import { HpsPluginRewardPoints } from '@hyperse-hub/hps-plugin-reward-points'; import { HpsPluginRewardReferral } from '@hyperse-hub/hps-plugin-reward-referral'; export const config = { plugins: [ HpsPluginCore.init({}), HpsPluginEmail.init({/* transport, from address, etc. */}), HpsPluginRewardPoints.init({/* reward points plugin options */}), HpsPluginRewardReferral.init({ // optional — see Configuration }), ], };

Local dev server reference: config/dev-server.ts in this package.

Configuration

Pass options to HpsPluginRewardReferral.init({ ... }). Defaults are defined on HpsPluginRewardReferral.options in src/hps-reward-referral.plugin.ts.

OptionTypeDescription
rewardPointsToInviternumberFixed points credited to the inviter when the invitee’s first qualifying order settles. Default: 500.
rewardPointsRateToInviteenumberMultiplier applied to round(order.subTotalWithTax / 100) for the invitee on their first qualifying order. Default: 5.
clientRegionalDomainsPartial<Record<LanguageCode, string>>Base URLs per locale for building Customer.referralLink (query param includes the share code). Default: { en: 'https://www.hyperse.net/' }. Configure every locale you use or fallbacks may warn.
promoterGroupsstring[]Customer group names treated as promoters. The inviter receives rewardPointsToInviter if they already have at least one paid order or belong to one of these groups. Default: ['Promoter'].

Full TypeScript shape: HpsPluginRewardReferralOptions in src/types.ts.

How rewards run

  1. When a customer needs a referralLink, the plugin lazily allocates a unique referralShareCode (16 characters, charset 1-9 and A-Z excluding ambiguous letters).
  2. Invitees call bindReferralCode with the inviter’s share code; this sets referralAttributionCode if the invitee has no prior attribution, no existing orders, and the code resolves to another customer in the channel.
  3. On OrderStateTransition to PaymentSettled (from ArrangingPayment or PaymentAuthorized), a job calc-reward-points-from-referral-order processes the order idempotently using order custom fields:
    • Invitee: bonus only when this is effectively their first paid order with your shop; points scale with rewardPointsRateToInvitee.
    • Inviter: fixed rewardPointsToInviter when the inviter has at least one historical paid order or is in promoterGroups.

If either side is already marked on the order (referralBonusInviteeApplied / referralBonusInviterApplied), that side is skipped.

Custom fields

EntityFieldPurpose
CustomerreferralShareCodeInviter’s share code (readonly).
CustomerreferralAttributionCodeInvitee’s bound code (readonly).
OrderreferralBonusInviteeAppliedIdempotency flag after invitee bonus processing.
OrderreferralBonusInviterAppliedIdempotency flag after inviter bonus processing.

GraphQL API

Shop API

  • bindReferralCode(referralCode: String!): Customer! — Active customer binds an inviter code (Permission.Owner).
  • sendReferralInvitations(input: SendReferralInvitationsInput!): SendReferralInvitationsResult! — Publishes SendReferralInvitationsEvent; email pipeline handled by HpsPluginEmail (Permission.Owner). Requires a non-empty referralLink.
  • myReferredCustomers(options: CustomerListOptions): CustomerList — Paginated invitees whose referralAttributionCode matches this customer’s share code (Permission.Owner).

Admin API

  • bindReferralCode(customerId: ID!, referralCode: String!): Customer! — Same bind logic as shop, for a specific customer. Requires RewardReferral.Update (see Permissions).

Extended Customer fields

  • referralLink: String — Resolved URL for sharing (may be empty if domain configuration is missing).
  • referralInviteeCount: Int! — Count of customers attributed to this inviter’s share code.

Permissions

The plugin registers RewardReferral (CrudPermissionDefinition). Grant RewardReferral.Update to roles that may use the admin bindReferralCode mutation.

Email

On bootstrap, the plugin registers the send-referral-invitations handler with HpsPluginEmail, using built templates under templates/dist. Configure email transport and template variables as required by your HpsPluginEmail setup.

Internationalization

Translation resources are registered in onApplicationBootstrap via I18nTranslationService from HpsPluginCore (src/i18n).

Development scripts

ScriptDescription
yarn buildServer build + email template bundle
yarn testUnit tests + e2e (vitest)
yarn codegenGraphQL codegen (codegen.cjs)
yarn serveLocal dev server (config/dev-server.ts)

Package exports

From @hyperse-hub/hps-plugin-reward-referral (see src/index.ts):

  • HpsPluginRewardReferral — plugin class
  • RewardReferralService — service for referral binding, links, and invitee listing
  • Re-exports from ./constants.js (for example rewardReferralPermission, loggerCtx, HPS_PLUGIN_REWARD_REFERRAL_INIT_OPTIONS)

License

MIT — see LICENSE.

On this page

  • @hyperse-hub/hps-plugin-reward-referral
    • Requirements
    • Installation
    • Registering the plugin
    • Configuration
    • How rewards run
    • Custom fields
    • GraphQL API
      • Shop API
      • Admin API
      • Extended Customer fields
    • Permissions
    • Email
    • Internationalization
    • Development scripts
    • Package exports
    • License