curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/{code}/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "id": "cust_4vMj8Twr5nBzvTrNCgipMb6M"
  },
  "order": {
    "items": [
      {
        "product_id": "prod_0ba621bae5d39762ce",
        "quantity": "1"
      },
      {
        "product_id": "prod_0b661d404787ec6d3b",
        "quantity": "1",
        "price": 3100
      }
    ]
  }
}
'

{
  "valid": false,
  "reason": "redemption does not match validation rules",
  "error": {
    "code": 400,
    "key": "redemption_rules_violated",
    "message": "redemption does not match validation rules",
    "details": "Gift Card cannot be redeemed because of violated validation rules: val_wvipKm99CJuL",
    "request_id": "v-0bccef7a9585cf63b6"
  },
  "tracking_id": "track_ZGPtmYcM+Mw=",
  "code": "vBQvYFEM",
  "metadata": {}
}

Validate Voucher

❗️ Deprecated

This endpoint represents the deprecated version of the API responsible for voucher validation, and we do not recommend using it. The new Stackable Discounts API introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. Developers are encouraged to migrate to the latest version to take advantage of the latest enhancements and bug fixes. No updates will be provided to the deprecated endpoint.

To verify a voucher code given by a customer, you can use this method. It is designed for a server side integration, which means that is accessible only through private keys.

❗️ Important

This endpoint supports the validation of a single promo code. If you need to validate more than one incentive, you can use the Stackable discounts API. The stacking discounts API lets you validate up to 30 incentives per call. Before integrating Voucherify, choose which validation endpoint you prefer to use.

Gift Vouchers - validate Gift Card and control amount to redeem

Voucherify also gives the possibility to create a gift card, which allows using credits to fulfill the order. A user can specify how many credits he wants to use from the gift card. The available balance of credits is counted based on policy rules attached to the Gift Voucher definition.

This operation returns information about the validity of the code. Moreover, it returns a hashed source identifier which can be used as a tracking ID in future calls.

If a validation session is established, then the session details will be returned as well. Read more about sessions here.

Voucher validation might fail because of one of these reasons:

voucher not found - voucher doesn’t exist or was deleted
voucher expired - voucher is out of start date - expiration date time frame
voucher is disabled - learn more about a disabled voucher
customer does not match segment rules - learn more customer tracking
order does not match validation rules - learn more about validation rules

POST

vouchers

{code}

validate

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/{code}/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "id": "cust_4vMj8Twr5nBzvTrNCgipMb6M"
  },
  "order": {
    "items": [
      {
        "product_id": "prod_0ba621bae5d39762ce",
        "quantity": "1"
      },
      {
        "product_id": "prod_0b661d404787ec6d3b",
        "quantity": "1",
        "price": 3100
      }
    ]
  }
}
'

{
  "valid": false,
  "reason": "redemption does not match validation rules",
  "error": {
    "code": 400,
    "key": "redemption_rules_violated",
    "message": "redemption does not match validation rules",
    "details": "Gift Card cannot be redeemed because of violated validation rules: val_wvipKm99CJuL",
    "request_id": "v-0bccef7a9585cf63b6"
  },
  "tracking_id": "track_ZGPtmYcM+Mw=",
  "code": "vBQvYFEM",
  "metadata": {}
}

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.

Path Parameters

code

string

required

A code that identifies the voucher.

Example:

"2CpRCE2c"

Body

application/json

Specify the voucher validation context using the request body parameters.

Vouchers Validate Discount Request Body
Vouchers Validate Gift Request Body
Vouchers Validate Loyalty Request Body

Request schema model for validating a voucher using POST v1/vouchers/{code}/validate.

customer

Customer · object

Customer's information.

Show child attributes

order

Order · object

Order information.

Show child attributes

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.

Show child attributes

tracking_id

string

metadata

object

options

object

Show child attributes

Response

Returns information whether the voucher is valid in the context of the parameter values provided in the request body.

Vouchers Validate Valid Response Body
Vouchers Validate Invalid Response Body

Response body schema for POST v1/vouchers/{code}/validate.

valid

boolean

default:true

required

Indicates whether the voucher is valid within the context of the parameters provided in the request body.

code

string

required

Voucher code.

applicable_to

Applicable To Result List · object

required

Contains list of items that qualify in the scope of the discount. These are definitions of included products, SKUs, and product collections. These can be discounted.

Show child attributes

inapplicable_to

Inapplicable To Result List · object

required

Contains list of items that do not qualify in the scope of the discount. These are definitions of excluded products, SKUs, and product collections. These CANNOT be discounted.

Show child attributes

metadata

object

required

The metadata object stores all custom attributes assigned to the code. A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format.

tracking_id

string

required

Hashed order source ID.

campaign

string

Voucher's parent campaign name.

campaign_id

string

Voucher's parent campaign's unique ID.

discount

Discount · object

Contains information about discount.

Discount
Discount
Discount
Discount
Discount

Show child attributes

gift

Gift · object

Gift object response

Show child attributes

loyalty

object

Contains the cost of reward in points.

Show child attributes

reward

object

Contains information about the reward that is being validated.

Show child attributes

order

Order Calculated No Customer Data · object

Order information.

Show child attributes

session

Session · object

Schema model for session lock object. The session object contains information about the session key that was used to establish a session between multiple parallel validation and redemption requests.

Show child attributes

start_date

string

Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is inactive before this date.

expiration_date

string

Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is inactive after this date.

Last modified on December 11, 2025

Validate Stackable Discounts Validate Promotions

⌘I

Introduction

Endpoints

Events

Validate Voucher

Gift Vouchers - validate Gift Card and control amount to redeem

Authorizations

Path Parameters

Body

Response