ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Ripllo Docs
⌘K

Referrals

Plugipay family portal: referrals

A referral program turns your existing customers into a distribution channel. They get a shareable link; when someone new clicks it and makes a qualifying purchase, both sides get a reward.

Unlike discount codes, referral programs are per-workspace — there's exactly one configuration, and every customer who has bought from you can mint a link against it. You configure the rules once and the system handles attribution end-to-end.

Rule of thumb. Referrals reward two sides: the existing customer (the referrer) and the new one (the referee). Most programs work best when the referee's discount is generous enough to win the click, and the referrer's reward is generous enough to keep them sharing.

What a referral program holds

Field What it's for
enabled Master switch. When false, the link-issue endpoint returns null and no rewards mint.
rewardType percent or fixed. Same shape on both sides.
referrerValue Reward for the existing customer who shared the link.
refereeValue Reward for the new customer who clicked it.
currency Currency for fixed rewards (and minPurchaseAmount).
minPurchaseAmount Smallest order that triggers a reward on either side.
rewardExpiryDays How long an issued reward stays valid after it mints.
attributionWindowDays How long after a click the referrer still gets credit.
maxRewardsPerReferrer Optional cap so one customer can't keep collecting forever.
programTerms Long-form terms shown on the referral landing page.

Setting up the program

Navigate to Dashboard → Referrals. The page shows your current configuration (or a "set up your program" CTA if you've never saved one).

Click Edit program, fill in the values, click Save. Behind the scenes this is PUT /api/v1/referrals/program — the program is a single row, so saving overwrites it.

How attribution flows

The lifecycle has five touchpoints. Most of them are wired up automatically if you're using the SDK or coming through Storlaunch.

POST /api/v1/referrals/links/issue
{ "accountId": "...", "customerId": "..." }

Returns a link with a unique code (e.g. alice-7Q9). One link per customer. Calling the endpoint twice returns the same link.

2. Record a click

When the referee clicks the link, your storefront calls:

POST /api/v1/referrals/links/click
{ "accountId": "...", "code": "alice-7Q9" }

This bumps the link's click counter and returns the underlying program/link IDs so you can set an attribution cookie.

3. Attribute on signup

When the referee creates an account (or completes guest checkout):

POST /api/v1/referrals/attributions/signup
{
  "accountId": "...",
  "refereeCustomerId": "cust_...",
  "refereeEmail": "...",
  "linkCode": "alice-7Q9",
  "externalSource": "storlaunch",
  "externalRef": "<storlaunchCustomerId>"
}

This creates a pending attribution row.

4. Fulfill on payment

When the referee's first qualifying order clears:

POST /api/v1/referrals/attributions/fulfill
{
  "checkoutSessionId": "...",
  "status": "paid",
  "currency": "IDR",
  "amount": 250000
}

Ripllo checks minPurchaseAmount, mints two discount codes (disc_*) — one for the referrer, one for the referee — and flips the attribution to rewarded. The codes appear in each customer's "my rewards" view.

5. Void on refund

If the order is later refunded:

POST /api/v1/referrals/attributions/void
{ "checkoutSessionId": "..." }

Ripllo flips the attribution to voided and revokes the issued reward codes. The customers see them disappear.

The stats page

The Stats tab on /dashboard/referrals shows:

  • Active links — how many customers have minted a link.
  • Clicks — total + last-30-day click count.
  • Attributions by status — pending / qualified / rewarded / voided / expired.
  • Revenue from referrals — sum of amount across rewarded attributions.

This is GET /api/v1/referrals/stats — available via the SDK as ripllo.referrals.stats().

"My rewards" (customer-facing)

The endpoint GET /api/v1/referrals/rewards/:accountId/:customerId returns every reward code issued to a given customer (both as referrer and as referee), along with status and expiry. Use this to power a "Your rewards" tab in your storefront's account area.

Expiring pending attributions

A nightly cron calls POST /api/v1/referrals/sweeps/expire-pending to flip stale pending rows to expired. The cutoff is program.attributionWindowDays after the click. You can call it manually from the SDK if you need to force a sweep.

What you can't do (yet)

  • Tiered rewards — one flat value per side. Tiered ladders (10% on first, 15% on third) are backlog.
  • Self-referral detection — we don't currently block a customer from claiming their own link. The minPurchaseAmount is the practical guard.
  • Reward in store credit — rewards always mint as discount codes, not as wallet balance.

Next