v4.0 (Beta)

Program Configurations

Access information on how customers can participate in campaigns, advance through tiers, and benefit from referral programs. These APIs provide the necessary data to display how customers can win

Available APIs

GET - Campaigns Configurations

https://api.gameball.co/api/v4/integrations/configurations/reward-campaigns

The API retrieves your reward campaign configurations, including both event-based and transactional campaigns. If the customerId, productSku, or collectionId query parameters are provided, the response will include the reward campaigns that are applicable for the specified customer or product.

Security: Requires apiKey header

Request

Query Parameters

customerId string Optional Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. If provided, the API filters and returns only the campaigns that can be achieved by this customer.

collectionId string Optional Unique identifier for a product collection. If provided, the API returns the transactional campaigns applicable to the specified collection.

productSku string Optional The SKU (Stock Keeping Unit) of a product. If provided, the API returns the transactional campaigns applicable to the specified product.

lang string Optional The language in which the response should be returned (e.g., en, fr). If not provided, the default language is used.

Response

application/json

The response will return a list of reward campaigns, each containing detailed information about the campaign’s rewards, availability, visibility, and other configurations.Each reward campaign object includes the following fields:

Reward Campaign Object

id number Unique identifier for the reward campaign.

name string Name of the reward campaign.

description string A brief description of the reward campaign.

isRepeatable boolean Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer.

maxAchievement number Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true . If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available.

type string The type of the campaign. Possible values:

  • SignUp: Reward is given when a user signs up.

  • SocialMedia: Reward is linked to social media activity.

  • ScheduledChallenge: A time-based challenge that gives rewards.

  • Spin The Wheel: Rewards are given based on a spin-the-wheel game.

  • EventBased: Reward is given based on specific customer events.

  • HighScore: Reward is given based on achieving high scores in a campaign.

  • Birthday: Reward is given for birthday-related activity.

visibility string The visibility status of the campaign. Possible values:

  • AlwaysVisible: The campaign is always visible on the widget.

  • NotVisible: The campaign is not visible to the customer on the widget.

  • VisibleIfEarned: The campaign becomes visible once the customer earns it on the widget.

icon string The URL of the campaign’s icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform.

availability object

Defines the criteria determining which customers are eligible to earn this reward campaign.

availability object

minTier number The minimum customer tier order required to achieve in the campaign. Customers must meet or exceed this tier to be eligible.

Example: A value of 2 indicates that only customers in the tier with order 2 or higher can earn this campaign.

tags array A list of tags that identify the target customers eligible for the campaign. Tags can be used to group customers based on specific attributes or behaviors.

Example: ["loyal", "new_customer"] indicates that only customers tagged as "loyal" or "new_customer" are eligible for the campaign.

redirectionButtonText string

The text displayed on the redirection button within the reward campaign page on the widget. Example: "Claim Your Reward" would prompt customers to take action.Text for the redirection button.

redirectionButtonLink string

The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward redemption process. Example: "https://yourwebsite.com/rewards" directs customers to a page where they can view their rewards.

activation string Defines the activation criteria for the campaign, which may include specific start and end dates.

activation object

StartDate DateTime The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: "2024-11-01T00:00:00" indicates that the campaign starts on November 1, 2024.

EndDate DateTime? The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign . Example: "2024-11-30T23:59:59" indicates that the campaign ends on November 30, 2024, at 11:59 PM.

rewards array Details of the rewards that the customer will earn once acchieving this reward campaign.

rewards object

rankReward number The score rewarded for achieving this reward campaign.

walletReward number The number of points the customer will earn upon achieving this reward campaign.

Example:If you have set up a "First Order" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200.

walletRewardFactor number The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers.

Example: In a "Double Points" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign.

couponReward object A coupon object that is awarded to the customer for this reward campaign.

  • couponReward.couponType string The type of coupon provided to the customer (e.g., discount type, free shipping). Possible Values :

    • Free Shipping

    • Free Product

    • Fixed Percentage

    • Fixed Amount

    • Custom

Example: A coupon type of "Free Shipping" indicates that the coupon rewarded to the customer is of type free shipping.

  • couponReward.discountValue number The value of the discount provided by the coupon. Example: If a customer receives a coupon with a couponType of "fixed amount" and a discountValue of 50, they can apply it to their next purchase, reducing the total amount by $50.

  • couponReward.minOrderValue number The minimum order value required to use the coupon. Example: A coupon that specifies a minOrderValue of 100 means the customer must spend at least $100 to apply the coupon.

  • couponReward.options.expiryAfter string The time after which the coupon expires. Example: If a coupon expires on 2024-12-31T23:59:59Z, the customer must use it before that date to receive the discount.

  • couponReward.options.usageLimit number The total number of times this coupon can be used. Example: A coupon with a usageLimit of 1 can only be used by the customer once, requiring them to choose their purchase carefully.

  • couponReward.options.usedCount number The number of times the coupon has already been used. Example: If the usedCount is 0, it indicates that the customer has not yet used the coupon.

  • couponReward.options.capping number Maximum discount or value cap of the coupon. Example: A coupon with a capping of 500 means the maximum discount the customer can receive is $500.

  • couponReward.options.combinesWith.orderDiscounts boolean Indicates if the coupon can combine with order discounts. Example: IforderDiscounts is true, the customer can use it alongside other order discounts for additional savings.

  • couponReward.options.combinesWith.productDiscounts boolean Indicates if the coupon can combine with product discounts. Example: If productDiscounts is false, customers must choose between applying the coupon or a product-specific discount.

  • couponReward.options.combinesWith.shippingDiscounts boolean Indicates if the coupon can combine with shipping discounts. Example: If shippingDiscounts is true, the customer may receive both a discount on the product and free shipping.

  • couponReward.options.productId string The unique identifier of the product associated with the coupon. Example: If the coupon references productId "PROD12345", the customer can use it specifically for that product.

  • couponReward.options.productUrl string URL of the product associated with the coupon. Example: A product URL like https://store.example.com/product/12345 allows customers to click through directly to the product page.

  • couponReward.options.productName string The name of the product associated with the coupon. Example: If the coupon is tied to the product productName "Smartphone", customers can easily identify the item the coupon applies to.

  • couponReward.options.variantId string The variant ID of the product associated with the coupon. Example: A variant ID of VARIANT123 indicates that the coupon can only be used for that specific product variant.

  • couponReward.options.variantName string The name of the product variant associated with the coupon. Example: If the coupon refers to the variant name Black 128GB, it is valid only for that specific option of the product.

  • couponReward.options.productDisplayName string Display name of the product associated with the coupon. Example: productDisplayName "Smartphone 2024 Edition" serves as the recognizable name for the product.

  • couponReward.options.couponPrefix string The prefix for the coupon code, if applicable. Example: A coupon prefix of SUMMER indicates that the coupon is part of a seasonal promotion.

  • couponReward.options.collections Array An array of collections associated with the coupon. Example: If the coupon applies to collections ["Summer Collection", "New Arrivals"], customers can use it on any product from these collections.

  • couponReward.options.productDisplayNames Array A list of product display names associated with the coupon. Example: ["Smartphone 2024", "Laptop Pro"] provides recognizable names of the products eligible for the coupon.

  • couponReward.options.hasCollections boolean Indicates whether the coupon applies to collections. Example: If hasCollections is true, customers can use the coupon on specific collections of products.

  • couponReward.options.platforms Array Platforms on which the coupon can be redeemed (e.g., web, mobile). Example: If the coupon is valid on both web and mobile, customers can apply it in either context.

  • couponReward.options.redeemInstructions Array Instructions on how to redeem the coupon, if available. Example: Instructions such as ["Apply at checkout", "Valid in-store and online"] help guide customers on how to use the coupon.

  • couponReward.options.instructions string Additional instructions related to the coupon. Example: If the coupon has instructions stating Valid only on weekends, customers need to be aware of the restrictions.

  • couponReward.options.source string The source or origin of the coupon. Example: source "Email Campaign" indicates that the coupon was received through an email marketing effort.

  • couponReward.options.couponName string The name of the coupon for internal tracking or display purposes. Example: couponName is"Black Friday Discount" serves as a clear identifier for the promotion.

Sample Response

[
    {
        "id": 5858,
        "name": "Join our family 👯‍♂️",
        "description": "Welcome to the family! Check out your new reward for signing up 😉",
        "rewards": [
            {
                "rankReward": 0,
                "walletReward": 0,
                "walletRewardFactor": null,
                "couponReward": null
            }
        ],
        "isRepeatable": false,
        "maxAchievement": 1,
        "type": "SignUp",
        "visibility": "AlwaysVisible",
        "icon": "https://cdn.gameball.co/uploads/gb-library/general/signup.webp",
        "availability": {
            "minTier": 1,
            "tags": []
        },
        "redirectionButtonText": "Check Your Rewards",
        "redirectionButtonLink": "https://yourwebsite.co/rewards",
        "activation": {
            "startDate": "2024-09-01T00:00:00Z",
            "endDate": "2024-12-31T23:59:59Z"
        }
    },
    {
        "id": 6652,
        "name": "Double points",
        "description": "Earn double points on all purchases during this limited-time campaign!",
        "rewards": [
            {
                "rankReward": 0,
                "walletReward": 0,
                "walletRewardFactor": 2,
                "couponReward": null
            }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "Reward Campaign",
        "visibility": "NotVisible",
        "icon": "https://cdn.gameball.co/uploads/gb-library/general/announcement.webp",
        "availability": {
            "minTier": 1,
            "tags": []
        },
        "redirectionButtonText": "Start Earning Double Points",
        "redirectionButtonLink": "https://yourwebsite.co/doublepoints",
        "activation": {
            "startDate": "2024-10-01T00:00:00Z",
            "endDate": "2024-10-31T23:59:59Z"
        }
    }
]

GET - Tiers Configurations

https://api.gameball.co/api/v4/integrations/configurations/tiers

This API call retrieves the tiers configuration, including the benefits and rewards associated with each tier.

Security: Requires apiKey header

Response

application/json

name string The name of the tier.

minProgress number

The minimum amount of progress a customer needs to reach this tier in the program. This represents the threshold that must be met for a customer to reach this tier.

Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to reach this tier.

Possible Values:

  • Total amount spent

  • Total points earned

  • Friends referred

  • Orders completed

  • Score

Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier.

order number This represents the numerical order of a tier. Higher numbers indicate higher tiers.

icon string The URL for the icon associated with the tier.You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles.

benefits array It contains a list of rewards associated with the tier, each offering specific advantages to the customer. This array includes various types of benefits.

benefits object

type string Indicates the type of benefit the customer will receive. The possible values are:

  • Custom Benefits: Offers tailored and custom rewards to offer customization for specific customer preferences or behaviors.

  • Lifetime Reward: A benefit that can be used once at any time during the customer's lifetime with Gameball, as long as they remain in this tier.

  • Loyalty Points Earning Custom Configuration:Enables customized settings for how customers earn loyalty points based on their spending amount.

  • Entry Reward: A one-time reward granted to customers upon joining this tier.

rankReward number The score rewarded for the customer as a reward.

walletReward number The number of points the customer will earn for this reward.

walletRewardFactor number This is a multiplier factor that indicates how the customer on their tier will be rewarded for each unit of currency they spend. This is returned for the benefits of type Loyalty Points Earning Custom Configuration.

Example : If a tier has a walletRewardFactor of 2, it means any customer on this tier will earn 2 loyalty points for every $1 they spend. Therefore, if the customer spends $100, they would receive 200 loyalty points as a reward.

couponReward object A coupon object that is awarded to the customer.

  • couponReward.couponType string The type of coupon provided to the customer. Possible Values :

    • Free Shipping

    • Free Product

    • Fixed Percentage

    • Fixed Amount

    • Custom

Example: A coupon type of "Free Shipping" indicates that the coupon rewarded to the customer is of type free shipping.

  • couponReward.discountValue number The value of the discount provided by the coupon. Example: If a customer receives a coupon with a couponType of "fixed amount" and a discountValue of 50, they can apply it to their next purchase, reducing the total amount by $50.

  • couponReward.minOrderValue number The minimum order value required to use the coupon. Example: A coupon that specifies a minOrderValue of 100 means the customer must spend at least $100 to apply the coupon.

  • couponReward.options.expiryAfter string The time after which the coupon expires. Example: If a coupon expires on 2024-12-31T23:59:59Z, the customer must use it before that date to receive the discount.

  • couponReward.options.usageLimit number The total number of times this coupon can be used. Example: A coupon with a usageLimit of 1 can only be used by the customer once, requiring them to choose their purchase carefully.

  • couponReward.options.usedCount number The number of times the coupon has already been used. Example: If the usedCount is 0, it indicates that the customer has not yet used the coupon.

  • couponReward.options.capping number Maximum discount or value cap of the coupon. Example: A coupon with a capping of 500 means the maximum discount the customer can receive is $500.

  • couponReward.options.combinesWith.orderDiscounts boolean Indicates if the coupon can combine with order discounts. Example: IforderDiscounts is true, the customer can use it alongside other order discounts for additional savings.

  • couponReward.options.combinesWith.productDiscounts boolean Indicates if the coupon can combine with product discounts. Example: If productDiscounts is false, customers must choose between applying the coupon or a product-specific discount.

  • couponReward.options.combinesWith.shippingDiscounts boolean Indicates if the coupon can combine with shipping discounts. Example: If shippingDiscounts is true, the customer may receive both a discount on the product and free shipping.

  • couponReward.options.productId string The unique identifier of the product associated with the coupon. Example: If the coupon references productId "PROD12345", the customer can use it specifically for that product.

  • couponReward.options.productUrl string URL of the product associated with the coupon. Example: A product URL like https://store.example.com/product/12345 allows customers to click through directly to the product page.

  • couponReward.options.productName string The name of the product associated with the coupon. Example: If the coupon is tied to the product productName "Smartphone", customers can easily identify the item the coupon applies to.

  • couponReward.options.variantId string The variant ID of the product associated with the coupon. Example: A variant ID of VARIANT123 indicates that the coupon can only be used for that specific product variant.

  • couponReward.options.variantName string The name of the product variant associated with the coupon. Example: If the coupon refers to the variant name Black 128GB, it is valid only for that specific option of the product.

  • couponReward.options.productDisplayName string Display name of the product associated with the coupon. Example: productDisplayName "Smartphone 2024 Edition" serves as the recognizable name for the product.

  • couponReward.options.couponPrefix string The prefix for the coupon code, if applicable. Example: A coupon prefix of SUMMER indicates that the coupon is part of a seasonal promotion.

  • couponReward.options.collections Array An array of collections associated with the coupon. Example: If the coupon applies to collections ["Summer Collection", "New Arrivals"], customers can use it on any product from these collections.

  • couponReward.options.productDisplayNames Array A list of product display names associated with the coupon. Example: ["Smartphone 2024", "Laptop Pro"] provides recognizable names of the products eligible for the coupon.

  • couponReward.options.hasCollections boolean Indicates whether the coupon applies to collections. Example: If hasCollections is true, customers can use the coupon on specific collections of products.

  • couponReward.options.platforms Array Platforms on which the coupon can be redeemed (e.g., web, mobile). Example: If the coupon is valid on both web and mobile, customers can apply it in either context.

  • couponReward.options.redeemInstructions Array Instructions on how to redeem the coupon, if available. Example: Instructions such as ["Apply at checkout", "Valid in-store and online"] help guide customers on how to use the coupon.

  • couponReward.options.instructions string Additional instructions related to the coupon. Example: If the coupon has instructions stating Valid only on weekends, customers need to be aware of the restrictions.

  • couponReward.options.source string The source or origin of the coupon. Example: source "Email Campaign" indicates that the coupon was received through an email marketing effort.

  • couponReward.options.couponName string The name of the coupon for internal tracking or display purposes. Example: couponName is"Black Friday Discount" serves as a clear identifier for the promotion.

Sample Response

[
    {
        "name": "Basic",
        "minProgress": 0,
        "order": 1,
        "icon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp",
        "benefits": []
    },
    {
        "name": "Gold",
        "minProgress": 190,
        "order": 2,
        "icon": "level-a1",
        "benefits": [
            {
                "type": "Custom Benefits",
                "description": "Golden membership",
                "hyperLink": "https://mywebsite.com/benefits",
                "rankReward": 0,
                "walletReward": 0
            },
            {
                "type": "Entry Reward",
                "rankReward": 0,
                "walletReward": 3000,
            },
            {
                "type": "Loyalty Points Earning Custom Configuration",
                "rewardWalletFactor": 3.0
            }
        ]
    }
]

GET - Referrals Configurations

https://api.gameball.co/api/v4/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.

Security: Requires apiKey header

Response

application/json

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 Contains additional metadata about the event that triggers the referral.

eventMetaData object

  • name string The name of the event metadata.

  • operator string The operator used for event metadata (e.g., equals, greater_than).

  • value string The value associated with the event metadata.

friendReward Object The reward details given to the referred friend as part of the referral program.

friendReward object

score number The score awarded to the referred friend.

point number The points awarded to the referred friend.

coupon object A coupon object that is awarded to the referred friend.

  • coupon .couponType string The type of coupon provided to the customer (e.g., discount type, free shipping). Possible Values :

    • Free Shipping

    • Free Product

    • Fixed Percentage

    • Fixed Amount

    • Custom

Example: A coupon type of "Free Shipping" indicates that the coupon rewarded to the customer is of type free shipping.

  • coupon.discountValue number The value of the discount provided by the coupon. Example: If a customer receives a coupon with a couponType of "fixed amount" and a discountValue of 50, they can apply it to their next purchase, reducing the total amount by $50.

  • coupon.minOrderValue number The minimum order value required to use the coupon. Example: A coupon that specifies a minOrderValue of 100 means the customer must spend at least $100 to apply the coupon.

  • coupon.options.expiryAfter string The time after which the coupon expires. Example: If a coupon expires on 2024-12-31T23:59:59Z, the customer must use it before that date to receive the discount.

  • coupon.options.usageLimit number The total number of times this coupon can be used. Example: A coupon with a usageLimit of 1 can only be used by the customer once, requiring them to choose their purchase carefully.

  • coupon.options.usedCount number The number of times the coupon has already been used. Example: If the usedCount is 0, it indicates that the customer has not yet used the coupon.

  • coupon.options.capping number Maximum discount or value cap of the coupon. Example: A coupon with a capping of 500 means the maximum discount the customer can receive is $500.

  • coupon.options.combinesWith.orderDiscounts boolean Indicates if the coupon can combine with order discounts. Example: IforderDiscounts is true, the customer can use it alongside other order discounts for additional savings.

  • coupon.options.combinesWith.productDiscounts boolean Indicates if the coupon can combine with product discounts. Example: If productDiscounts is false, customers must choose between applying the coupon or a product-specific discount.

  • coupon.options.combinesWith.shippingDiscounts boolean Indicates if the coupon can combine with shipping discounts. Example: If shippingDiscounts is true, the customer may receive both a discount on the product and free shipping.

  • coupon.options.productId string The unique identifier of the product associated with the coupon. Example: If the coupon references productId "PROD12345", the customer can use it specifically for that product.

  • coupon.options.productUrl string URL of the product associated with the coupon. Example: A product URL like https://store.example.com/product/12345 allows customers to click through directly to the product page.

  • coupon.options.productName string The name of the product associated with the coupon. Example: If the coupon is tied to the product productName "Smartphone", customers can easily identify the item the coupon applies to.

  • coupon.options.variantId string The variant ID of the product associated with the coupon. Example: A variant ID of VARIANT123 indicates that the coupon can only be used for that specific product variant.

  • coupon.options.variantName string The name of the product variant associated with the coupon. Example: If the coupon refers to the variant name Black 128GB, it is valid only for that specific option of the product.

  • coupon.options.productDisplayName string Display name of the product associated with the coupon. Example: productDisplayName "Smartphone 2024 Edition" serves as the recognizable name for the product.

  • coupon.options.couponPrefix string The prefix for the coupon code, if applicable. Example: A coupon prefix of SUMMER indicates that the coupon is part of a seasonal promotion.

  • coupon.options.collections Array An array of collections associated with the coupon. Example: If the coupon applies to collections ["Summer Collection", "New Arrivals"], customers can use it on any product from these collections.

  • coupon.options.productDisplayNames Array A list of product display names associated with the coupon. Example: ["Smartphone 2024", "Laptop Pro"] provides recognizable names of the products eligible for the coupon.

  • coupon.options.hasCollections boolean Indicates whether the coupon applies to collections. Example: If hasCollections is true, customers can use the coupon on specific collections of products.

  • coupon.options.platforms Array Platforms on which the coupon can be redeemed (e.g., web, mobile). Example: If the coupon is valid on both web and mobile, customers can apply it in either context.

  • coupon.options.redeemInstructions Array Instructions on how to redeem the coupon, if available. Example: Instructions such as ["Apply at checkout", "Valid in-store and online"] help guide customers on how to use the coupon.

  • coupon.options.instructions string Additional instructions related to the coupon. Example: If the coupon has instructions stating Valid only on weekends, customers need to be aware of the restrictions.

  • coupon.options.source string The source or origin of the coupon. Example: source "Email Campaign" indicates that the coupon was received through an email marketing effort.

  • coupon.options.couponName string The name of the coupon for internal tracking or display purposes. Example: couponName is"Black Friday Discount" serves as a clear identifier for the promotion.

customerReward Object The reward details given to the customer as part of the referral program.

customerReward object

score number The score awarded to the customer.

point number The points awarded to the customer.

coupon object A coupon object that is awarded to the customer.

  • coupon.couponType string The type of coupon provided to the customer (e.g., discount type, free shipping). Possible Values :

    • Free Shipping

    • Free Product

    • Fixed Percentage

    • Fixed Amount

    • Custom

Example: A coupon type of "Free Shipping" indicates that the coupon rewarded to the customer is of type free shipping.

  • coupon.discountValue number The value of the discount provided by the coupon. Example: If a customer receives a coupon with a couponType of "fixed amount" and a discountValue of 50, they can apply it to their next purchase, reducing the total amount by $50.

  • coupon.minOrderValue number The minimum order value required to use the coupon. Example: A coupon that specifies a minOrderValue of 100 means the customer must spend at least $100 to apply the coupon.

  • coupon.options.expiryAfter string The time after which the coupon expires. Example: If a coupon expires on 2024-12-31T23:59:59Z, the customer must use it before that date to receive the discount.

  • coupon.options.usageLimit number The total number of times this coupon can be used. Example: A coupon with a usageLimit of 1 can only be used by the customer once, requiring them to choose their purchase carefully.

  • coupon.options.usedCount number The number of times the coupon has already been used. Example: If the usedCount is 0, it indicates that the customer has not yet used the coupon.

  • coupon.options.capping number Maximum discount or value cap of the coupon. Example: A coupon with a capping of 500 means the maximum discount the customer can receive is $500.

  • coupon.options.combinesWith.orderDiscounts boolean Indicates if the coupon can combine with order discounts. Example: IforderDiscounts is true, the customer can use it alongside other order discounts for additional savings.

  • coupon.options.combinesWith.productDiscounts boolean Indicates if the coupon can combine with product discounts. Example: If productDiscounts is false, customers must choose between applying the coupon or a product-specific discount.

  • coupon.options.combinesWith.shippingDiscounts boolean Indicates if the coupon can combine with shipping discounts. Example: If shippingDiscounts is true, the customer may receive both a discount on the product and free shipping.

  • coupon.options.productId string The unique identifier of the product associated with the coupon. Example: If the coupon references productId "PROD12345", the customer can use it specifically for that product.

  • coupon.options.productUrl string URL of the product associated with the coupon. Example: A product URL like https://store.example.com/product/12345 allows customers to click through directly to the product page.

  • coupon.options.productName string The name of the product associated with the coupon. Example: If the coupon is tied to the product productName "Smartphone", customers can easily identify the item the coupon applies to.

  • coupon.options.variantId string The variant ID of the product associated with the coupon. Example: A variant ID of VARIANT123 indicates that the coupon can only be used for that specific product variant.

  • coupon.options.variantName string The name of the product variant associated with the coupon. Example: If the coupon refers to the variant name Black 128GB, it is valid only for that specific option of the product.

  • coupon.options.productDisplayName string Display name of the product associated with the coupon. Example: productDisplayName "Smartphone 2024 Edition" serves as the recognizable name for the product.

  • coupon.options.couponPrefix string The prefix for the coupon code, if applicable. Example: A coupon prefix of SUMMER indicates that the coupon is part of a seasonal promotion.

  • coupon.options.collections Array An array of collections associated with the coupon. Example: If the coupon applies to collections ["Summer Collection", "New Arrivals"], customers can use it on any product from these collections.

  • coupon.options.productDisplayNames Array A list of product display names associated with the coupon. Example: ["Smartphone 2024", "Laptop Pro"] provides recognizable names of the products eligible for the coupon.

  • coupon.options.hasCollections boolean Indicates whether the coupon applies to collections. Example: If hasCollections is true, customers can use the coupon on specific collections of products.

  • coupon.options.platforms Array Platforms on which the coupon can be redeemed (e.g., web, mobile). Example: If the coupon is valid on both web and mobile, customers can apply it in either context.

  • coupon.options.redeemInstructions Array Instructions on how to redeem the coupon, if available. Example: Instructions such as ["Apply at checkout", "Valid in-store and online"] help guide customers on how to use the coupon.

  • coupon.options.instructions string Additional instructions related to the coupon. Example: If the coupon has instructions stating Valid only on weekends, customers need to be aware of the restrictions.

  • coupon.options.source string The source or origin of the coupon. Example: source "Email Campaign" indicates that the coupon was received through an email marketing effort.

  • coupon.options.couponName string The name of the coupon for internal tracking or display purposes. Example: couponName is"Black Friday Discount" serves as a clear identifier for the promotion.

extraReward Object It contains all the details of the reward (like the friendReward Object) that will be awarded to the customer as a a bonus on top of the regular reward) for every X friend referred.

  • extraReward.forEvery number 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.

Sample Response

{
    "referralMethod": "CustomerAndFriend",
    "eventName": "place_order",
    "eventMetaData": {
        "name": "number_of_products",
        "operator": "equals",
        "value": "3"
    },
    "customerReward": {
        "extraReward": {
            "forEvery": 3,
            "score": 0,
            "point": 500,
            "coupon": null
        },
        "score": 0,
        "point": 200,
        "coupon":null
        
    },
    "friendReward": {
        "score": 0,
        "point": 0,
        "coupon": {
            "couponType": "Percentage",
            "discountValue": 10.0,
            "minOrderValue": 50.0,
            "product": "Any",
            "collections": ["Summer Collection", "Spring Sale"],
            "options": {
                "expiryAfter": "2025-12-31",
                "usageLimit": 1,
                "usedCount": 0,
                "capping": 100,
                "minOrderValue": 50.0,
                "combinesWith": {
                    "orderDiscounts": true,
                    "productDiscounts": false,
                    "shippingDiscounts": true
                },
                "productId": "ABC123",
                "productUrl": "https://example.com/product/ABC123",
                "productName": "Sample Product",
                "variantId": "VAR456",
                "variantName": "Red",
                "productDisplayName": "Sample Product - Red",
                "couponPrefix": "SUMMER",
                "collections": ["Featured", "Best Sellers"],
                "productDisplayNames": ["Sample Product"],
                "hasCollections": true,
                "platforms": ["Web", "Mobile"],
                "redeemInstructions": ["Apply at checkout"],
                "instructions": "Use this coupon code at checkout to avail the discount.",
                "source": "Referral Program",
                "couponName": "SUMMER10"
            }
        }
    }
}
PreviousReward ConfigurationsNextWidget Configuration

Last updated