Origins#
An origin is an action a person takes that you report to Talkable. Talkable uses origins to give Advocates their offers. When Talkable matches a Friend’s purchase or event to an Advocate, it creates a referral and checks which rewards qualify.
Use the Origins API for actions that happen on your backend, in your app, or off-site. On your website, the Post Purchase Script reports orders instead.
Origin types#
Affiliate Member — a person joins the referral program or opens your referral screen. Talkable returns their offer. Call POST /api/v2/origins/affiliate_member.
Purchase — a person places an order, with
order_numberandsubtotal. Call POST /api/v2/origins/purchase.Event — a person takes another action, with
event_categoryandevent_number. Call POST /api/v2/origins/event.
Send the person’s email with each origin, and the Friend’s visitor ID as
uuid when you have it. See
Referral program via API for the full flow.
A campaign rewards purchases by default. To reward an event, set the Advocate’s reward criterion Friend event category to the event’s category in the campaign.
Example use cases#
Subscription. To reward the Advocate after the Friend’s third monthly
payment, send an event when your billing system charges that payment, for
example with "event_category": "third_payment". Set Friend event
category to third_payment.
Off-site purchases and appointments. Report a store purchase as a purchase, and an in-person appointment as an event. Talkable matches the Friend by email or by the coupon they used.
Application approval. When you approve a Friend’s application, send an
event with a category such as application_approved. Set Friend event
category to the same category.
Refunds#
When an order is refunded, call
POST /api/v2/origins/{origin_slug}/refund. For
origin_slug, use the order number. For an event, use its category and
number, such as third_payment:4512.
A full refund voids a pending or flagged referral. A partial refund,
with refund_subtotal, records the amount and keeps the referral. An origin
can be refunded once.