Referrals#
A referral links an Advocate’s offer to a Friend’s purchase or event. Talkable creates the referral when it matches the purchase or event to the Advocate, and checks it against your fraud rules. Talkable approves pending referrals when your approval period ends, and issues the rewards that qualify.
If you run your own approval process, your backend can also approve or void a
referral with the Referrals API while its status is pending or
flagged.
Referral statuses#
Status |
Meaning |
|---|---|
|
Talkable is processing the referral |
|
The referral waits for the approval period to end |
|
A fraud rule flagged the referral for review |
|
The referral is approved, and Talkable issues the rewards that qualify. Final status |
|
A fraud rule blocked the referral |
|
The referral is canceled, and its rewards are voided. Final status |
Set the approval period in Fraud Settings under Pending referrals. See Referrals Approval.
Approve or void a referral#
Call PUT /api/v2/origins/{origin_slug}/referral with the
API key. For origin_slug, use the Friend’s order number. For an event, use
its category and number, such as third_payment:4512:
{
"site_slug": "example-site",
"data": {
"status": "voided"
}
}
Send approved to issue the rewards that qualify, or voided to cancel the
referral.
Talkable creates referrals in the background. If a call right after the
purchase returns 400 with No referral found for given origin. or
Status cannot be transitioned from 'in_progress', retry it later.
Example use cases#
Approve early. Send approved when your system confirms the Friend’s
order, for example when it ships, before the approval period ends.
Void after your review. Send voided when your team rejects a
pending or flagged referral.
Returns. Report the refund with the Origins API. A
full refund voids a pending or flagged referral.
Note
To issue rewards only after your API approval, ask your Customer Success Manager.