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: 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. 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.

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

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: Offers Available for logged in customers
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
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
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
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").
Last modified on February 10, 2026