@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({}),
HpsPluginRewardPoints.init({}),
HpsPluginRewardReferral.init({
}),
],
};
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.
| Option | Type | Description |
|---|
rewardPointsToInviter | number | Fixed points credited to the inviter when the invitee’s first qualifying order settles. Default: 500. |
rewardPointsRateToInvitee | number | Multiplier applied to round(order.subTotalWithTax / 100) for the invitee on their first qualifying order. Default: 5. |
clientRegionalDomains | Partial<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. |
promoterGroups | string[] | 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
- When a customer needs a
referralLink, the plugin lazily allocates a unique referralShareCode (16 characters, charset 1-9 and A-Z excluding ambiguous letters).
- 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.
- 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
| Entity | Field | Purpose |
|---|
| Customer | referralShareCode | Inviter’s share code (readonly). |
| Customer | referralAttributionCode | Invitee’s bound code (readonly). |
| Order | referralBonusInviteeApplied | Idempotency flag after invitee bonus processing. |
| Order | referralBonusInviterApplied | Idempotency 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
| Script | Description |
|---|
yarn build | Server build + email template bundle |
yarn test | Unit tests + e2e (vitest) |
yarn codegen | GraphQL codegen (codegen.cjs) |
yarn serve | Local 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.