Referral Program

Important: rewards are disabled after installation. Configure the audience and rules, run acceptance tests, and only then enable rewards.

1. Installation

1. Back up the store files and database.
2. If another referral add-on is installed, disable it to prevent duplicate attribution and rewards.
3. Upload the files to the CS-Cart root and install the add-on under “Add-ons → Downloaded add-ons”.
4. Open “Marketing → Referral Program” and verify the summary.

2. Participant audience

On the “General” tab, select who can receive personal links, access the referral portal, and earn points:

• all active registered users of the Customer type;
• all active vendors;
• all active administrators;
• users in selected available CS-Cart user groups.

The rules use OR logic. For example, if no user types are enabled and the “MLM” group is selected, only active members of that group participate. If no type and no group is selected, there are no participants.

3. Buyer recommendations

1. Set the recommendation lifetime. Zero disables buyer recommendations; a value above zero defines how long the visit is stored before registration or sign-in.
2. A participant creates a URL containing sr_ref. It may point to any allowed store page.
3. The buyer is linked after successful registration or sign-in. Standard CS-Cart registration and sign-in flows are handled automatically.
4. Optionally select a group for new buyers registered through a recommendation. A successfully linked new account is added to that group; existing buyers are not assigned when they merely sign in.
5. The selected group can be used in standard CS-Cart discounts and promotions.
6. Once linked, the cookie lifetime no longer applies: subsequent eligible orders are attributed without another referral visit.
7. A later link from another participant does not replace the existing relationship.

4. Rewards

1. On the “Rewards” tab, select the order status that confirms a reward.
2. Select fixed points or a percentage of the eligible order amount and enter the value in the single direct reward field.
3. For percentage rewards, configure points per primary currency unit.
4. Optionally exclude products, categories, and vendor plans through the native CS-Cart search and multi-select dialogs. Manual IDs are not required.
5. Click “Publish current rules”. New orders receive an immutable snapshot of those rules.
6. Test order placement, confirmation, repeated status updates, cancellation, full returns, and partial returns.
7. Enable direct participant rewards only after acceptance succeeds.

5. MLM and program invitations

All settings for this flow are located on the dedicated “MLM” tab.

1. Set the program invitation lifetime. Zero disables new invitations and new MLM relationships.
2. A separate URL containing sr_partner stores the inviter until the participation application is submitted.
3. The participant joins the tree only after approval. A normal account registration does not create an MLM relationship by itself.
4. Configure maximum depth, levels 1–3 order rewards, and fixed participant-addition rewards.
5. Test self-invitation, second-parent, and cycle rejection.
6. Enable MLM order rewards only after acceptance succeeds.

6. Storefront participant portal

• An allowed participant opens “Referral program” from the storefront account menu.
• The “Overview” tab contains personal links and a generator for any allowed store page.
• “Orders”, “Rewards”, “Team”, and “Terms” show privacy-safe data from the add-on's common application services.

7. External portal and custom authentication

• Configure an allowed HTTPS callback and a separate server-to-server secret.
• The external portal exchanges a one-time browser code for a claim token and completes binding through the API after successful authentication.
• If the store uses a custom sign-in method that bypasses standard CS-Cart hooks, the integration must call the add-on post-auth hook or claim endpoint.
• Never expose the handoff secret in a browser or trust raw referral identifiers.

8. Pre-launch verification

• Test access for every enabled type and selected group, and denial for all other users.
• Test values 0 and 30 for both lifetimes.
• Test normal registration, normal sign-in, and every custom authentication method in use.
• Test assigning the selected group to a newly referred buyer and not assigning it to an existing buyer after sign-in.
• Test search, saving, and repeated display of excluded products, categories, and vendor plans.
• Test the account menu and every portal tab for an allowed participant, and denial for an out-of-scope user.
• Test one-time tokens, self-referral, repeated order statuses, returns, and Multi-Vendor order splitting.
• Configure a scheduled queue worker before enabling rewards in production.

9. Limitations

• A new buyer does not receive a welcome bonus.
• Points are not a cash wallet; withdrawals and payouts are not supported.
• Changing a parent or buyer binding requires a separate audited administrative action.