---
title: "Referral Completed (2.0)"
method: POST
path: "yotpo/referral/completed"
---

# Referral Completed (2.0)

`POST yotpo/referral/completed` (webhook)

Sent when a customer refers a friend who meets your referral program's requirements. Use it to thank the customer for the referral.

To receive it, add `yotpo/referral/completed` to `events` when you [create a filter](ref:create-filter), then [create a store subscription](ref:create-subscription) for each store that installed your app. Yotpo sends the event to your target URL as a `POST` with this JSON body.

For Shopify stores that joined Yotpo Loyalty & Referrals after August 2024. Stores that joined earlier get [Referral Completed](ref:referral-completed) (`swell/referral/completed`).

## Headers

- `X-Yotpo-Webhooks-Event-Type` string, required
- `X-Yotpo-Webhooks-Tenant-Type` string, required
- `X-Yotpo-Webhooks-Tenant-Id` string, required
- `WebhookMessageId` string, required
- `WebhookMessageIdPerTarget` string, required

## Payload

- object
  - `topic` string: The event name, `yotpo/referral/completed`.
  - `name` string: The display name of the event.
  - `website_url` string: Your store's website URL.
  - `store_name` string: Your store's name.
  - `perk` object: The reward record.
    - `id` integer: The ID of the reward record.
    - `campaign_id` integer, nullable: The ID of the campaign (earning rule) that gave the reward, or `null`.
    - `merchant_id` integer: Your Yotpo Loyalty merchant ID.
    - `customer_id` integer: The customer's Yotpo Loyalty ID.
    - `reward_points` integer, nullable: The number of points the referring customer earned for a successful referral.
    - `completed` boolean: Whether the customer completed the action that earns the reward.
    - `completed_at` string, date-time, nullable: When the action was completed, or `null`.
    - `awarded` boolean: Whether the reward was given to the customer.
    - `awarded_at` string, date-time, nullable: When the reward was given, or `null`.
    - `pending` boolean: Whether the reward is pending and not yet available.
    - `reversed` boolean: Whether the reward was taken back, for example after a refund.
    - `reversed_at` string, date-time, nullable: When the reward was reversed, or `null`.
    - `expired` boolean: Whether the reward has expired.
    - `expired_at` string, date-time, nullable: When the reward expired, or `null`.
    - `expires_at` string, date-time, nullable: When the reward will expire, or `null`.
    - `redemption_option_id` integer, nullable: The ID of the reward (redemption option) given, or `null` when the reward is points.
    - `history_title` string: The description shown in the customer's points history.
    - `created_at` string, date-time: When the reward record was created.
    - `redemption_option` object: The reward given.
      - `id` integer: The reward (redemption option) ID.
      - `cost_text` string, nullable: The points cost as display text, for example `500 points`.
      - `amount` integer, nullable: The points the reward costs. `0` for `variable` rewards, where the customer chooses how many points to redeem.
      - `applies_to_product_type` string, nullable: Which products the reward applies to, for example `ALL`.
      - `duration` string, nullable: How long the reward lasts, for example `single_use`.
      - `type` string: The reward type, for example `Coupon`.
      - `discount_amount_cents` integer, nullable: The discount in cents for fixed-amount rewards.
      - `discount_rate_cents` integer, nullable: For `variable` rewards, the discount in cents for each point redeemed.
      - `discount_percentage` integer, nullable: The discount percentage for percentage rewards. `null` or `0` for other types.
      - `discount_type` string, nullable: How the discount works, for example `fixed_amount`, `percentage`, `variable`, `custom_reward` or `donation`.
      - `discount_value_cents` integer, nullable: The discount value in cents, or `null`.
      - `name` string: The name of the discount code the referring customer earned for a successful referral.
      - `description` string, nullable: The reward description shown to customers.
      - `unrendered_name` string, nullable: The reward name as set in the admin, before placeholders are filled in.
      - `unrendered_description` string, nullable: The reward description as set in the admin, before placeholders are filled in.
      - `cart_greater_than` string, nullable: Minimum cart subtotal for the reward to apply, in store currency units. `"0"` means no minimum.
      - `discount_with_currency` string, nullable: The discount formatted in your store currency, for example `$10`.
    - `redemption` object: The coupon given with this reward.
      - `id` integer: The redemption ID.
      - `reward_text` string: The discount code the referring customer earned for a successful referral.
      - `approved` boolean: Whether the redemption is approved.
      - `approved_at` string, date-time, nullable: When the redemption was approved.
      - `is_admin` boolean: `true` when the redemption was made from the Yotpo Loyalty admin.
      - `is_pos` boolean: `true` when the redemption was made at a point of sale.
      - `at_checkout` boolean: `true` when points are deducted only when the coupon is used at checkout.
      - `amount` string, nullable: The points spent, or `null` when the reward was given rather than bought with points.
      - `token` string: An internal reference for the redemption.
      - `third_party_id` string, nullable: The discount's ID in your e-commerce platform, or `null` for codes you uploaded.
      - `third_party_rule_id` string, nullable: The ID of the discount rule in your e-commerce platform, or `null` for codes you uploaded.
      - `code` string, nullable: The coupon code.
  - `referral_code` object: The referring customer's referral code and its sharing stats.
    - `code` string: The referral code.
    - `customer_id` integer: The referring customer's Yotpo Loyalty ID.
    - `total_shares` integer: Total shares.
    - `email_shares` integer: Shares by email.
    - `sms_shares` integer: Shares by SMS.
    - `whatsapp_shares` integer: Shares on WhatsApp.
    - `copy_link_shares` integer: Times the referral link was copied.
    - `personal_email_shares` integer: Shares from a personal email account.
    - `links_clicked_from_email` integer: Link clicks from email.
    - `links_clicked_from_sms` integer: Link clicks from SMS.
    - `links_clicked_from_whatsapp` integer: Link clicks from WhatsApp.
    - `links_clicked_from_personal_email` integer: Link clicks from a personal email account.
    - `links_clicked_from_copy_link` integer: Clicks on the copied link.
    - `friends_orders` integer: Orders placed by referred friends.
    - `friends_amount_spent_cents` integer: Total spend by referred friends, in cents.
    - `friends_average_amount_cents` integer: Average order value of referred friends, in cents.
    - `expired` boolean: Whether the code has expired.
    - `customer` object: The referring customer, or `null`. Includes more account details than are listed here.
      - `total_spend_cents` integer: Total spend recorded for the customer, in cents.
      - `total_purchases` integer: Number of purchases recorded for the customer.
      - `perks_redeemed` integer: Number of rewards the customer has redeemed.
      - `last_purchase_at` string, date-time, nullable: When the customer's last recorded purchase was made, or `null`.
      - `first_name` string, nullable: The customer's first name.
      - `last_name` string, nullable: The customer's last name.
      - `is_member` boolean: Whether the customer is a loyalty program member.
      - `accepts_marketing` boolean, nullable: Whether the customer accepts marketing, or `null` when unknown.
      - `email` string: The customer's email address.
      - `points_balance` integer: The points the customer can spend now, after this event.
      - `points_earned` integer: Total points the customer has earned over their lifetime.
      - `last_seen_at` string, date-time, nullable: When Yotpo Loyalty last recorded activity for the customer, or `null`.
      - `thirty_party_id` string, nullable: Legacy misspelled duplicate of `third_party_id`. Use `third_party_id`.
      - `third_party_id` string, nullable: The customer's ID in your e-commerce platform.
      - `referral_link` string: The customer's personal referral link.
      - `referral_discount_code` string, nullable: The discount code the customer received for being referred, or `null`.
      - `is_opt_in` boolean: Whether the customer is opted in to the loyalty program.
      - `loyalty_opt_in_date` string: The date the customer opted in to the loyalty program, or `null` when they have not.
      - `has_store_account` boolean: Whether the customer has an account in your store.
      - `credit_balance` string: Store-credit value of the points balance, formatted in your store currency, for example `$0`.
      - `credit_balance_in_customer_currency` string: Store-credit value of the points balance, formatted in the customer's currency.
      - `is_affiliate` boolean: Whether the customer is an affiliate.
      - `points_expire_at` string, date-time, nullable: When the customer's points expire, or `null` when they never expire. Follows your **Points expiration policy**: **Last Activity** (counted from the customer's last activity), **Date Earned** (the next upcoming expiration across the customer's point batches) or **Never expire** (`null`).
      - `referred_by_customer` string, nullable: The email address of the customer who referred this customer, or `null` when there is no referrer.
      - `vip_tier_name` string, nullable: The customer's current VIP tier, or `null` when they aren't in one.
      - `vip_tier_ends_at` string, date, nullable: When the customer's current VIP tier ends, or `null` when it doesn't expire.
      - `birthday_month` integer, nullable: The customer's birthday month (1 to 12), or `null` when not set.
      - `birth_day` integer, nullable: The day of the month of the customer's birthday, or `null` when not set.
      - `birth_year` string, nullable: The customer's birth year, or `null` when not set.
      - `anniversary_month` integer, nullable: The customer's anniversary month (1 to 12), or `null` when not set.
      - `anniversary_day` integer, nullable: The day of the month of the customer's anniversary, or `null` when not set.
      - `anniversary_year` string, nullable: The year of the customer's anniversary, or `null` when not set.
    - `completed_referral_customers` object[]: An array of friends the referring customer has referred so far.
      - `email` string: The friend's email address.
      - `first_name` string: The friend's first name.
      - `last_name` string: The friend's last name.
      - `reward_type` string: The kind of reward given for the referral, for example `REWARD_OPTION`.
      - `referral_status` string: The referral status, for example `COMPLETED`.
      - `last_seen_at` string, date-time: When Yotpo Loyalty last recorded activity for the friend.
    - `email` string: The referring customer's email address.
    - `unique_clicks` integer: Unique link clicks.
    - `total_clicks` integer: Total link clicks.
  - `friend_referral_code` object: The referred friend's own referral code and stats.
    - `code` string: The referral code.
    - `customer_id` integer: The referring customer's Yotpo Loyalty ID.
    - `total_shares` integer: Total shares.
    - `email_shares` integer: Shares by email.
    - `sms_shares` integer: Shares by SMS.
    - `whatsapp_shares` integer: Shares on WhatsApp.
    - `copy_link_shares` integer: Times the referral link was copied.
    - `personal_email_shares` integer: Shares from a personal email account.
    - `links_clicked_from_email` integer: Link clicks from email.
    - `links_clicked_from_sms` integer: Link clicks from SMS.
    - `links_clicked_from_whatsapp` integer: Link clicks from WhatsApp.
    - `links_clicked_from_personal_email` integer: Link clicks from a personal email account.
    - `links_clicked_from_copy_link` integer: Clicks on the copied link.
    - `friends_orders` integer: Orders placed by referred friends.
    - `friends_amount_spent_cents` integer: Total spend by referred friends, in cents.
    - `friends_average_amount_cents` integer: Average order value of referred friends, in cents.
    - `expired` boolean: Whether the code has expired.
    - `customer` object, nullable: The referring customer, or `null`. Includes more account details than are listed here.
    - `completed_referral_customers` object[]: The friends who completed a referral with this code.
    - `email` string: The referring customer's email address.
    - `unique_clicks` integer: Unique link clicks.
    - `total_clicks` integer: Total link clicks.
  - `email` string: The email address of the customer who made the referral.
  - `friend` object: The friend who was referred.
    - `total_spend_cents` integer: Total spend recorded for the customer, in cents.
    - `total_purchases` integer: Number of purchases recorded for the customer.
    - `perks_redeemed` integer: Number of rewards the customer has redeemed.
    - `last_purchase_at` string, date-time, nullable: When the customer's last recorded purchase was made, or `null`.
    - `first_name` string, nullable: The customer's first name.
    - `last_name` string, nullable: The customer's last name.
    - `is_member` boolean: Whether the customer is a loyalty program member.
    - `accepts_marketing` boolean, nullable: Whether the customer accepts marketing, or `null` when unknown.
    - `email` string: The customer's email address.
    - `points_balance` integer: The points the customer can spend now, after this event.
    - `points_earned` integer: Total points the customer has earned over their lifetime.
    - `last_seen_at` string, date-time, nullable: When Yotpo Loyalty last recorded activity for the customer, or `null`.
    - `thirty_party_id` string, nullable: Legacy misspelled duplicate of `third_party_id`. Use `third_party_id`.
    - `third_party_id` string, nullable: The customer's ID in your e-commerce platform.
    - `referral_link` string: The customer's personal referral link.
    - `referral_discount_code` string, nullable: The discount code the customer received for being referred, or `null`.
    - `is_opt_in` boolean: Whether the customer is opted in to the loyalty program.
    - `loyalty_opt_in_date` string: The date the customer opted in to the loyalty program, or `null` when they have not.
    - `has_store_account` boolean: Whether the customer has an account in your store.
    - `credit_balance` string: Store-credit value of the points balance, formatted in your store currency, for example `$0`.
    - `credit_balance_in_customer_currency` string: Store-credit value of the points balance, formatted in the customer's currency.
    - `is_affiliate` boolean: Whether the customer is an affiliate.
    - `points_expire_at` string, date-time, nullable: When the customer's points expire, or `null` when they never expire. Follows your **Points expiration policy**: **Last Activity** (counted from the customer's last activity), **Date Earned** (the next upcoming expiration across the customer's point batches) or **Never expire** (`null`).
    - `referred_by_customer` string, nullable: The email address of the customer who referred this customer, or `null` when there is no referrer.
  - `published_at` string, date-time: When Yotpo sent the event.

## Acknowledgement `200`

Return any 2xx status quickly to acknowledge the event. Without one, Yotpo retries at least 10 times with exponential backoff.

---

[API](https://skmtc.dev/yotpo/apis/app-developer-api.md) - [All operations](https://skmtc.dev/yotpo/apis/app-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/yotpo/apis/app-developer-api/revisions/5bcae8239b6e?raw)