Validate Voucher (client-side)

curl --request GET \
  --url https://{cluster}.voucherify.io/client/v1/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Client-Application-Id: <api-key>' \
  --header 'X-Client-Token: <api-key>' \
  --header 'origin: <origin>'

{
  "valid": false,
  "reason": "customer does not match validation rules",
  "error": {
    "message": "Only the gift card owner can apply credits from the gift card to the order."
  },
  "tracking_id": "track_0nmdnu/6xIb6NTN0Ea40oFmM4wD5QYlxAgKdSn6wh+o",
  "code": "GIFT-CARD-kW4aEsfB",
  "metadata": {}
}

Validate Voucher (client-side)

❗️ 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 customer, you can use this method. It is designed for client side integration which means that is accessible only through public keys. This method is designed to be run directly either in web browsers or mobile apps.

❗️ Specifying gift credits and loyalty points

This endpoint does not support specifying the specific amount of gift credits to apply to an order nor the specific amount of loyalty points to an order. It calculates the amount that is available on the card and applies as much credits or points as possible to cover the total amount.

Set customer identity (optional)

Voucherify can help you track anonymous customers. Once you integrate Voucherify into your web app and call the validate method, Voucherify will return a tracking ID and the script will store it in a cookie. Each subsequent validate call will use the same tracking ID.

Voucherify tracks a user using a tracking ID to see if the user who is validating vouchers is the same as the one who consuming them. Voucherify does this by setting up an identity for the user. A tracking_id will be generated on the server side, unless you specify your own tracking_id. In both cases, you will receive the tracking_id in the validation response.

The returned tracking_id field should be used as the customer source_id in subsequent redemption requests. Moreover, the tracking_id returned from Validation API is encoded. Voucherify will recognize both values for identifying customer - the one before encryption sent as a query parameter to the GET v1/validate request, and the version encrypted and returned as part of the validation request.

Sample workflow

Customer tracking workflow in a nutshell:

Client-side:

A customer visits your website.
A customer validates a voucher code. That triggers a validate request to be sent to Voucherify. In the request, you pass the tracking_id or customer.source_id. As a result, the API call to this endpoint returns an encoded tracking_id.

Backend:

Once the customer finishes the checkout process, your website passes the tracking_id to your backend during a redemption call. The tracking_id is sent as a value assigned to the property source_id in a customer object.
A customer object is created and within the redemption response, you get a customer id.
You can use the customer id or the customer source_id to fetch or modify the customer details.

A customer is created (upserted) automatically with a redemption call. Alternatively, you can create a new profile by creating a customer via a dedicated API method. Take a look at the customer object to understand the entity’s structure.

📘 Customer identifier

The source id of the customer may either be an already hashed version of the tracking_id, which you received in a response from a validation request or a custom ID you predefined (i.e. an email address). Nevertheless, we recommend using identifiers delivered by Voucherify API.

Examples with Query Parameters

Query Parameters	Example URL
Shortcut - `customer` query param instead of `customer[source_id]`	`https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=customer_id`
Pass `customer`’s and `redemption`’s context `metadata` in query parameters	`https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=sure_he_is_new&metadata[shop]=1&customer[metadata][propsy]=2&metadata[test]=true`
Use `tracking_id` instead of `source_id`	`https://api.voucherify.io/client/v1/validate?code=IKU-mvS-JOG&amount=10100&tracking_id=sure_he_is_new_5&metadata[shop]=1&metadata[test]=true`

Reasons why a validation might fail

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] timeframe
voucher is disabled - learn more about disabled vouchers
customer does not match segment rules - learn more about customer tracking
order does not match validation rules - learn more about validation rules

GET

client

validate

Validate Voucher (client-side)

curl --request GET \
  --url https://{cluster}.voucherify.io/client/v1/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Client-Application-Id: <api-key>' \
  --header 'X-Client-Token: <api-key>' \
  --header 'origin: <origin>'

{
  "valid": false,
  "reason": "customer does not match validation rules",
  "error": {
    "message": "Only the gift card owner can apply credits from the gift card to the order."
  },
  "tracking_id": "track_0nmdnu/6xIb6NTN0Ea40oFmM4wD5QYlxAgKdSn6wh+o",
  "code": "GIFT-CARD-kW4aEsfB",
  "metadata": {}
}

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).

Query Parameters

code

string

A code that identifies the voucher.

Example:

"2CpRCE2c"

tracking_id

string

A tracking identifier of a user that validated the voucher. This identifier is generated during voucher validation based on your internal ID (e.g., email, database ID) during the first request. This is a hashed customer source ID. If the request is performed for the first time, pass the internal ID to track the customer. Although not all information is required, the extra information helps prevent fraud.

amount

string

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

session_key

string

The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.

Example:

"ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"

session_ttl

integer

Value for the period of time that the session is active. Units for this parameter are defined by the session_ttl_unit parameter.

session_ttl_unit

enum<string>

Defines the type of unit in which the session time is counted.

Available options:

HOURS,

DAYS,

MINUTES,

SECONDS,

MILLISECONDS,

MICROSECONDS,

NANOSECONDS

metadata

object

Metadata key value pairs.

item

Order Item · object[]

Array of order items.

Show child attributes

session_type

string

The session is required to establish a session between multiple parallel validation and redemption requests. This parameter is required to establish a new session. The session locks the redemption quantity by 1 and additionally the redemption gift credits specified within the request for a gift card and the loyalty points for a loyalty card.

customer

Customer details. Customer source ID and/or customer metadata.

Show child attributes

order

Order details · object

Order details.

Show child attributes

Response

Returns information whether the voucher is valid in the context of the parameter values provided in the query parameters. Moreover, it returns a hashed source identifier which can be used as tracking ID in future calls. If a validation session is established, then the session details will be returned as well. Read more on validation sessions.

Valid - Discount Code
Valid - Gift Card
Valid - Loyalty Card
Not Valid

Response schema model for validating a discount code using POST v1/vouchers/{code}/validate.

valid

boolean

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

applicable_to

Included Items · object

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

Excluded Items · object

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

tracking_id

string

Hashed customer source ID.

order

Order object - Effect: Apply to order · object

This is an object representing an order with calculated discounts applied using the voucher code.

Order object - Effect: Apply to order
Order object - Effect: Apply to items

Show child attributes

code

string

Voucher code.

discount

Amount Discount · object

Contains information about the discount to be applied to the order.

Show child attributes

metadata

object

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.

start_date

string<date-time>

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

Example:

"2022-10-04T00:00:00.000Z"

expiration_date

string<date-time>

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

Example:

"2022-10-31T00:00:00.000Z"

campaign

string

Voucher's parent campaign name.

campaign_id

string

Voucher's parent campaign's unique ID.

Example:

"camp_W8DJVd8J0btqXT6FBwn7BSkC"

session

Session Lock · 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

Last modified on December 11, 2025

Track Custom Event (client-side)Redeem Voucher (client-side)

⌘I

Introduction

Endpoints

Events

Validate Voucher (client-side)

Set customer identity (optional)

Sample workflow

Examples with Query Parameters

Reasons why a validation might fail

Authorizations

Headers

Query Parameters

Response