Referral rewards

Reward a referral after your application establishes attribution and qualification.

Use Slices after your backend decides a referral qualifies. The integration does not need a Slices-specific referral engine: it submits the exact allocation your program already calculated.

Define the qualifying moment#

Decide what makes the referral eligible: for example, an invited customer completing an approved activity rather than merely entering an email address. Your application owns attribution, duplicate-person controls, self-referral policy, and any hold period.

Do not let a referral-link click or browser-submitted verified flag authorize a payout.

Persist the allocation#

When qualification succeeds, store the recipient's authorized wallet, the exact base-unit amount, your calculation version, and a stable event identity in your own database. Send from a durable worker or outbox so retries reuse the original decision.

const reward = await slices.rewards.issue({
  campaignId: approvedCampaignId,
  recipient: { walletAddress: referrerWallet },
  amountBaseUnits: calculatedReferrerAmount,
  event: {
    id: `${referralId}:referrer`,
    type: "referral.qualified",
  },
  idempotencyKey: `referral:${referralId}:referrer`,
});

Initialize slices using Install. Variables above come from your trusted backend; calculatedReferrerAmount is a positive integer string. Choose identifier formats that fit the documented event and key limits.

Rewarding both participants#

Submit two deliberate instructions with different event identities, such as referral_0182:referrer and referral_0182:invitee. Each has its own wallet, amount, and idempotency key.

There is no atomic multi-recipient grant endpoint. If one allocation succeeds and the other fails, preserve the successful reward ID and retry or investigate only the outstanding instruction. Do not reissue both with fresh keys.

Show progress#

Store each Slices reward ID against the referral record and poll for state. Tell users the reward is recorded after acceptance, awaiting approval while it is queued, on its way once it is sent, and confirmed only when it is delivered. Approval and sending may happen later than acceptance; show the current status rather than a promise.

Reversals#

A reward your operator has not yet approved can be cancelled. Once approved, a disqualified referral does not automatically reverse its allocation. Define your referral hold period and correction policy before submitting rewards that might need reversal.

A corrected reward needs a reviewed new event identity; a cancelled tuple remains deduplicated.

What this does not add#

This integration does not generate referral links, attribute clicks, create recipient wallets, or identify unique people. It uses the same partner payout endpoint as every other partner-qualified use case.

Related: Events and qualification, Idempotency, and Track rewards.