Referral integration reference

The referral guide covers campaign and program setup, customer identity, stable advocate codes, conversion timing, and reward delivery. Its loyalty-points example shows how a referral reward credits a membership in a separate loyalty program.

To show a customer’s vouchers, use vouchers.list({ customerId }). To find which of those codes apply to a cart, use qualification:

const offers = await offerkit.vouchers.qualify({
  customerId: customer.id,
  order: { amount: 5000, currency: "USD", items: [] },
  filters: { includeSkipped: true },
});

Qualification may create a customer if you instead supply an unknown external ID. Use a prior customer upsert when profile data or assignment matters. Validation of one known voucher returns valid, not ok, and assigned vouchers require customer context.

API conventions list outcome fields and error codes. Retries and recovery explains replay guarantees and what to inspect after a failed conversion.