Skip to main content
POST
/
client
/
v1
/
validations
curl --request POST \
  --url https://{cluster}.voucherify.io/client/v1/validations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Application-Id: <api-key>' \
  --header 'X-Client-Token: <api-key>' \
  --header 'origin: <origin>' \
  --data '
{
  "customer": {
    "source_id": "sample_customer",
    "metadata": {
      "key": "value"
    }
  },
  "options": {
    "expand": [
      "order",
      "redeemable",
      "category"
    ]
  },
  "redeemables": [
    {
      "object": "voucher",
      "id": "voucher-code"
    }
  ],
  "session": {
    "type": "LOCK"
  },
  "order": {
    "amount": 55000,
    "status": "PAID",
    "items": [
      {
        "quantity": 2,
        "price": 20000,
        "source_id": "sample product1",
        "related_object": "product",
        "product": {
          "metadata": {
            "key": "value"
          }
        }
      },
      {
        "quantity": 1,
        "price": 15000,
        "source_id": "sample product2",
        "related_object": "product",
        "product": {
          "metadata": {
            "key": "value"
          }
        }
      }
    ],
    "metadata": {
      "key": "value"
    }
  }
}
'
{
  "valid": true,
  "redeemables": [
    {
      "status": "APPLICABLE",
      "id": "<string>",
      "object": "voucher",
      "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
            }
          ]
        }
      },
      "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": {}
          }
        ]
      },
      "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"
        }
      ],
      "campaign_name": "<string>",
      "campaign_id": "camp_pqZjuhG6Mgtp4GD0zD7b8hA3",
      "name": "<string>"
    }
  ],
  "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
  },
  "id": "valid_101740aa2869354c6d",
  "skipped_redeemables": [
    {
      "status": "SKIPPED",
      "id": "<string>",
      "object": "voucher",
      "result": {
        "details": {
          "key": "applicable_redeemables_limit_exceeded",
          "message": "Applicable redeemables limit exceeded"
        }
      },
      "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"
        }
      ],
      "campaign_name": "<string>",
      "campaign_id": "camp_pqZjuhG6Mgtp4GD0zD7b8hA3",
      "name": "<string>"
    }
  ],
  "inapplicable_redeemables": [
    {
      "status": "INAPPLICABLE",
      "id": "<string>",
      "object": "voucher",
      "result": {
        "error": {
          "code": 123,
          "message": "<string>",
          "key": "<string>",
          "details": "<string>",
          "request_id": "v-0a885062c80375740f",
          "resource_id": "rf_0c5d710a87c8a31f86",
          "resource_type": "voucher",
          "error": {
            "message": "<string>"
          }
        },
        "details": {
          "message": "<string>",
          "key": "<string>"
        },
        "bundle": {
          "quantity": 50,
          "limit": 50,
          "identified": [
            {
              "id": "<string>",
              "object": "product",
              "item_index": 1,
              "item_quantity": 123
            }
          ],
          "missing": [
            {
              "id": "<string>",
              "object": "product",
              "item_quantity": 123
            }
          ]
        }
      },
      "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"
        }
      ],
      "campaign_name": "<string>",
      "campaign_id": "camp_pqZjuhG6Mgtp4GD0zD7b8hA3",
      "name": "<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
          }
        ]
      }
    ]
  },
  "tracking_id": "track_VAVo1/z+G2GI2LPw==",
  "session": {
    "key": "<string>",
    "type": "LOCK",
    "ttl": 123,
    "ttl_unit": "DAYS"
  }
}

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.

Headers

​
origin
string<hostname>
required

Indicates the origin (scheme, hostname, and port).

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 /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