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#

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.