---
title: "Referrals Configurations"
method: GET
path: "/api/v4.0/integrations/configurations/referrals"
---

# Referrals Configurations

`GET /api/v4.0/integrations/configurations/referrals`

This API retrieves the referral configuration, including customer and friend rewards, as well as metadata related to the events that trigger referral rewards.

## Headers

- `lang` string

## Response `200`

Referral settings retrieved successfully

- ReferralConfiguration
  - `referralMethod` string — This specifies who will receive the referral reward when a successful referral is made. Possible values: CustomerOnly (Only the customer making the referral will receive the reward. The referred friend will not receive any reward), CustomerAndFriend (Both the customer making the referral and the referred friend will receive rewards, encouraging mutual benefit).
  - `eventName` string — This describes the event that will trigger the referral reward. Example: if the eventName is set to place_order, the referral reward will be granted when the referred friend completes an order after using the referral link. Other events can also be configured to trigger the reward, depending on your system's setup.
  - `eventMetaData` object, nullable — Contains additional metadata about the event that triggers the referral.
    - `name` string, nullable — The name of the event metadata.
    - `operator` string, nullable — The operator used for event metadata (e.g., equals, greater_than).
    - `value` string, nullable — The value associated with the event metadata.
  - `friendReward` object, nullable — The reward details given to the referred friend as part of the referral program.
    - `score` number, nullable — The score awarded to the referred friend.
    - `point` number, nullable — The points awarded to the referred friend.
    - `coupon` object, nullable — A coupon object that is awarded to the referred friend.
      - `couponType` string, nullable — The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.
      - `discountValue` number, nullable — The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount.
      - `product` object, nullable
        - `productId` string, nullable — The unique identifier for the product.
        - `productName` string, nullable — The name of the product.
        - `variantId` string, nullable — The unique identifier for the product variant.
        - `variantName` string, nullable — The name of the product variant.
        - `productDisplayName` string, nullable — The display name associated with the product that configured on the dashboard based on required language.
      - `collections` object[], nullable — A list of collection IDs that the coupon can be applied to.
        - `collectionId` string, nullable — The unique identifier for the collection.
        - `collectionName` string, nullable — The name for the collection.
      - `group` object, nullable
        - `handle` string, nullable — A unique identifier used to reference the coupon group in the system.
        - `title` string, nullable — The title of the coupon group.
        - `url` string, nullable — The URL for the coupon group.
        - `iconPath` string, nullable — The path to the icon of the coupon group.
        - `description` string, nullable — A description of the coupon group.
        - `maxPerCustomer` number, nullable — The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.
        - `startDate` string, date-time, nullable — The date when the coupons within this coupon group will become active and valid for redemption.
        - `expiryDate` string, date-time, nullable — The date when the coupons within this coupon group will expire and no longer be valid for redemption.
        - `isAvailable` boolean, nullable — Indicates whether the coupon group is currently available.
        - `isActive` boolean, nullable — Indicates whether the coupon group is currently active.
      - `options` object, nullable
        - `name` string, nullable — The name of the reward rule configured on the dashboard based on required language.
        - `expiryAfter` number, nullable — The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.
        - `usageLimit` number, nullable — The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.
        - `capping` number, nullable — The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.
        - `minOrderValue` number, nullable — The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.
        - `codePrefix` string, nullable — The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".
        - `redeemInstructions` string, nullable — The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."
  - `customerReward` object, nullable — The reward details given to the customer as part of the referral program.
    - `score` number, nullable — The score awarded to the customer.
    - `point` number, nullable — The points awarded to the customer.
    - `coupon` object, nullable — A coupon object that is awarded to the customer.
      - `couponType` string, nullable — The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.
      - `discountValue` number, nullable — The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount.
      - `product` object, nullable
        - `productId` string, nullable — The unique identifier for the product.
        - `productName` string, nullable — The name of the product.
        - `variantId` string, nullable — The unique identifier for the product variant.
        - `variantName` string, nullable — The name of the product variant.
        - `productDisplayName` string, nullable — The display name associated with the product that configured on the dashboard based on required language.
      - `collections` object[], nullable — A list of collection IDs that the coupon can be applied to.
        - `collectionId` string, nullable — The unique identifier for the collection.
        - `collectionName` string, nullable — The name for the collection.
      - `group` object, nullable
        - `handle` string, nullable — A unique identifier used to reference the coupon group in the system.
        - `title` string, nullable — The title of the coupon group.
        - `url` string, nullable — The URL for the coupon group.
        - `iconPath` string, nullable — The path to the icon of the coupon group.
        - `description` string, nullable — A description of the coupon group.
        - `maxPerCustomer` number, nullable — The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.
        - `startDate` string, date-time, nullable — The date when the coupons within this coupon group will become active and valid for redemption.
        - `expiryDate` string, date-time, nullable — The date when the coupons within this coupon group will expire and no longer be valid for redemption.
        - `isAvailable` boolean, nullable — Indicates whether the coupon group is currently available.
        - `isActive` boolean, nullable — Indicates whether the coupon group is currently active.
      - `options` object, nullable
        - `name` string, nullable — The name of the reward rule configured on the dashboard based on required language.
        - `expiryAfter` number, nullable — The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.
        - `usageLimit` number, nullable — The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.
        - `capping` number, nullable — The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.
        - `minOrderValue` number, nullable — The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.
        - `codePrefix` string, nullable — The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".
        - `redeemInstructions` string, nullable — The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."
    - `extraReward` object, nullable — It contains all the details of the reward (like the friendReward Object) that will be awarded to the customer as a bonus on top of the regular reward for every X friend referred.
      - `forEvery` number, nullable — This defines the number of friends a customer needs to refer in order to earn the extraReward. For example, if the value of forEvery is set to 5, the customer will receive the extra reward for every 5 friends they successfully refer. This acts as a bonus on top of the regular reward, incentivizing more referrals.
      - `score` number, nullable — The score awarded as part of the extra reward.
      - `point` number, nullable — The points awarded as part of the extra reward.
      - `coupon` object, nullable — A coupon object that is awarded as part of the extra reward.

---

[API](https://skmtc.net/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.net/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gameballers/gameball-api/revisions/3b11e1670d61/schema)