Skip to main content
POST
/
client
/
v1
/
qualifications
Check Eligibility (client-side)
curl --request POST \
  --url https://{cluster}.voucherify.io/client/v1/qualifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Application-Id: <api-key>' \
  --header 'X-Client-Token: <api-key>' \
  --data '
{
  "customer": {
    "id": "<string>",
    "source_id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "birthday": "2023-12-25",
    "birthdate": "2023-12-25",
    "address": {
      "city": "<string>",
      "state": "<string>",
      "line_1": "<string>",
      "line_2": "<string>",
      "country": "<string>",
      "postal_code": "<string>"
    },
    "metadata": {}
  },
  "order": {
    "id": "<string>",
    "source_id": "<string>",
    "status": "CREATED",
    "amount": 123,
    "initial_amount": 123,
    "discount_amount": 123,
    "items": [
      {
        "sku_id": "<string>",
        "product_id": "<string>",
        "related_object": "product",
        "source_id": "<string>",
        "quantity": 123,
        "discount_quantity": 123,
        "initial_quantity": 123,
        "amount": 123,
        "discount_amount": 123,
        "initial_amount": 123,
        "price": 123,
        "product": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "name": "<string>",
          "metadata": {},
          "price": 123
        },
        "sku": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "sku": "<string>",
          "price": 123,
          "metadata": {}
        },
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "tracking_id": "<string>",
  "scenario": "ALL",
  "options": {
    "limit": 49,
    "starting_after": "2021-09-08T13:52:18.227Z",
    "filters": {
      "junction": "and",
      "category_id": {
        "conditions": {
          "$is": [
            "<string>"
          ],
          "$is_not": [
            "<string>"
          ],
          "$has_value": [
            "<string>"
          ],
          "$is_unknown": [
            "<string>"
          ],
          "$in": [
            "<string>"
          ],
          "$not_in": [
            "<string>"
          ]
        }
      },
      "campaign_id": {
        "conditions": {
          "$is": [
            "<string>"
          ],
          "$is_not": [
            "<string>"
          ],
          "$has_value": [
            "<string>"
          ],
          "$is_unknown": [
            "<string>"
          ],
          "$in": [
            "<string>"
          ],
          "$not_in": [
            "<string>"
          ]
        }
      },
      "campaign_type": {
        "conditions": {
          "$is": [
            "PROMOTION"
          ],
          "$is_not": [
            "PROMOTION"
          ],
          "$in": [
            "PROMOTION"
          ],
          "$not_in": [
            "PROMOTION"
          ]
        }
      },
      "resource_id": {
        "conditions": {
          "$is": [
            "<string>"
          ],
          "$is_not": [
            "<string>"
          ],
          "$has_value": [
            "<string>"
          ],
          "$is_unknown": [
            "<string>"
          ],
          "$in": [
            "<string>"
          ],
          "$not_in": [
            "<string>"
          ]
        }
      },
      "resource_type": {
        "conditions": {
          "$is": [
            "campaign"
          ],
          "$is_not": [
            "campaign"
          ],
          "$in": [
            "campaign"
          ],
          "$not_in": [
            "campaign"
          ]
        }
      },
      "voucher_type": {
        "conditions": {
          "$is": [
            "<string>"
          ],
          "$is_not": [
            "<string>"
          ],
          "$has_value": [
            "<string>"
          ],
          "$is_unknown": [
            "<string>"
          ],
          "$in": [
            "<string>"
          ],
          "$not_in": [
            "<string>"
          ]
        }
      },
      "code": {
        "conditions": {
          "$is": [
            "<string>"
          ],
          "$is_not": [
            "<string>"
          ],
          "$has_value": [
            "<string>"
          ],
          "$is_unknown": [
            "<string>"
          ],
          "$in": [
            "<string>"
          ],
          "$not_in": [
            "<string>"
          ]
        }
      },
      "holder_role": {
        "conditions": {
          "$is": [
            "OWNER"
          ],
          "$is_not": [
            "OWNER"
          ],
          "$in": [
            "OWNER"
          ],
          "$not_in": [
            "OWNER"
          ]
        }
      }
    },
    "expand": [
      "redeemable"
    ],
    "sorting_rule": "BEST_DEAL"
  },
  "session": {
    "type": "LOCK"
  },
  "metadata": {}
}
'
{
  "redeemables": {
    "object": "list",
    "data_ref": "data",
    "data": [
      {
        "id": "<string>",
        "object": "campaign",
        "created_at": "2022-03-09T11:19:04.819Z",
        "result": {
          "discount": {
            "type": "AMOUNT",
            "amount_off": 123,
            "amount_off_formula": "<string>",
            "aggregated_amount_limit": 123,
            "effect": "APPLY_TO_ORDER",
            "is_dynamic": true
          },
          "bundle": {
            "quantity": 50,
            "limit": 50,
            "identified": [
              {
                "id": "<string>",
                "object": "product",
                "item_index": 1,
                "item_quantity": 123
              }
            ],
            "missing": [
              {
                "id": "<string>",
                "object": "product",
                "item_quantity": 123
              }
            ]
          },
          "gift": {
            "balance": 123,
            "credits": 123,
            "locked_credits": 123
          },
          "loyalty_card": {
            "points": 7000,
            "balance": 6970,
            "exchange_ratio": 123,
            "points_ratio": 123,
            "transfers": [
              {
                "code": "<string>",
                "points": 123,
                "source_id": "<string>",
                "reason": "<string>"
              }
            ]
          },
          "error": {
            "code": 123,
            "message": "<string>",
            "key": "<string>",
            "details": "<string>",
            "request_id": "v-0a885062c80375740f",
            "resource_id": "rf_0c5d710a87c8a31f86",
            "resource_type": "voucher",
            "error": {
              "message": "<string>"
            }
          }
        },
        "order": {
          "id": "<string>",
          "source_id": "<string>",
          "status": "CREATED",
          "amount": 123,
          "initial_amount": 123,
          "discount_amount": 123,
          "items_discount_amount": 123,
          "total_discount_amount": 123,
          "total_amount": 123,
          "applied_discount_amount": 123,
          "items_applied_discount_amount": 123,
          "total_applied_discount_amount": 123,
          "metadata": {},
          "object": "order",
          "created_at": "2021-12-22T10:13:06.487Z",
          "updated_at": "2021-12-22T10:14:45.316Z",
          "customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
          "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
          "customer": {
            "id": "<string>",
            "object": "customer"
          },
          "referrer": {
            "id": "<string>",
            "object": "customer"
          },
          "redemptions": {},
          "items": [
            {
              "object": "order_item",
              "id": "<string>",
              "sku_id": "<string>",
              "product_id": "<string>",
              "related_object": "product",
              "source_id": "<string>",
              "quantity": 123,
              "discount_quantity": 123,
              "initial_quantity": 123,
              "amount": 123,
              "discount_amount": 123,
              "applied_discount_amount": 123,
              "applied_discount_quantity": 123,
              "applied_quantity": 123,
              "applied_quantity_amount": 123,
              "initial_amount": 123,
              "price": 123,
              "subtotal_amount": 123,
              "product": {
                "id": "<string>",
                "source_id": "<string>",
                "override": true,
                "name": "<string>",
                "metadata": {},
                "price": 123
              },
              "sku": {
                "id": "<string>",
                "source_id": "<string>",
                "override": true,
                "sku": "<string>",
                "price": 123,
                "metadata": {}
              },
              "metadata": {},
              "application_details": [
                {
                  "source_index": 1,
                  "source_applied_quantity": -2,
                  "source_applied_quantity_amount": -1,
                  "target_index": 123,
                  "target_applied_quantity": 123,
                  "target_applied_quantity_amount": 123,
                  "target_applied_discount_amount": 123
                }
              ]
            }
          ]
        },
        "validation_rule_id": "<string>",
        "applicable_to": {
          "data": [
            {
              "object": "product",
              "id": "<string>",
              "effect": "APPLY_TO_EVERY",
              "source_id": "<string>",
              "product_id": "<string>",
              "product_source_id": "<string>",
              "price": 123,
              "price_formula": 123,
              "quantity_limit": 123,
              "aggregated_quantity_limit": 123,
              "amount_limit": 123,
              "aggregated_amount_limit": 123,
              "order_item_indices": [
                123
              ],
              "order_item_units": [
                {
                  "index": 1,
                  "units": [
                    123
                  ],
                  "units_limit_exceeded": true
                }
              ],
              "repeat": 123,
              "skip_initially": 123,
              "target": "ITEM"
            }
          ],
          "total": 1,
          "object": "list",
          "data_ref": "data"
        },
        "inapplicable_to": {
          "data": [
            {
              "object": "product",
              "id": "<string>",
              "effect": "APPLY_TO_EVERY",
              "source_id": "<string>",
              "product_id": "<string>",
              "product_source_id": "<string>",
              "price": 123,
              "price_formula": 123,
              "quantity_limit": 123,
              "aggregated_quantity_limit": 123,
              "amount_limit": 123,
              "aggregated_amount_limit": 123,
              "order_item_indices": [
                123
              ],
              "order_item_units": [
                {
                  "index": 1,
                  "units": [
                    123
                  ],
                  "units_limit_exceeded": true
                }
              ],
              "repeat": 123,
              "skip_initially": 123,
              "target": "ITEM"
            }
          ],
          "total": 1,
          "object": "list",
          "data_ref": "data"
        },
        "metadata": {},
        "categories": [
          {
            "id": "<string>",
            "name": "<string>",
            "hierarchy": 1,
            "object": "category",
            "created_at": "2022-07-14T10:45:13.156Z",
            "updated_at": "2022-08-16T10:52:08.094Z",
            "stacking_rules_type": "JOINT"
          }
        ],
        "banner": "Order Paid - You will get 100 points",
        "name": "promotion_tier_get_points",
        "campaign_name": "PromotionCampaign",
        "campaign_id": "camp_Mow7u4gSxagLlZ2oDQ01ZS5N",
        "validation_rules_assignments": {
          "object": "list",
          "data_ref": "data",
          "data": [
            {
              "id": "asgm_LnY1g7UNFA9KyDrD",
              "rule_id": "val_3gPNA6SnH4ae",
              "related_object_id": "camp_CZOnEGiZfwIKWmSjhIoIT7Ol",
              "related_object_type": "campaign",
              "object": "validation_rules_assignment",
              "validation_status": "PARTIALLY_VALID",
              "validation_omitted_rules": [
                "1"
              ]
            }
          ],
          "total": 1
        },
        "redeemables": [
          {
            "id": "<string>",
            "object": "campaign",
            "created_at": "2022-03-09T11:19:04.819Z",
            "result": {
              "discount": {
                "type": "AMOUNT",
                "amount_off": 123,
                "amount_off_formula": "<string>",
                "aggregated_amount_limit": 123,
                "effect": "APPLY_TO_ORDER",
                "is_dynamic": true
              },
              "bundle": {
                "quantity": 50,
                "limit": 50,
                "identified": [
                  {
                    "id": "<string>",
                    "object": "product",
                    "item_index": 1,
                    "item_quantity": 123
                  }
                ],
                "missing": [
                  {
                    "id": "<string>",
                    "object": "product",
                    "item_quantity": 123
                  }
                ]
              },
              "gift": {
                "balance": 123,
                "credits": 123,
                "locked_credits": 123
              },
              "loyalty_card": {
                "points": 7000,
                "balance": 6970,
                "exchange_ratio": 123,
                "points_ratio": 123,
                "transfers": [
                  {
                    "code": "<string>",
                    "points": 123,
                    "source_id": "<string>",
                    "reason": "<string>"
                  }
                ]
              },
              "error": {
                "code": 123,
                "message": "<string>",
                "key": "<string>",
                "details": "<string>",
                "request_id": "v-0a885062c80375740f",
                "resource_id": "rf_0c5d710a87c8a31f86",
                "resource_type": "voucher",
                "error": {
                  "message": "<string>"
                }
              }
            },
            "order": {
              "id": "<string>",
              "source_id": "<string>",
              "status": "CREATED",
              "amount": 123,
              "initial_amount": 123,
              "discount_amount": 123,
              "items_discount_amount": 123,
              "total_discount_amount": 123,
              "total_amount": 123,
              "applied_discount_amount": 123,
              "items_applied_discount_amount": 123,
              "total_applied_discount_amount": 123,
              "metadata": {},
              "object": "order",
              "created_at": "2021-12-22T10:13:06.487Z",
              "updated_at": "2021-12-22T10:14:45.316Z",
              "customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
              "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
              "customer": {
                "id": "<string>",
                "object": "customer"
              },
              "referrer": {
                "id": "<string>",
                "object": "customer"
              },
              "redemptions": {},
              "items": [
                {
                  "object": "order_item",
                  "id": "<string>",
                  "sku_id": "<string>",
                  "product_id": "<string>",
                  "related_object": "product",
                  "source_id": "<string>",
                  "quantity": 123,
                  "discount_quantity": 123,
                  "initial_quantity": 123,
                  "amount": 123,
                  "discount_amount": 123,
                  "applied_discount_amount": 123,
                  "applied_discount_quantity": 123,
                  "applied_quantity": 123,
                  "applied_quantity_amount": 123,
                  "initial_amount": 123,
                  "price": 123,
                  "subtotal_amount": 123,
                  "product": {
                    "id": "<string>",
                    "source_id": "<string>",
                    "override": true,
                    "name": "<string>",
                    "metadata": {},
                    "price": 123
                  },
                  "sku": {
                    "id": "<string>",
                    "source_id": "<string>",
                    "override": true,
                    "sku": "<string>",
                    "price": 123,
                    "metadata": {}
                  },
                  "metadata": {},
                  "application_details": [
                    {
                      "source_index": 1,
                      "source_applied_quantity": -2,
                      "source_applied_quantity_amount": -1,
                      "target_index": 123,
                      "target_applied_quantity": 123,
                      "target_applied_quantity_amount": 123,
                      "target_applied_discount_amount": 123
                    }
                  ]
                }
              ]
            },
            "validation_rule_id": "<string>",
            "applicable_to": {
              "data": [
                {
                  "object": "product",
                  "id": "<string>",
                  "effect": "APPLY_TO_EVERY",
                  "source_id": "<string>",
                  "product_id": "<string>",
                  "product_source_id": "<string>",
                  "price": 123,
                  "price_formula": 123,
                  "quantity_limit": 123,
                  "aggregated_quantity_limit": 123,
                  "amount_limit": 123,
                  "aggregated_amount_limit": 123,
                  "order_item_indices": [
                    123
                  ],
                  "order_item_units": [
                    {
                      "index": 1,
                      "units": [
                        123
                      ],
                      "units_limit_exceeded": true
                    }
                  ],
                  "repeat": 123,
                  "skip_initially": 123,
                  "target": "ITEM"
                }
              ],
              "total": 1,
              "object": "list",
              "data_ref": "data"
            },
            "inapplicable_to": {
              "data": [
                {
                  "object": "product",
                  "id": "<string>",
                  "effect": "APPLY_TO_EVERY",
                  "source_id": "<string>",
                  "product_id": "<string>",
                  "product_source_id": "<string>",
                  "price": 123,
                  "price_formula": 123,
                  "quantity_limit": 123,
                  "aggregated_quantity_limit": 123,
                  "amount_limit": 123,
                  "aggregated_amount_limit": 123,
                  "order_item_indices": [
                    123
                  ],
                  "order_item_units": [
                    {
                      "index": 1,
                      "units": [
                        123
                      ],
                      "units_limit_exceeded": true
                    }
                  ],
                  "repeat": 123,
                  "skip_initially": 123,
                  "target": "ITEM"
                }
              ],
              "total": 1,
              "object": "list",
              "data_ref": "data"
            },
            "metadata": {},
            "categories": [
              {
                "id": "<string>",
                "name": "<string>",
                "hierarchy": 1,
                "object": "category",
                "created_at": "2022-07-14T10:45:13.156Z",
                "updated_at": "2022-08-16T10:52:08.094Z",
                "stacking_rules_type": "JOINT"
              }
            ],
            "banner": "Order Paid - You will get 100 points",
            "name": "promotion_tier_get_points",
            "campaign_name": "PromotionCampaign",
            "campaign_id": "camp_Mow7u4gSxagLlZ2oDQ01ZS5N",
            "validation_rules_assignments": {
              "object": "list",
              "data_ref": "data",
              "data": [
                {
                  "id": "asgm_LnY1g7UNFA9KyDrD",
                  "rule_id": "val_3gPNA6SnH4ae",
                  "related_object_id": "camp_CZOnEGiZfwIKWmSjhIoIT7Ol",
                  "related_object_type": "campaign",
                  "object": "validation_rules_assignment",
                  "validation_status": "PARTIALLY_VALID",
                  "validation_omitted_rules": [
                    "1"
                  ]
                }
              ],
              "total": 1
            }
          }
        ]
      }
    ],
    "total": 5,
    "has_more": true,
    "more_starting_after": "2023-10-31T12:13:16.374Z"
  },
  "tracking_id": "<string>",
  "order": {
    "id": "<string>",
    "source_id": "<string>",
    "status": "CREATED",
    "amount": 123,
    "initial_amount": 123,
    "discount_amount": 123,
    "items_discount_amount": 123,
    "total_discount_amount": 123,
    "total_amount": 123,
    "applied_discount_amount": 123,
    "items_applied_discount_amount": 123,
    "total_applied_discount_amount": 123,
    "metadata": {},
    "object": "order",
    "created_at": "2021-12-22T10:13:06.487Z",
    "updated_at": "2021-12-22T10:14:45.316Z",
    "customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
    "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
    "customer": {
      "id": "<string>",
      "object": "customer"
    },
    "referrer": {
      "id": "<string>",
      "object": "customer"
    },
    "redemptions": {},
    "items": [
      {
        "object": "order_item",
        "id": "<string>",
        "sku_id": "<string>",
        "product_id": "<string>",
        "related_object": "product",
        "source_id": "<string>",
        "quantity": 123,
        "discount_quantity": 123,
        "initial_quantity": 123,
        "amount": 123,
        "discount_amount": 123,
        "applied_discount_amount": 123,
        "applied_discount_quantity": 123,
        "applied_quantity": 123,
        "applied_quantity_amount": 123,
        "initial_amount": 123,
        "price": 123,
        "subtotal_amount": 123,
        "product": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "name": "<string>",
          "metadata": {},
          "price": 123
        },
        "sku": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "sku": "<string>",
          "price": 123,
          "metadata": {}
        },
        "metadata": {},
        "application_details": [
          {
            "source_index": 1,
            "source_applied_quantity": -2,
            "source_applied_quantity_amount": -1,
            "target_index": 123,
            "target_applied_quantity": 123,
            "target_applied_quantity_amount": 123,
            "target_applied_discount_amount": 123
          }
        ]
      }
    ]
  },
  "stacking_rules": {
    "redeemables_limit": 30,
    "applicable_redeemables_limit": 5,
    "applicable_redeemables_per_category_limit": 1,
    "applicable_redeemables_category_limits": {},
    "applicable_exclusive_redeemables_limit": 1,
    "exclusive_categories": [
      "<string>"
    ],
    "joint_categories": [
      "<string>"
    ],
    "redeemables_application_mode": "ALL",
    "redeemables_sorting_rule": "REQUESTED_ORDER",
    "redeemables_products_application_mode": "STACK",
    "redeemables_no_effect_rule": "REDEEM_ANYWAY",
    "no_effect_skip_categories": [
      "<string>"
    ],
    "no_effect_redeem_anyway_categories": [
      "<string>"
    ],
    "redeemables_rollback_order_mode": "WITH_ORDER",
    "applicable_exclusive_redeemables_per_category_limit": 1
  }
}

Authorizations

​
X-Client-Application-Id
string
header
required
​
X-Client-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Define order and customer context.

Request body schema for POST v1/qualifications.

​
customer
Customer · object

Customer's information.

​
order
Order · object

Order information.

​
tracking_id
string

Is correspondent to Customer's source_id

​
scenario
enum<string>

Defines the scenario Voucherify should consider during the qualification process.

  • ALL - Scenario that returns all redeemables available for the customer in one API request. This scenario is used by default when no value is selected.
  • CUSTOMER_WALLET - returns vouchers applicable to the customer's cart based on the vouchers assigned to the customer's profile.
  • AUDIENCE_ONLY - returns all vouchers, promotion tiers, and campaigns available to the customer. Voucherify validates the rules based on the customer profile only.
  • PRODUCTS - returns 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_DISCOUNT - returns all promotions available for products when a discount is defined as applicable to specific item(s).
  • PROMOTION_STACKS - returns the applicable promotion stacks.
  • PRODUCTS_BY_CUSTOMER - returns 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_CUSTOMER - returns all promotions available for a customer for products when a discount is defined as applicable to specific item(s).
Available options:
ALL,
CUSTOMER_WALLET,
AUDIENCE_ONLY,
PRODUCTS,
PRODUCTS_DISCOUNT,
PROMOTION_STACKS,
PRODUCTS_BY_CUSTOMER,
PRODUCTS_DISCOUNT_BY_CUSTOMER
​
options
object

Configure parameters returned in the response.

​
session
object

Parameter to return details about locked_credits on a gift card which has locked credits under a validation session.

​
metadata
object

A set of key/value pairs that you can send in the request body to check against redeemables requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.

Response

200 - application/json

Returns a qualifications object.

Response body schema for POST v1/qualifications.

​
redeemables
Redeemables · object

List of redeemables for examine qualification.

​
tracking_id
string

This identifier is generated during voucher qualification based on your internal id (e.g., email, database ID). This is a hashed customer source ID.

​
order
Order Calculated No Customer Data · object

Order information.

​
stacking_rules
Stacking Rules · object

Defines stacking rules for redeemables. Read more in the Stacking Rule Documentation.

Last modified on December 11, 2025