Loyalty and referrals

Sellerlane includes two related but separate growth systems:

• Loyalty rewards a customer’s own qualifying activity with points and published redemption offers.
• Customer referrals attribute a new customer’s qualifying order to an advocate and can reward both sides.

Neither system changes the financial meaning of an order. A discount reduces the eligible selling price; store credit or a gift card is a payment tender; and points remain a non-cash loyalty balance until redeemed into a defined reward. See Financial semantics.

For worked examples that connect these balances to COD, fulfillment, self-service, events, and review rewards, see Order & rewards lifecycle.

Loyalty balances

Every member has separate balances:

Balance	Meaning
Pending	Earned but still inside a vesting/return hold; not spendable
Available	Vested, unexpired points that are not reserved
Reserved	Held for an active cart or redemption; still outstanding but unavailable elsewhere
Unrecovered	Points that should have been clawed back after the member had already spent them; future earnings repay this debt first

The append-only points ledger records the original earn, vesting, redemption, expiry, manual adjustment, and reversal. A correction adds a compensating entry; it never deletes history.

Configure the program

The base program controls:

• points earned per money amount;
• points-to-value redemption rate and minimum redemption;
• purchase vesting days;
• fixed expiry or activity-reset expiry;
• maximum cart subtotal payable with points;
• rounding mode;
• whether discounts, tax, shipping, gift cards, and store credit are excluded from the purchase earn basis;
• whether pay-with-points can combine with product, order, or shipping discounts.

Purchase points use a snapshotted earn basis. A later rule edit does not rewrite points already earned. Full cancellation, void, and terminal full refund always reverse the corresponding earned basis. Partial refunds do so when Partially refunded is included in the program’s configured clawback statuses; a retry is idempotent.

Note

“Exclude store credit” affects how many points the purchase earns. Applying store credit never lowers gross or net sales because credit is a tender, not a discount.

Earn rules

Earn rules can target purchases, spend thresholds, products, punch cards, signup, birthday, newsletter opt-in, reviews, referrals, verified custom actions, and metafield conditions. Each rule can carry a schedule, customer eligibility, frequency cap, and a versioned reward definition.

Only actions Sellerlane can verify should be described as completed actions. A social-network URL open can be rewarded as a social visit/click; it must not be labelled a verified follow unless the network provides a trusted confirmation callback.

Review earns must be rating-neutral. Verification, text/photo/video content, and one-per-order/customer limits are valid gates; positive sentiment or a minimum rating above the universal 1-star floor is not. See Review requests and rewards.

For media rules, “photo” or “video” means at least one unhidden object with a persisted Clean verdict, committed canonical copy, edge publication marker, and Public ready timestamp. The buyer’s attachment window must be closed and every attached object must be terminal before the qualification generation is frozen. Pending, rejected, scan-failed, clean-but-not-public-ready, and hidden objects do not qualify. Base review points and the optional media bonus are posted as separate idempotent lots, so removing the last qualifying media object reverses only unused media-bonus value while the base review earn remains.

This loyalty earn is configured independently from the review-incentive rules under Reviews. The review-incentive engine chooses exactly one richest matching review_reward_rules payout (video, then photo, then text/any); multiple review reward tiers never stack. Loyalty base and media-bonus lots do stack with each other and may coexist with a discount or store-credit review incentive. If the selected review incentive is also points, the loyalty rule owns that review’s points award and the duplicate incentive-points mint is suppressed. Configure both systems only when that combined policy is the merchant’s intended offer.

The later “add a photo or video” reminder is not a second earning opportunity. Its seven-day upload window begins only after qualification is frozen, and those objects are permanently excluded from the loyalty media-bonus predicate. They still require normal scanning and approval before display.

Tiers and campaigns

Tiers can qualify members by lifetime points, eligible orders, or spend and can apply an earn multiplier and birthday points. Tier history is versioned so an account has one current membership while previous memberships remain auditable.

Timed campaigns can add a multiplier or flat bonus and can scope eligibility by product, collection, segment, or tier. Overlapping campaigns follow the published campaign combination rule; the resulting points are posted once with the winning campaign/rule snapshot.

Caution

Tier names, thresholds, earn multipliers, and birthday points are executable benefits. Sellerlane does not promise automatic tags, free shipping, entry discounts, or arbitrary text perks merely because they were written into tier copy. Create those as a supported redemption or campaign rule instead.

Redeem points

Published redemption rules define the exact exchange:

• points price (fixed, or a permitted variable range);
• supported reward type and value: fixed-amount discount, percentage discount, or free shipping;
• online/POS channels;
• customer tag or tier gates;
• minimum purchase, product/collection/country scope, expiry, and frequency limits;
• explicit product/order/shipping discount combination flags.

A redemption reserves points before issuing/applying the benefit. Completion consumes the reservation exactly once; cancellation releases it. Loyalty free-product, gift-card, and store-credit redemption definitions currently fail typed validation and cannot be published. Store credit issued by the separate referral or review-reward engines creates one linked monetary ledger artifact; it is not a second points balance.

The admin only exposes reward kinds with a complete issuer and reversal path. Unsupported catalog definitions cannot be activated as customer-facing promises.

Refunds and clawbacks

For purchase points, the reversal basis is the refunded or canceled eligible merchandise basis, not the entire gateway refund when that refund also includes tax or shipping.

If the member still has the affected points, the reversal consumes them. If the member already spent them, the unrecovered balance records the debt and future earnings repay it before becoming available. This preserves the original ledger and prevents a refund from manufacturing value.

Customer referrals

A referral moves through:

attributed → qualified → held → rewarded, or becomes disqualified.

1. The advocate shares their signed code/link.
2. Sellerlane persists the claim on the referred cart so asynchronous gateway completion cannot lose it.
3. The referred customer and qualifying paid order must satisfy the snapshotted minimum order, new-customer, expiry, and program limits.
4. The friend discount and advocate reward are created according to their own configured rules.
5. The advocate reward waits through the configured review/return hold and any required fulfillment milestone.
6. A successful release creates store credit or a discount-code award exactly once. A later disqualifying refund/cancellation can claw it back.

Percentage advocate rewards are calculated from the snapshotted eligible order basis and rounded to a whole minor unit. Store-credit referral rewards are fixed money amounts. The award, qualifying order, currency, rule snapshot, and linked credit lot/discount remain connected for audit.

Referral fraud signals

Sellerlane separates deterministic invalidity from uncertain evidence:

• the same customer, shared verified contact identity, an invalid code, or another deterministic self-referral rule is blocked before an advocate award can be issued;
• an exact shipping-address match to the advocate’s prior order, a persistent first-party visitor/device token shared by multiple referred customers, a locally identified disposable-email domain, or network velocity creates a merchant-review hold;
• network velocity currently means at least three distinct referred customers on the same hashed IP-address and user-agent pair inside the immutable 24-hour window ending at qualification time.

Every input is interpreted at the qualification anchor. The disposable-domain boolean is snapshotted when attribution is accepted, not recomputed from the customer’s current email. Address comparison uses only non-test, non-canceled advocate orders that were paid or partially refunded and whose order/address rows existed by the anchor. Device and network populations use signup events whose occurrence and ingestion timestamps are no later than the anchor. The complete privacy-minimized evidence result is then stored on the evaluation row with a SHA-256 fingerprint. The database prevents later changes to the anchor, snapshot, or fingerprint.

The case stores privacy-minimized summaries, counts, source classes, and the window—not raw addresses, IP addresses, user agents, or visitor tokens. These are first-party observations. Sellerlane does not claim an external provider risk score, device graph, proxy/VPN verdict, or email-reputation verdict unless that source is explicitly labelled providerDependent in a future integration.

A signal is not proof of fraud. Shared households, workplaces, schools, networks, and devices are normal false-positive cases. The queue therefore shows evidence as triage and requires an authorized operator to record a reason for approve, reject, or override.

Evaluation failure and retry

Risk evaluation does not decide whether the referred customer’s already-paid order was paid. Sellerlane captures the complete anchored evidence snapshot once, stores it durably, and then evaluates only that stored snapshot inside a database savepoint. If evaluation or case persistence fails after capture, Sellerlane rolls back only that attempt, commits the paid order/referral qualification, and retains:

1. a pending, non-spendable advocate award;
2. an evaluation_pending technical hold; and
3. a durable idempotent retry row containing the immutable snapshot.

The periodic evaluator uses persisted exponential backoff and reads the stored snapshot; it never queries the current customer, address, order, device, or network population. A successful clean retry removes the technical placeholder and lets the normal award issuer continue. A retry whose snapshot contains evidence replaces the placeholder with a real merchant-review case. evaluation_pending is not merchant evidence and cannot be approved or rejected from the UI.

If the source snapshot itself cannot be captured, reconstructing it later would not be an honest as-of query because email and order addresses can change. The award therefore enters evaluation_capture_failed: a fail-closed, non-spendable technical state that is excluded from automated evaluation and requires operational repair/replay from an authoritative source. It is not a fraud verdict and merchants cannot approve around it.

The issuer never runs evidence queries again. It consumes the completed durable result, so a duplicate payment webhook or a later worker clock cannot change the risk window or roll the paid order back.

Decision and financial effect

Each decision is bound to the exact SHA-256 evidence fingerprint displayed to the operator. A changed signal, count, summary, or window changes the fingerprint and invalidates the stale action. In the normal path, the immutable evaluation snapshot prevents those fields from drifting between retry and decision.

Decision	Award effect
Approve	Removes the fraud hold. A pending award issues only if fulfillment, return-hold, cap, currency, and order-eligibility rules are also satisfied. If an operational race exposed a case after issuance, approval preserves the issued economics; observing evidence alone never reverses value.
Reject	This is the only fraud-review decision that cancels or claws back value. It cancels a pending award; for an issued award, Sellerlane disables an unused discount or reverses the unspent store-credit lot. Already used value is preserved in history and requires an explicit audited recovery/manual adjustment rather than a fabricated reversal.
Override reject	Applies the same rejection/clawback rules to a previously approved case.
Override approve	Restores a false-positive award only when it was canceled before issuance. An issued-then-rejected reward cannot be silently re-issued; use an audited manual adjustment.

Idempotency keys make client retries replay the one recorded transition and financial effect. Audit history records the prior/new status, action, reason, operator, evidence fingerprint, and timestamp. Viewing cases requires customer access; actions require Manage customers, the same authority used for store-credit value changes.

Online, customer accounts, and POS

• Customer accounts show pending, available, reserved, expiring, lifetime, and tier state.
• POS resolves the same loyalty account using its unguessable member code/QR and posts to the same ledger.
• Channel eligibility is explicit per redemption. A POS redemption is not silently treated as an online discount, and an online order does not invent a POS location.
• Referral attribution is customer/order based; ordinary in-store traffic does not receive an online referral merely because an advocate shopped earlier.

Liability and operational reporting

Monitor, by currency and period:

• points issued, pending, vested, reserved, redeemed, expired, reversed, and unrecovered;
• monetary value represented by the configured points conversion, labelled as an estimate rather than cash;
• store credit and gift cards issued, redeemed, expired, reversed, and outstanding;
• referral awards pending, held, issued, disqualified, expired, and clawed back;
• review reward artifacts issued, used, expired, and revoked.

Never add points units to money. A points liability estimate and a monetary store-credit liability are separate measures.

Invariants

• available points + reserved points never exceed vested, unexpired lot value;
• every redemption allocation sums to the redemption’s points cost;
• an earn source/rule version produces at most one award for the same idempotency key;
• award reversal never exceeds the awarded amount;
• one referred customer has at most one accepted advocate attribution per program scope;
• friend and advocate amounts use the snapshotted currency and rule;
• issued referral/review store-credit rewards link to exactly one monetary artifact;
• a pending or held award is never reported as spendable.

Related guides

Store credit

Understand monetary reward lots in Store credit.

Discounts

Configure eligibility and combinations in Discounts.

Review rewards

Collect policy-safe reviews in Review requests and rewards.

Analytics definitions

Measure the systems consistently in Analytics definitions.