Skip to main content
POST
/
v1
/
validations
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/validations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "redeemables": [
    {
      "object": "voucher",
      "id": "BLCKFRDY"
    }
  ],
  "order": {
    "amount": 5500
  }
}
'
{
  "id": "valid_101740aa2869354c6d",
  "valid": false,
  "redeemables": [
    {
      "status": "INAPPLICABLE",
      "id": "eee33463",
      "object": "voucher",
      "result": {
        "error": {
          "code": 404,
          "key": "not_found",
          "message": "Resource not found",
          "details": "Cannot find voucher with id eee33463",
          "request_id": "v-0c6c6e20dc42940f0b",
          "resource_id": "eee33463",
          "resource_type": "voucher"
        }
      }
    },
    {
      "status": "SKIPPED",
      "id": "promo_Mwy9XpA0TLctSGriM5kum0qp",
      "object": "promotion_tier",
      "result": {}
    }
  ],
  "tracking_id": "track_VAVW6qltuo1/z+G2GI2LPw==",
  "stacking_rules": {
    "redeemables_limit": 30,
    "applicable_redeemables_limit": 30,
    "applicable_exclusive_redeemables_limit": 5,
    "applicable_redeemables_per_category_limit": 30,
    "applicable_redeemables_category_limits": {},
    "exclusive_categories": [
      "cat_0e1d0ba106c17fa350"
    ],
    "joint_categories": [
      "cat_0e1d0ba99c2fff2b51"
    ],
    "redeemables_application_mode": "PARTIAL",
    "redeemables_sorting_rule": "REQUESTED_ORDER",
    "redeemables_no_effect_rule": "REDEEM_ANYWAY",
    "no_effect_skip_categories": [
      "cat_0e156dab8f2e43873a"
    ],
    "no_effect_redeem_anyway_categories": [
      "cat_0e1d0ba106c17fa350"
    ],
    "redeemables_products_application_mode": "STACK",
    "redeemables_rollback_order_mode": "WITHOUT_ORDER",
    "grouped_redeemables_sorting_rule": "JOINT_ALWAYS_LAST"
  }
}

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

Request body schema for POST v1/validations.

​
redeemables
(Voucher Redeemable · object | Promotion Tier Redeemable · object | Promotion Stack Redeemable · object | Gift Card Redeemable · object | Loyalty Card Redeemable · object)[]
required

An array of redeemables. You can combine voucher(s) and promotion_tier(s). Alternatively, send one uniquepromotion_stack in the array. Each unique redeemable can be sent in one request only once.

Required array length: 1 - 30 elements

Validate or redeem a discount code.

​
options
object

Configure parameters returned in the response.

​
order
Order · object

Order information.

​
customer
Customer · object

Customer's information.

​
session
Session · object

Schema model for session lock object. The session object is required to establish a session between multiple parallel validation and redemption requests. If you only send the type parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a validation session.

​
tracking_id
string

Is correspondent to Customer's source_id

​
metadata
object

A set of key/value pairs that you can attach to a redemption object. It can be useful for storing additional information about the redemption in a structured format.

Response

Depending on your project settings: all redeemables must be valid or just one must be valid to result as valid validation. Read more in the Stacking Rule Documentation.

Response body schema for POST v1/validations.

​
valid
boolean
required

The result of the validation. It takes all of the redeemables into account and returns a false if at least one redeemable is inapplicable. Returns true if all redeemables are applicable.

​
redeemables
(Applicable Redeemable · object | Inapplicable Redeemable · object | Skipped Redeemable · object)[]
required

Lists validation results of each redeemable. If redeemables_application_mode is PARTIAL in the stacking_rules object, all redeemables here will be APPLICABLE. Read more in the Stacking rules article.

​
stacking_rules
Stacking Rules · object
required

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

​
id
string

Unique identifier of the validation, assigned by Voucherify.

Example:

"valid_101740aa2869354c6d"

​
skipped_redeemables
Skipped Redeemable · object[]

Lists validation results of each skipped redeemable.

​
inapplicable_redeemables
Inapplicable Redeemable · object[]

Lists validation results of each inapplicable redeemable.

​
order
Order Calculated No Customer Data · object

Order information.

​
tracking_id
string

Hashed customer source ID.

Example:

"track_VAVo1/z+G2GI2LPw=="

​
session
Session · object
Last modified on December 11, 2025