Skip to main content
POST
/
v1
/
qualifications
Check Eligibility
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/qualifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-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": "BUNDLE-PROD-1c",
        "object": "voucher",
        "created_at": "2025-03-26T11:00:17.987Z",
        "result": {
          "discount": {
            "type": "AMOUNT",
            "effect": "APPLY_TO_ITEMS",
            "amount_off": 900,
            "aggregated_amount_limit": 9000,
            "is_dynamic": false
          },
          "bundle": {
            "quantity": 0,
            "identified": [
              {
                "id": "prod_0fc35dfe978defeb6b",
                "object": "product",
                "item_index": 0,
                "item_quantity": 1
              },
              {
                "id": "prod_0fc35dfeaa0defeb73",
                "object": "product",
                "item_index": 1,
                "item_quantity": 1
              },
              {
                "id": "prod_0fc35dfeabcdefeb80",
                "object": "product",
                "item_index": 2,
                "item_quantity": 2
              }
            ],
            "missing": [
              {
                "id": "prod_0fc35dfe978defeb6b",
                "object": "product",
                "item_quantity": 1
              },
              {
                "id": "pc_pWu3TzRFhJ99Xak7Z7QlynNa",
                "object": "products_collection",
                "item_quantity": 2
              }
            ]
          }
        },
        "order": {
          "amount": 5496,
          "total_amount": 5496,
          "items": [
            {
              "object": "order_item",
              "id": "ordli_105e1f56dc0bc19187",
              "quantity": 1,
              "initial_quantity": 1,
              "amount": 2499,
              "initial_amount": 2499,
              "price": 2499,
              "subtotal_amount": 2499,
              "product": {
                "id": "prod_0fc35dfe978defeb6b",
                "source_id": "star-th-bottle",
                "name": "Star Thermal Bottle",
                "metadata": {
                  "brand": "Star"
                },
                "price": 2499
              }
            },
            {
              "object": "order_item",
              "id": "ordli_105e1f56dc0bc19188",
              "quantity": 1,
              "initial_quantity": 1,
              "amount": 1999,
              "initial_amount": 1999,
              "price": 1999,
              "subtotal_amount": 1999,
              "product": {
                "id": "prod_0fc35dfeaa0defeb73",
                "source_id": "adv-tshirt",
                "name": "Adventure T-shirt",
                "metadata": {
                  "brand": "Adventure"
                },
                "price": 1999
              }
            },
            {
              "object": "order_item",
              "id": "ordli_105e1f56dc0bc19189",
              "quantity": 2,
              "initial_quantity": 2,
              "amount": 998,
              "initial_amount": 998,
              "price": 499,
              "subtotal_amount": 998,
              "product": {
                "id": "prod_0fc35dfeabcdefeb80",
                "source_id": "adv-scks",
                "name": "Adventure Socks",
                "metadata": {
                  "brand": "Adventure"
                },
                "price": 499
              }
            }
          ],
          "customer_id": null,
          "referrer_id": null,
          "object": "order"
        },
        "applicable_to": {
          "data": [
            {
              "object": "products_collection",
              "id": "pc_nw1xRgXB8cBzDJSrSbdSqJP4",
              "effect": "APPLY_TO_EVERY",
              "skip_initially": 0,
              "repeat": 1,
              "target": "ITEM"
            }
          ],
          "total": 1,
          "data_ref": "data",
          "object": "list"
        },
        "inapplicable_to": {
          "data": [],
          "total": 0,
          "data_ref": "data",
          "object": "list"
        },
        "metadata": {},
        "campaign_id": "camp_vzuF8JZdh1tdQqw3R6rS63ci",
        "campaign_name": "Bundle-Product-Discount",
        "validation_rules_assignments": {
          "object": "list",
          "data_ref": "data",
          "data": [
            {
              "id": "asgm_e9RsrtXBMCJ5ti1S",
              "rule_id": "val_g1rAIcaPuxAd",
              "related_object_id": "v_XXSJVTBFFKLPiy585UqtTPiYJMF1bnBW",
              "related_object_type": "voucher",
              "object": "validation_rules_assignment",
              "validation_status": "VALID"
            }
          ],
          "total": 1
        }
      }
    ],
    "total": 1,
    "has_more": true,
    "more_starting_after": "2025-03-26T11:00:17.987Z"
  },
  "tracking_id": "track_C7TLT9aBmso=",
  "order": {
    "items": [
      {
        "object": "order_item",
        "id": "ordli_105e1f56dc0bc19187",
        "quantity": 1,
        "product": {
          "id": "prod_0fc35dfe978defeb6b",
          "source_id": "star-th-bottle",
          "name": "Star Thermal Bottle",
          "metadata": {
            "brand": "Star"
          },
          "price": 2499
        }
      },
      {
        "object": "order_item",
        "id": "ordli_105e1f56dc0bc19188",
        "quantity": 1,
        "product": {
          "id": "prod_0fc35dfeaa0defeb73",
          "source_id": "adv-tshirt",
          "name": "Adventure T-shirt",
          "metadata": {
            "brand": "Adventure"
          },
          "price": 1999
        }
      },
      {
        "object": "order_item",
        "id": "ordli_105e1f56dc0bc19189",
        "quantity": 2,
        "product": {
          "id": "prod_0fc35dfeabcdefeb80",
          "source_id": "adv-scks",
          "name": "Adventure Socks",
          "metadata": {
            "brand": "Adventure"
          },
          "price": 499
        }
      }
    ],
    "customer_id": null,
    "referrer_id": null,
    "object": "order"
  },
  "stacking_rules": {
    "redeemables_limit": 30,
    "applicable_redeemables_limit": 5,
    "applicable_exclusive_redeemables_limit": 1,
    "exclusive_categories": [],
    "joint_categories": [],
    "redeemables_application_mode": "PARTIAL",
    "redeemables_sorting_rule": "REQUESTED_ORDER",
    "redeemables_no_effect_rule": "REDEEM_ANYWAY",
    "redeemables_products_application_mode": "STACK",
    "redeemables_rollback_order_mode": "WITH_ORDER"
  }
}

Authorizations

​
X-App-Id
string
header
required
​
X-App-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
object

Customer's information.

​
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](https://docs.voucherify.io/reference/create-validation-rules) -->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
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
object

Order information.

​
stacking_rules
object

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

⌘I