Skip to main content

​
Overview

Sometimes you want to show a customer all the coupons they’re eligible for — taking into account their attributes as well as the current content of their cart. Voucherify’s Qualifications API helps recommend applicable promotions and coupons in the given customer and order context with filtering options based on campaign category and hierarchy. The qualifications API can be applied (among others) for:
  • Upsell scenarios - showing the customers the discounts available for the customer, encouraging the customer to adjust the cart to conform to the available promotions.
  • Customer wallet - providing a list of vouchers the customer was assigned/received (in Voucherify’s terms, a voucher was published to the customer) in the past that can be used for the current cart.
  • Strike through price - showing new prices for a list of products after a promotional discount is applied.
  • Showing coupons available for given products in a product catalog
Product Catalog Coupon

​
API Endpoints

There are two dedicated API Endpoints for checking eligibility:
EndpointLink
POST v1/v1/qualificationsCheck eligibility using the server-side endpoint.
POST v1/client/v1/qualificationsCheck eligibility using the client-side endpoint.
You can find a description of the qualification object schema in the data model description here.

​
Scenarios

To specify the types of promotions and codes that you would like to reveal to your customers, we introduced the option of including a scenario. A scenario defines the type of content that you would like to return from all the available campaigns and standalone codes that you’ve created in Voucherify.
ScenarioPossible Use Case
ALLReturns all redeemables available for the customer in one API request.
CUSTOMER_WALLETreturns vouchers applicable to the customer’s cart based on the vouchers assigned to the customer’s profile.
AUDIENCE_ONLYReturns all vouchers, promotion tiers, and campaigns available to the customer. Voucherify validates the rules based on the customer profile only.
PRODUCTSReturns all promotions available for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).
PRODUCTS_DISCOUNTReturns all promotions available for products when a discount is defined as applicable to specific item(s).
PROMOTION_STACKSReturns the applicable promotion stacks.
PRODUCTS_BY_CUSTOMERReturns all promotions available for a customer for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).
PRODUCTS_DISCOUNT_BY_CUSTOMERReturns all promotions available for a customer for products when a discount is defined as applicable to specific item(s).
In the request, you can add options to configure the parameters returned in the response, e.g. filters for types of redeemables or sorting rules like BEST_DEAL or LEAST_DEAL.

​
Use Cases

To show a couple of the use cases that are possible with the qualifications API, we’ll show it using the following scenarios. Depending on the different scenario, we’ll send a slightly different API call and the results will be returned in the context of the scenario.

​
Customer profile

The customer is assigned 2 vouchers.
CampaignDetails
Gift card campaignThe gift voucher maIxGd5r can be used by the owner of the code only
Discount campaigncamp_f78wOLL9cE2WCSdtliT0UIh0Voucher code vm3HkNF2 from a 10% discount for BOSCH products redeemable by the owners of the code.

​
Promotions

The use case assumes there are also two promotions available.
  1. 10% for everyone on entire order
  2. 20% for Digital books for VIP customers.
We’ll send a qualification API call with several different settings and explain the results.

​
Case 1 - Logged in vs non-logged in customers

  • If the customer is not logged in, the customer will see only one promotion - the 10% for everyone. | "scenario": "ALL"
  • If they are logged in, they will see two promotion tiers and all the vouchers they have on their hand. | "scenario": "ALL"

​
Not Logged in

Since we cannot identify the customer, we can not show redeemables that are out of scope, i.e. that are not dependent on the customer profile. Promotions Available for non-logged in customers 
{
    "scenario": "ALL",
    "order": {
        "items": [
            {
                "source_id": "bosch_product_1",
                "quantity": "1",
                "price": 10000,
                "related_object": "product",
                "product": {
                    "name": "BOSCH GDR 120-LI Cordless Impact Driver / Wrench"
                }
            },
            {
                "source_id": "digital_book",
                "quantity": "1",
                "price": 1500,
                "related_object": "product",
                "product": {
                    "name": "Digital Book"
                }
            }
        ]
    },
    "options": {
        "expand": [
            "redeemable"
        ]
    }
}

​
Logged in

Once we know who the customer is, the Qualifications API can now return the promotions that are customer specific and the voucher codes the customer owns and that can be used right now. This would then return the following:
CampaignDetails
Gift card campaignThe gift voucher maIxGd5r can be used by the owner of the code only
Discount campaign10% discount for BOSCH productsVoucher code vm3HkNF2 from a 10% discount for BOSCH products redeemable by the owners of the code
10% for everyone on entire orderThe promotion is available for anyone and gives a 10% discount
20% for Digital books for VIP customersThe promotion is available to customers who are VIP customers and is applicable to digital books only
Offers Available for logged in customers 
{
    "scenario": "ALL",
    "customer": {
        "source_id": "GUID_123_john_wayne",
        "name": "John Wayne",
        "metadata": {
            "tier": "VIP"
        }
    },
    "order": {
        "items": [
            {
                "source_id": "bosch_product_1",
                "quantity": "1",
                "price": 10000,
                "related_object": "product",
                "product": {
                    "name": "BOSCH GDR 120-LI Cordless Impact Driver / Wrench"
                }
            },
            {
                "source_id": "digital_book",
                "quantity": "1",
                "price": 1500,
                "related_object": "product",
                "product": {
                    "name": "Digital Book"
                }
            }
        ]
    },
    "options": {
        "expand": [
            "redeemable"
        ]
    }
}
Case 1 Summary The qualification request returned all of the possible vouchers and redeemables the customer could use right now. You can use the qualifications API request to enhance the customer experience by:
  • Showing the current promotions available for everyone on the home page
  • Showing a different set of promotions available for a specific customer on the home page
  • Present the list of available discounts during the customer’s checkout
All of these scenarios require one API request per attempt.
This scenario considered the promotions, voucher codes, and voucher campaigns available for the customer to be used on the current cart. You can experiment with the “Audience Only” scenario that will return all of the discounts based on the customer profile alone, enabling you to create upsell scenarios.

​
Case 2 - Vouchers assigned to customer

We’ll send the same request, but with a different scenario setting. Only the voucher codes assigned to the customer will be returned. "scenario": "CUSTOMER_WALLET" Product Catalog Coupon 
{
    "scenario": "CUSTOMER_WALLET",
    "customer": {
        "source_id": "GUID_123_john_wayne",
        "name": "John Wayne",
        "metadata": {
            "tier": "VIP"
        }
    },
    "order": {
        "items": [
            {
                "source_id": "bosch_product_1",
                "quantity": "1",
                "price": 10000,
                "related_object": "product",
                "product": {
                    "name": "BOSCH GDR 120-LI Cordless Impact Driver / Wrench"
                }
            },
            {
                "source_id": "digital_book",
                "quantity": "1",
                "price": 1500,
                "related_object": "product",
                "product": {
                    "name": "Digital Book"
                }
            }
        ]
    },
    "options": {
        "expand": [
            "redeemable"
        ]
    }
}
Case 2 Summary The customer wallet scenario returned the list of vouchers the customer can use right now. This mechanism enables you to show the customer, at the cart level, all of his/her vouchers he/she can use, including the gift vouchers and loyalty cards that can be used as the means of payment, enabling your customers to choose a specific reward for themselves, or allowing you to apply the discounts automatically.

​
Case 3 - Vouchers applicable to specific products

Only a promotion that is applicable to items in the cart. "scenario": "PRODUCTS_DISCOUNT" Product Coupons In Cart 
{
    "scenario": "PRODUCTS_DISCOUNT",
    "customer": {
        "source_id": "GUID_123_john_wayne",
        "name": "John Wayne",
        "metadata": {
            "tier": "VIP"
        }
    },
    "order": {
        "items": [
            {
                "source_id": "bosch_product_1",
                "quantity": "1",
                "price": 10000,
                "related_object": "product",
                "product": {
                    "name": "BOSCH GDR 120-LI Cordless Impact Driver / Wrench"
                }
            },
            {
                "source_id": "digital_book",
                "quantity": "1",
                "price": 1500,
                "related_object": "product",
                "product": {
                    "name": "Digital Book"
                }
            }
        ]
    },
    "options": {
        "expand": [
            "redeemable"
        ]
    }
}
Case 3 Summary Voucherify will return all the discounts that apply to the products you sent in the order. When a customer is browsing your products and is shown the product listing page, you can send, in the payload, the list of all the products the customer is presented and Voucherify will return all the discounts that apply to these products. The returned results can be visualized, for example, by a striked-through price.

​
Case 4 - Upselling (audience only)

The upsell scenario displays all the incentives within customer’s reach in their cart view and encourages them to purchase additional products. "scenario": "AUDIENCE_ONLY" Upselling 
{
    "scenario": "AUDIENCE_ONLY",
    "customer": { 
        "source_id": "15072024", 
        "name": "John Toolman", 
        "email": "[email protected]", 
        "metadata": {
            "subscribed": false
        }
    },
    "order": {
        "items": [
            {
                "quantity": 1, 
                "price": 10000,  
                "amount": 10000,
                "source_id": "23425235", 
                "name": "GDR Drill",
                "related_object": "product",
                "product": {
                    "metadata": {
                        "category": "Tools",
                        "vendor": "Bosch",
                        "color": "gray"
                    }
                }
            },
            {
                "quantity": 1,
                "price": 40000,
                "amount": 40000, 
                "source_id": "327583490",
                "name": "GRW Stirring Mech.", 
                "related_object": "product",
                "product": {
                    "metadata": {
                        "category": "Tools",
                        "vendor": "Bosch",
                        "color": "dark_green"
                    }
                }
            }
        ]
    },
    "options": {
        "limit": 30,
        "starting_after": "null", 
        "sorting_rule": "DEFAULT",
        "expand": [
            "redeemable",
            "validation_rules",
            "category"
        ],
        "filters": {
            "resource_type": {
                "conditions": {
                    "$is": [
                        "promotion_tier"
                    ]
                }
            }
        }
    }
}
Case 4 Summary Based on the customer order, Voucherify will encourage customers to buy a more expensive version of a product or add extra products from a matching theme adding various incentives. This process focuses on enhancing the customer’s purchase to increase the total sale.

​
Bundles

With bundles, you can create discount incentives that depend on the content of the customer’s cart (order.items array in the request). For example, you can create a bundle of two thermal bottles and five products from a product collection that the customer must have in their cart to be eligible for a $10 discount for a hoodie. The incentives based on a bundle behave differently depending on the qualification scenario. The incentives are returned depending on how the customer’s cart meets bundle requirements:
  • ALL – the cart must meet the bundle conditions for the incentive to be returned;
  • AUDIENCE_ONLY – the cart does not have to meet the bundle conditions for the incentive to be returned;
  • CUSTOMER_WALLET – the cart must meet the bundle conditions;
  • PRODUCTS – the cart does not have to meet the bundle conditions;
  • PRODUCTS_DISCOUNT – the incentive is returned if it is a discount that target products and if that discounted product is in the cart; however, the cart does not have to meet the bundle conditions;
  • PROMOTION_STACKS – the cart must meet the bundle conditions;
  • PRODUCTS_BY_CUSTOMER – the cart does not have to meet the bundle conditions
  • PRODUCTS_DISCOUNT_BY_CUSTOMER – the incentive is returned if it is a discount that target products and if that discounted product is in the cart; however, the cart does not have to meet the bundle conditions.
If the bundle conditions are not met, but the incentive is returned nevertheless, the qualification will return the data showing which SKUs, products, or collections are missing and the missing quantity. In the following example, the bundle conditions are:
  • 2 Star Thermal Bottles
  • 5 Adventure-brand products
Because the customer’s cart (order.items) include only 1 Star Thermal Bottle, 1 Adventure T-shirt, and 2 pairs of Adventure Socks, the qualification returns data with identified products and their quantities that meet the bundle conditions and what is missing in the bundle, namely 1 Star Thermal Bottle and 2 items from the Adventure-brand collection ("id": "pc_pWu3TzRFhJ99Xak7Z7QlynNa"). 
{
    "customer": {
        "source_id": "rdmr01"
    },
    "order": {
        "items": [
            {
                "product": {
                    "id": "prod_0fc35dfe978defeb6b",
                    "name": "Star Thermal Bottle",
                    "price": 2499,
                    "metadata": {
                        "brand": "Star"
                    }
                },
                "quantity": 1
            },
            {
                "product": {
                    "id": "prod_0fc35dfeaa0defeb73",
                    "name": "Adventure T-shirt",
                    "price": 1999,
                    "metadata": {
                        "brand": "Adventure"
                    }
                },
                "quantity": 1
            },
            {
                "product": {
                    "id": "prod_0fc35dfeabcdefeb80",
                    "name": "Adventure Socks",
                    "price": 499,
                    "metadata": {
                        "brand": "Adventure"
                    }
                },
                "quantity": 2
            }
        ]
    },
    "options": {
        "filters": {
            "campaign_type": {
                "conditions": {
                    "$is": [
                        "DISCOUNT_COUPONS"
                    ]
                }
            },
            "resource_type": {
                "conditions": {
                    "$is": [
                        "voucher"
                    ]
                }
            }
        },
        "expand": [
            "redeemable",
            "validation_rules"
        ],
        "limit": 1
    },
    "scenario": "AUDIENCE_ONLY"
}
⌘I