Endpoints
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 deletedvoucher expired- voucher is out of start date - expiration date time framevoucher is disabled- learn more about a disabled vouchercustomer does not match segment rules- learn more customer trackingorder does not match validation rules- learn more about validation rules
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
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
A code that identifies the voucher.
"2CpRCE2c"
Body
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's information.
Show child attributes
Show child attributes
The ID of an existing customer.
A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored.
Customer's first and last name.
An arbitrary string that you can attach to a customer object.
Customer's email address.
Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.
Deprecated. Customer's birthdate; format YYYY-MM-DD.
Customer's birthdate; format YYYY-MM-DD.
A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments.
Order information.
Show child attributes
Show child attributes
Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.
Unique source ID of an existing order that will be linked to the redemption of this request.
The order status.
CREATED, PAID, CANCELED, FULFILLED 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.
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.
Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Array of items applied to the order. It can include up to 500 items.
Show child attributes
Show child attributes
Unique identifier of the SKU. It is assigned by Voucherify.
Unique identifier of the product. It is assigned by Voucherify.
Used along with the source_id property, can be set to either sku or product.
product, sku The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service.
The quantity of the particular item in the cart.
Number of dicounted items.
A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.
The total amount of the order item (price * quantity).
Sum of all order-item-level discounts applied to the order.
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.
Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
An object containing details of the related product.
Show child attributes
Show child attributes
A unique identifier that represents the product and is assigned by Voucherify.
The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.
The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database.
Product name.
A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).
An object containing details of the related SKU.
Show child attributes
Show child attributes
A unique identifier that represents the SKU and is assigned by Voucherify.
The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.
The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system.
The SKU name.
SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).
A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections.
A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to define business validation rules.
A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas.
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
Show child attributes
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.
This parameter is required to establish a new session.
LOCK Value for the period of time that the session is active. Units for this parameter are defined by the session.ttl_unit parameter.
Defines the type of unit in which the session time is counted.
DAYS, HOURS, MICROSECONDS, MILLISECONDS, MINUTES, NANOSECONDS, SECONDS 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.
Indicates whether the voucher is valid within the context of the parameters provided in the request body.
Voucher code.
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
Show child attributes
Contains array of items to which the discount can apply.
Show child attributes
Show child attributes
This object stores information about the resource to which the discount is applicable.
product, sku, products_collection Unique product collection, product, or SKU identifier assigned by Voucherify.
Defines how the discount is applied to the customer's order.
APPLY_TO_EVERY, APPLY_TO_CHEAPEST, APPLY_FROM_CHEAPEST, APPLY_TO_MOST_EXPENSIVE, APPLY_FROM_MOST_EXPENSIVE The source identifier from your inventory system.
Parent product's unique ID assigned by Voucherify.
Parent product's source ID from your inventory system.
New fixed price of an item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 price is written as 1000. In case of the fixed price being calculated by the formula, i.e. the price_formula parameter is present in the fixed price definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed price.
Formula used to dynamically calculate the discounted price of an item.
The maximum number of units allowed to be discounted per order line item.
The maximum number of units allowed to be discounted combined across all matched order line items.
Upper limit allowed to be applied as a discount per order line item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600.
Maximum discount amount per order. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount on the entire order is written as 600. This value is definable for the following discount effects:
APPLY_TO_ITEMS(each item subtotal is discounted equally)APPLY_TO_ITEMS_BY_QUANTITY(each unit of matched products has the same discount value)
Lists which order lines are (not) covered by the discount. The order in the array is determined by the sequence of applied discounts, while the numbers correspond to the order lines sent in the order object in the request. The first order line is assigned 0, the second order line is assigned 1, and so on.
Lists which units within order lines are covered by the discount. The order line items are listed according to sequence of applied discounts while the index corresponds to the order line sent in the order object in the request.
Show child attributes
Show child attributes
Number assigned to the order line item in accordance with the order sent in the request.
x >= 0Numbers of units in the order line covered by the discount; e.g. 2, 5, 8 for 10 units with the setting "skip_initially": 1, "repeat": 3. The counting of units starts from 1. The maximum quantity of all handled units is 1000. If the quantity of all order items exceeds 1000, this array is not returned, but units_limit_exceeded: true. However, the discount is calculated properly for all relevant units.
Returned as true only when the sum total of quantity of all order items exceeds 1000.
Determines the recurrence of the discount, e.g. "repeat": 3 means that the discount is applied to every third item.
Determines how many items are skipped before the discount is applied.
Determines to which kinds of objects the discount is applicable. ITEM includes products and SKUs. UNIT means particular units within an order line.
ITEM, UNIT Total number of objects defining included products, SKUs, or product collections.
x >= 0The type of the object represented by JSON.
list The type of the object represented by JSON.
data 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
Show child attributes
Contains array of items to which the discount cannot apply.
Show child attributes
Show child attributes
This object stores information about the resource to which the discount is applicable.
product, sku, products_collection Unique product collection, product, or SKU identifier assigned by Voucherify.
Defines how the discount is applied to the customer's order.
APPLY_TO_EVERY, APPLY_TO_CHEAPEST, APPLY_FROM_CHEAPEST, APPLY_TO_MOST_EXPENSIVE, APPLY_FROM_MOST_EXPENSIVE The source identifier from your inventory system.
Parent product's unique ID assigned by Voucherify.
Parent product's source ID from your inventory system.
New fixed price of an item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 price is written as 1000. In case of the fixed price being calculated by the formula, i.e. the price_formula parameter is present in the fixed price definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed price.
Formula used to dynamically calculate the discounted price of an item.
The maximum number of units allowed to be discounted per order line item.
The maximum number of units allowed to be discounted combined across all matched order line items.
Upper limit allowed to be applied as a discount per order line item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600.
Maximum discount amount per order. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount on the entire order is written as 600. This value is definable for the following discount effects:
APPLY_TO_ITEMS(each item subtotal is discounted equally)APPLY_TO_ITEMS_BY_QUANTITY(each unit of matched products has the same discount value)
Lists which order lines are (not) covered by the discount. The order in the array is determined by the sequence of applied discounts, while the numbers correspond to the order lines sent in the order object in the request. The first order line is assigned 0, the second order line is assigned 1, and so on.
Lists which units within order lines are covered by the discount. The order line items are listed according to sequence of applied discounts while the index corresponds to the order line sent in the order object in the request.
Show child attributes
Show child attributes
Number assigned to the order line item in accordance with the order sent in the request.
x >= 0Numbers of units in the order line covered by the discount; e.g. 2, 5, 8 for 10 units with the setting "skip_initially": 1, "repeat": 3. The counting of units starts from 1. The maximum quantity of all handled units is 1000. If the quantity of all order items exceeds 1000, this array is not returned, but units_limit_exceeded: true. However, the discount is calculated properly for all relevant units.
Returned as true only when the sum total of quantity of all order items exceeds 1000.
Determines the recurrence of the discount, e.g. "repeat": 3 means that the discount is applied to every third item.
Determines how many items are skipped before the discount is applied.
Determines to which kinds of objects the discount is applicable. ITEM includes products and SKUs. UNIT means particular units within an order line.
ITEM, UNIT Total number of objects defining included products, SKUs, or product collections.
x >= 0The type of the object represented by JSON.
list The type of the object represented by JSON.
data 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.
Hashed order source ID.
Voucher's parent campaign name.
Voucher's parent campaign's unique ID.
Contains information about discount.
- Discount
- Discount
- Discount
- Discount
- Discount
Show child attributes
Show child attributes
Defines the type of the voucher.
AMOUNT Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.
Formula used to dynamically calculate the discount.
Maximum discount amount per order.
Defines how the discount is applied to the customer's order.
APPLY_TO_ORDER, APPLY_TO_ITEMS, APPLY_TO_ITEMS_PROPORTIONALLY, APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY, APPLY_TO_ITEMS_BY_QUANTITY Flag indicating whether the discount was calculated using a formula.
Gift object response
Show child attributes
Show child attributes
Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
Available funds. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00. balance = amount - subtracted_amount - redemption.redeemed_amount.
Total amount of subtracted credits over the gift card lifetime.
Defines how the credits are applied to the customer's order.
APPLY_TO_ORDER, APPLY_TO_ITEMS Contains information about the reward that is being validated.
Order information.
Show child attributes
Show child attributes
Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.
Unique source ID of an existing order that will be linked to the redemption of this request.
The order status.
CREATED, PAID, CANCELED, FULFILLED This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
This is the sum of the order items' amounts before any discount or other effect (e.g. add missing units) is applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
Sum of all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
sum(items, i => i.applied_discount_amount)
Sum of all order-level AND all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount
A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas.
The type of the object represented by JSON.
order Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
Timestamp representing the date and time when the order was last updated in ISO 8601 format.
"2021-12-22T10:14:45.316Z"
Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.
"cust_7iUa6ICKyU6gH40dBU25kQU1"
Unique referrer ID.
"cust_nM4jqPiaXUvQdVSA6vTRUnix"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format.
"2022-09-02T17:06:56.649Z"
Unique ID of the redemption rollback.
"rr_0c63c84eb78ee0a6c0"
Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format.
"2023-01-31T14:18:37.150Z"
The source of the incentive.
Unique ID of the parent redemption.
"r_0ba186c4824e4881e1"
Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
Lists the rollback redemption IDs of the particular child redemptions.
Array of items applied to the order. It can include up to 500 items.
Show child attributes
Show child attributes
The type of the object represented by JSON.
order_item Unique identifier of the order line item.
Unique identifier of the SKU. It is assigned by Voucherify.
Unique identifier of the product. It is assigned by Voucherify.
Used along with the source_id property, can be set to either sku or product.
product, sku The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service.
The quantity of the particular item in the cart.
Number of dicounted items.
A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.
The total amount of the order item (price * quantity).
Sum of all order-item-level discounts applied to the order.
This field shows the order-level discount applied.
Number of the discounted items applied in the transaction.
Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.
Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.
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.
Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
Final order item amount after the applied item-level discount. If there are no item-level discounts applied, this item is equal to the amount.
subtotal_amount=amount-applied_discount_amount
An object containing details of the related product.
Show child attributes
Show child attributes
A unique identifier that represents the product and is assigned by Voucherify.
The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.
The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system.
Product name.
A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).
An object containing details of the related SKU.
Show child attributes
Show child attributes
A unique identifier that represents the SKU and is assigned by Voucherify.
The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.
The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system.
The SKU name.
SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).
A set of custom key/value pairs that you can attach to an SKU. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
A set of custom key/value pairs that you can attach to an item object. It can be useful for storing additional information about the item in a structured format. It can be used to define business validation rules or discount formulas.
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
Show child attributes
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.
This parameter is required to establish a new session.
LOCK Value for the period of time that the session is active. Units for this parameter are defined by the session.ttl_unit parameter.
Defines the type of unit in which the session time is counted.
DAYS, HOURS, MICROSECONDS, MILLISECONDS, MINUTES, NANOSECONDS, SECONDS Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is inactive before this date.
Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is inactive after this date.
Was this page helpful?