Skip to content

Referrals ​

TiruPay provides a built-in friend-referral program. Every customer automatically gets a personal referral code, which can be redeemed by a new customer at checkout - just like a coupon, through the same apply/unapply endpoint. Once the referred customer's cumulative spend crosses a service-configured tier threshold (and an optional chargeback-safety delay has passed), the referrer - and optionally the referred customer too - is credited a fixed amount of Credit Balance.

Example

Customer A shares their referral code with Customer B. B enters it on their first order. Once B's cumulative spend reaches 40 €, A is credited 10 € and B is credited 5 € - both as Credit Balance credit, paid out 14 days later (the service's configured chargeback-safety delay).

Concepts ​

ReferralPolicy ​

One per service (optional - a service that never configures one simply has no referral program). It has:

  • is_active - whether the program currently accepts new redemptions
  • payout_delay_days - optional chargeback-safety window between a tier being crossed and the reward actually being credited. None/0 means immediate payout.
  • convert_referrer_reward - if true, the referrer's payout is converted at payout execution time from the tier's fixed currency into the referrer's own currency (derived from their country), using the live FX rate. If false (default), the referrer is paid in the tier's fixed currency unconverted - see Referrer Currency Conversion.
  • first_order_only - if true, a referral code can only be applied while the referred customer has no other order at this service in a completed-payment state yet - see First Order Only.
  • a tier ladder - one or more ReferralRewardTier rows

ReferralRewardTier ​

A single reward step within a policy, identified by tier_order (1-10). Each tier defines:

  • referrer_reward_amount / referrer_reward_currency_code - a single fixed amount, in one currency the service chooses, credited to the referrer when the tier is crossed - regardless of which currency actually triggered it. The service deliberately carries any FX risk here rather than needing to define a separate referrer amount per currency. May be 0 if the tier should only reward the referee.
  • one or more ReferralTierThreshold rows - see below.

A tier must reward someone

A tier is rejected if it would reward neither side - referrer_reward_amount and every threshold's referee_reward_amount are all 0.

ReferralTierThreshold ​

A tier's per-currency configuration. Since spend is tracked strictly per-currency, a tier needs one threshold row per currency it should be reachable in:

  • currency_code - the currency this threshold applies to
  • cumulative_spend_threshold - how much the referred customer must have spent, in this currency, to cross the tier. May be 0 - the tier is then crossed by the redemption alone, with no minimum spend required.
  • referee_reward_amount - the amount credited to the referred customer, paid in this same currency, when the tier is crossed via this currency. May be 0 if the tier should only reward the referrer.

Single-currency services

A service that only operates in one currency simply configures one threshold per tier. The multi-currency structure only adds complexity when you actually need it.

ReferralCode ​

A customer's personal, auto-generated code (format RC + 12 characters, e.g. RC7K9M2XQ4TBHW), created lazily on first request. One code per customer per service. Redeemed case-insensitively; the readability dashes some frontends may render (RC-7K9M-2XQ4-TBHW) are optional and stripped before matching.

A code can be deactivated (is_active = false) to block a single customer's code - e.g. for fraud - without disabling the whole program.

AppliedReferralCode ​

Created when a code is entered on a DRAFT order - mirrors how Applied Coupons work. Applying a different code to the same order replaces the previous one. A customer may have the same or different referral codes applied to several of their own open orders at once; only one of them can ever end up winning a reward (see below).

Its status is applied once a customer is attached to the order, or pending if it was entered on a customer-less draft order and is still waiting for one - see Applying a Referral Code Before a Customer Is Known.

ReferralRewardProgress ​

Marks the winning redemption: created exactly once, for the first of a customer's orders (carrying an AppliedReferralCode) to reach a completed state. All tier/payout tracking hangs off this row.

ReferralPayout ​

One row per tier crossing per beneficiary (REFERRER or REFEREE). Status is PENDING → PAID (or CANCELLED if the threshold is no longer met by the time the payout would execute). A tier that only rewards one side simply never gets a row for the other.

Redeeming a Code ​

Referral codes are redeemed through the same endpoint as coupons:

POST /orders/{order_id}/apply/{code}

TiruPay automatically detects whether the code is a coupon or a referral code:

  1. It first checks whether a matching Coupon exists for the order's service - coupons are freely configurable per service, so this authoritative lookup always wins.
  2. Otherwise, a code starting with RC (case-insensitive) is treated as a referral code.

The response includes code_type ("coupon" or "referral") alongside the order, so a frontend knows which kind of code was applied.

Removing a code requires the type explicitly, since a coupon and a referral code can be applied to the same order independently:

DELETE /orders/{order_id}/unapply/{code_type}

No Order Discount

Unlike coupons, applying a referral code never changes the order total. Referral rewards are Credit Balance credits only, for both sides, resolved after the order is paid - not an order-time discount.

Applying a Referral Code Before a Customer Is Known ​

Most of the applicability checks below (self-referral, already redeemed, first_order_only) need a referred customer to evaluate. A draft order created without one yet can still have a referral code entered on it through the same POST /orders/{order_id}/apply/{code} endpoint - TiruPay queues it instead of rejecting it outright.

  • Only the checks that don't depend on a customer run at this point: the code exists and belongs to the order's service, is active, the service's referral program is active, and a tier threshold exists for the order's currency.
  • The queued AppliedReferralCode has status: "pending" and no referred_customer_id yet.
  • It can be unapplied at this stage the same way as an already-applied one - DELETE /orders/{order_id}/unapply/referral.

Once PATCH /orders/{id}/customer links a customer to the order, TiruPay automatically re-checks the queued code with the now-known customer:

  • If it's still applicable, it becomes status: "applied" - exactly as if it had been entered after the customer was already linked.
  • If not (e.g. the linked customer turns out to be the code's own referrer, or has already redeemed a code for this service), it is silently dropped. Linking the customer still succeeds either way - a stale referral code never blocks it.

Coupons Don't Need This

A coupon has no customer-dependent applicability rules, so it applies immediately on a customer-less order - there's no pending state for coupons.

Winning the Redemption ​

Because AppliedReferralCode rows are created immediately at apply-time - independent of whether the order ever completes - a customer can have codes applied to several open orders simultaneously. Only one of them can ever count:

  • When an order carrying an AppliedReferralCode completes, TiruPay checks whether this (service, referred customer) pair has already won a redemption elsewhere.
  • If not, this order wins: a ReferralRewardProgress row is created, and tiers are evaluated immediately for whatever the customer has spent so far.
  • If two of a customer's orders race to complete around the same time, the first one processed wins - deterministically, never both, never neither.

Once Per Customer, Per Service ​

A referred customer may only ever have one winning redemption per service - enforced across all of their orders, forever:

  • Once any tier payout for a customer's winning redemption has reached PAID, the slot is permanently closed - even if that winning order is later refunded or cancelled. No reward is ever clawed back, but no new redemption can take its place either.
  • Before any payout has reached PAID, fully reversing the winning order does reopen the slot - one of the customer's other open orders (if any still carry a different or the same referral code) can then win on its own next completion.

First Order Only ​

If a policy's first_order_only is enabled, applying a referral code is rejected outright once the referred customer already has any order at this service in a completed-payment state (COMPLETED_OUTSTANDING, COMPLETED_FINALIZED, PARTIALLY_REFUNDED, or DUNNING) - regardless of whether that order carried a referral code at all.

DRAFT and PENDING orders never block - they haven't reached a completed payment yet. Fully reversed orders (REFUNDED, REVOKED, CANCELLED, WITHDRAWN) don't block either - as far as this check is concerned, they never happened.

Why DUNNING blocks too

A DUNNING order already reached a completed payment state before its renewal failed - it's a returning customer with a payment problem, not a prospective new one.

Tier Crossing & Cumulative Spend ​

Cumulative spend is the unconditional sum of a customer's completed orders - subscription renewals and one-time purchases alike - tracked strictly per-currency, and computed at the level of individual order positions, not whole orders. An order placed in a different currency never contributes, since TiruPay never assumes an FX rate. A partially refunded order still counts, but only for its post-refund net amount.

Excluding an article category or balance type from spend

An article category's excluded_from_referral_spend flag removes every position for articles in that category - and their extensions, which always inherit their parent article's category - from the spend calculation entirely. Useful for e.g. one-time setup fees or add-ons that shouldn't count toward a referral tier.

The same flag exists on balance types: a PAYG position's excluded_from_referral_spend is resolved through its balance's balance type, not through an article. Unlike the article category flag, this one defaults to true - PAYG usage is typically incidental consumption (e.g. API calls) rather than the kind of deliberate purchase a referral tier is meant to reward, so a service has to opt a balance type in rather than out.

If an order is refunded, a position-specific refund only reduces that position's contribution; a full-order refund (not tied to one position) is distributed across all of the order's positions proportionally to their share of the order's total - excluded or not.

Each time the referred customer's order completes, every tier is re-evaluated:

  • For each currency any tier has a threshold configured in, spend is summed independently in that currency.
  • A tier is crossed via any of its configured currencies. The referrer is always paid the tier's single fixed amount in its fixed currency, regardless of which currency triggered the crossing. The referee is paid in whichever currency actually triggered it.
  • Crossing a tier creates a PENDING payout for each beneficiary whose reward for that tier is greater than zero.
  • Every tier is checked on every evaluation, not just the next one in line. If a single order pushes cumulative spend past several tiers' thresholds at once (e.g. a 100 € order when tiers sit at 40 € and 80 €), all of them are crossed and paid out in the same pass - not just the highest one.

Payout Execution ​

A daily background job finds PENDING payouts whose due_at (the crossing time plus the policy's payout_delay_days) has passed, re-verifies the threshold is still met, and credits the beneficiary's Credit Balance - recorded as a credit transaction with reference type REFERRAL.

If the threshold is no longer met by execution time (e.g. a refund arrived in between), the payout is cancelled instead - no balance credit happens.

Referrer Currency Conversion ​

By default, the referrer is credited in the tier's fixed referrer_reward_currency_code - unconverted, regardless of the referrer's own country. A referrer whose currency differs from every tier's currency ends up with a balance they may have no other use for (e.g. a Swiss referrer credited in EUR).

If the policy's convert_referrer_reward is enabled, the payout job instead converts the tier's fixed amount into the referrer's own currency (resolved from Customer.country_code -> Country.currency_code, falling back to EUR) at the live exchange rate, at the moment the payout executes. The tier's configured amount and currency are unaffected - they remain the audit trail of what was promised; only the amount actually credited (and the currency of that credit) reflects the conversion.

Example

A service configures a tier with referrer_reward_amount: 10.00, referrer_reward_currency_code: EUR, and enables conversion. A Swiss referrer (country currency CHF) crosses the tier - at payout time, 10 € is converted to CHF at the current rate (e.g. 9.50 CHF) and credited to their Credit Balance in CHF, not EUR.

This only ever applies to REFERRER payouts. The referee is always paid in whichever currency actually triggered their threshold - never converted.

Refunds ​

When an order is refunded, TiruPay re-checks every PENDING payout tied to the affected customer:

  • A referee payout is cancelled if spend in its specific triggering currency has dropped back below that tier's threshold.
  • A referrer payout is cancelled only if none of the tier's configured currency thresholds are met anymore.
  • An already-PAID payout is never retracted.

If the winning order itself is fully reversed and no payout for it has reached PAID yet, the redemption slot reopens (see Once Per Customer).

Good to know ​

One Code Per Customer Per Service

Every customer gets exactly one referral code per service, created automatically the first time it's requested.

Self-Referral Is Always Blocked

Unlike most other referral rules, self-referral cannot be configured - it is always rejected, independent of policy.

No Reward Clawback

Once a payout reaches PAID, it is never reversed - even if the underlying order is later refunded. The only consequence of a later refund is that the redemption slot may or may not reopen, depending on whether any payout was already paid.

Currency Coverage

If a service's policy has no threshold configured for an order's currency, the referral code is rejected outright when applied - it could never advance any tier for that order.

A user's own redemption list only exposes aggregated total_earned / pending_amount totals - never per-tier or per-payout detail.

Relationships ​

  • Orders - Referral codes are applied to orders the same way coupons are; winning is decided when the order completes. On a customer-less draft order, applying one queues it instead - see Applying a Referral Code Before a Customer Is Known.
  • Coupons - Both share the same apply/unapply endpoint; a coupon and a referral code can be applied to the same order independently.
  • Credit Balance - All referral rewards are credited as Credit Balance, with reference type REFERRAL.
  • Customers - Every customer has at most one referral code per service.
  • Services - The referral program, its tiers, and thresholds are all scoped to a service.
  • Background Jobs - A daily job executes due payouts.