Overview

Vouchers Validate Response Body

Response body schema for POST v1/vouchers/{code}/validate. One of: Vouchers Validate Valid Response Body, Vouchers Validate Invalid Response Body

Vouchers Validate Valid Response Body

Attributes	Description
valid`boolean`	Indicates whether the voucher is valid within the context of the parameters provided in the request body.
code`string`	Voucher code.
applicable_to	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.Applicable To Result List
inapplicable_to	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.Inapplicable To Result List
campaign`string`	Voucher’s parent campaign name.
campaign_id`string`	Voucher’s parent campaign’s unique ID.
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.
discount	See: Discount
gift	Gift object responseGift
loyalty`object`	Contains the cost of reward in points.Attributes Descriptionpoints_costnumber Number of points that wlil be deducted from loyaty card for the associated reward.
reward`object`	Contains information about the reward that is being validated.Attributes Descriptionidstring Unique reward ID assigned by Voucherify. assignment_idstring Unique reward assignment ID assigned by Voucherify. pointsnumber Number of points applied to the reward.
order	All of: 1. Order Calculated No Customer Data
2.Attributes Descriptionitemsarray Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated
session	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.Session
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.
tracking_id`string`	Hashed order source ID.

Vouchers Validate Invalid Response Body

Attributes	Description
valid`boolean`	Indicates whether the voucher is valid within the context of the parameters provided in the request body.
code`string`	Voucher code.
error`object`	Detailed failure cause for the invalid voucher if the reason has a translation defined in the Dashboard → Project Settings → Error Messages.Attributes Descriptioncodenumber Voucher code. keystring messagestring Customized error message. detailsstring request_idstring resource_idstring resource_typestring
tracking_id`string`	Hashed customer source ID.
customer_id`string`	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.
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.
reason`string`

Applicable To Result List

Attributes	Description
data`array`	Contains array of items to which the discount can apply.Array of Applicable To
total`integer`	Total number of objects defining included products, SKUs, or product collections.
object`string`	The type of the object represented by JSON.Available values: `list`
data_ref`string`	The type of the object represented by JSON.Available values: `data`

Inapplicable To Result List

Attributes	Description
data`array`	Contains array of items to which the discount cannot apply.Array of Inapplicable To
total`integer`	Total number of objects defining included products, SKUs, or product collections.
object`string`	The type of the object represented by JSON.Available values: `list`
data_ref`string`	The type of the object represented by JSON.Available values: `data`

Discount

Contains information about discount. One of: Amount, Unit, Unit Multiple, Percent, Fixed

Gift

Attributes	Description
amount`number`	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`.
subtracted_amount`integer`	Total amount of subtracted credits over the gift card lifetime.
balance`number`	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`.
effect`string`	Defines how the credits are applied to the customer’s order.Available values: `APPLY_TO_ORDER`, `APPLY_TO_ITEMS`

Order Calculated No Customer Data

Attributes	Description
id`string`	Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.
source_id`string`, `null`	Unique source ID of an existing order that will be linked to the redemption of this request.
status`string`	The order status.Available values: `CREATED`, `PAID`, `CANCELED`, `FULFILLED`
amount`integer`	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).
initial_amount`integer`	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).
discount_amount`integer`	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).
items_discount_amount`integer`	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).
total_discount_amount`integer`	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).
total_amount`integer`	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).
applied_discount_amount`integer`	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).
items_applied_discount_amount`integer`	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)`
total_applied_discount_amount`integer`	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`
metadata`object`	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.
object`string`	The type of the object represented by JSON.Available values: `order`
created_at`string`	Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.Example:2021-12-22T10:13:06.487Z
updated_at`string`, `null`	Timestamp representing the date and time when the order was last updated in ISO 8601 format.Example:2021-12-22T10:14:45.316Z
customer_id`string`, `null`	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.Example:cust_7iUa6ICKyU6gH40dBU25kQU1
referrer_id`string`, `null`	Unique referrer ID.Example:cust_nM4jqPiaXUvQdVSA6vTRUnix
customer	Customer Id
referrer	Referrer Id
redemptions`object`	Attributes Description[propertyName] See: Order Redemptions

Order Item Calculated

Attributes	Description
id`string`	Unique identifier of the order line item.
sku_id`string`	Unique identifier of the SKU. It is assigned by Voucherify.
product_id`string`	Unique identifier of the product. It is assigned by Voucherify.
related_object`string`	Used along with the source_id property, can be set to either sku or product.Available values: `product`, `sku`
source_id`string`	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.
quantity`integer`	The quantity of the particular item in the cart.
discount_quantity`integer`	Number of dicounted items.
initial_quantity`integer`	A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items’ quantity.
amount`integer`	The total amount of the order item (price * quantity).
discount_amount`integer`	Sum of all order-item-level discounts applied to the order.
applied_discount_amount`integer`	This field shows the order-level discount applied.
applied_discount_quantity`integer`	Number of the discounted items applied in the transaction.
applied_quantity`integer`	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.
applied_quantity_amount`integer`	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.
initial_amount`integer`	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.
price`integer`	Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`.
subtotal_amount`integer`	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`
product`object`	An object containing details of the related product.Attributes Descriptionidstring A unique identifier that represents the product and is assigned by Voucherify. source_idstring 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. overrideboolean 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. namestring Product name. metadataobject 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. pricenumber Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).
sku`object`	An object containing details of the related SKU.Attributes Descriptionidstring A unique identifier that represents the SKU and is assigned by Voucherify. source_idstring 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. overrideboolean 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. skustring The SKU name. pricenumber SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00). metadataobject 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.
object`string`	The type of the object represented by JSON.Available values: `order_item`
metadata`object`	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.

Session

Attributes	Description
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.
type`string`	This parameter is required to establish a new session.Available values: `LOCK`
ttl`number`	Value for the period of time that the session is active. Units for this parameter are defined by the session.ttl_unit parameter.
ttl_unit`string`	Defines the type of unit in which the session time is counted.Available values: `DAYS`, `HOURS`, `MICROSECONDS`, `MILLISECONDS`, `MINUTES`, `NANOSECONDS`, `SECONDS`

Applicable To

Attributes	Description
object`string`	This object stores information about the resource to which the discount is applicable.Available values: `product`, `sku`, `products_collection`
id`string`	Unique product collection, product, or SKU identifier assigned by Voucherify.
source_id`string`	The source identifier from your inventory system.
product_id`string`	Parent product’s unique ID assigned by Voucherify.
product_source_id`string`	Parent product’s source ID from your inventory system.
price`number`	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.
price_formula`number`	Formula used to dynamically calculate the discounted price of an item.
effect	Defines how the discount is applied to the customer’s order.Applicable To Effect
quantity_limit`integer`	The maximum number of units allowed to be discounted per order line item.
aggregated_quantity_limit`integer`	The maximum number of units allowed to be discounted combined across all matched order line items.
amount_limit`integer`	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.
aggregated_amount_limit`integer`	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) | | order_item_indicesarray | 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. | | order_item_unitsarray | 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.Array of:Attributes Descriptionindexinteger Number assigned to the order line item in accordance with the order sent in the request. unitsarray Numbers 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. units_limit_exceededboolean Returned as true only when the sum total of quantity of all order items exceeds 1000. | | repeatinteger | Determines the recurrence of the discount, e.g. "repeat": 3 means that the discount is applied to every third item. | | skip_initiallyinteger | Determines how many items are skipped before the discount is applied. | | targetstring | Determines to which kinds of objects the discount is applicable. ITEM includes products and SKUs. UNIT means particular units within an order line.Available values: ITEM, UNIT |

Inapplicable To

Applicable To

Amount

Attributes	Description
type`string`	Defines the type of the voucher.Available values: `AMOUNT`
amount_off`number`	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.
amount_off_formula`string`	Formula used to dynamically calculate the discount.
aggregated_amount_limit`integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer’s order.Discount Amount Vouchers Effect Types
is_dynamic`boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type`string`	Discount type.Available values: `UNIT`
unit_off`integer`	Number of units to be granted a full value discount.
unit_off_formula`string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer’s order.Discount Unit Vouchers Effect Types
unit_type`string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product.Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is_dynamic`boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes	Description
type`string`	Discount type.Available values: `UNIT`
effect`string`	Defines how the discount is applied to the customer’s order.Available values: `ADD_MANY_ITEMS`
units`array`	Array of One Unit

Percent

Attributes	Description
type`string`	Defines the type of the voucher.Available values: `PERCENT`
percent_off`number`	The percent discount that the customer will receive.
percent_off_formula`string`	Formula used to dynamically calculate the discount.
amount_limit`number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600.
aggregated_amount_limit`integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer’s order.Discount Percent Vouchers Effect Types
is_dynamic`boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type`string`	Defines the type of the voucher.Available values: `FIXED`
fixed_amount`number`	Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the fallback value. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value.
fixed_amount_formula`string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer’s order.Discount Fixed Vouchers Effect Types
is_dynamic`boolean`	Flag indicating whether the discount was calculated using a formula.

Customer Id

Attributes	Description
id`string`	A unique identifier of an existing customer.
object`string`	The type of the object represented by JSON.Available values: `customer`

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date`string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format.Example:2022-09-02T17:06:56.649Z
rollback_id`string`	Unique ID of the redemption rollback.Example:rr_0c63c84eb78ee0a6c0
rollback_date`string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format.Example:2023-01-31T14:18:37.150Z
related_object_type`string`	The source of the incentive.
related_object_id`string`	Unique ID of the parent redemption.Example:r_0ba186c4824e4881e1
related_object_parent_id`string`	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.
stacked`array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback_stacked`array`	Lists the rollback redemption IDs of the particular child redemptions.

Applicable To Effect

Available values: APPLY_TO_EVERY, APPLY_TO_CHEAPEST, APPLY_FROM_CHEAPEST, APPLY_TO_MOST_EXPENSIVE, APPLY_FROM_MOST_EXPENSIVE

Discount Amount Vouchers Effect Types

Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS, APPLY_TO_ITEMS_PROPORTIONALLY, APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY, APPLY_TO_ITEMS_BY_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD_MISSING_ITEMS, ADD_NEW_ITEMS, ADD_MANY_ITEMS

Simple Product Discount Unit

Attributes	Description
id`string`	Unique product ID, assigned by Voucherify.
source_id`string`	Product’s source ID.
name`string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id`string`	Unique SKU ID, assigned by Voucherify.
source_id`string`	Product variant’s source ID.
name`string`	Sku name

One Unit

Attributes	Description
unit_off`number`	Number of units to be granted a full value discount.
unit_off_formula`string`	Formula used to dynamically calculate the number of units.
effect`string`	Defines how the unit is added to the customer’s order.Available values: `ADD_NEW_ITEMS`, `ADD_MISSING_ITEMS`
unit_type`string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product.Simple Product Discount Unit
sku	Contains information about the sku.Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS

Getting started

Integration Blueprint

Development

Campaigns Recipes

Discounts Recipes

Distributions Recipes

More

Vouchers Validate Response Body

Vouchers Validate Valid Response Body

Vouchers Validate Invalid Response Body

Applicable To Result List

Inapplicable To Result List

Discount

Gift

Order Calculated No Customer Data

Order Item Calculated

Session

Applicable To

Inapplicable To

Amount

Unit

Unit Multiple

Percent

Fixed

Customer Id

Referrer Id

Order Redemptions

Applicable To Effect

Discount Amount Vouchers Effect Types

Discount Unit Vouchers Effect Types

Simple Product Discount Unit

Simple Sku Discount Unit

One Unit

Discount Percent Vouchers Effect Types

Discount Fixed Vouchers Effect Types

​Vouchers Validate Response Body

​Vouchers Validate Valid Response Body

​Vouchers Validate Invalid Response Body

​Applicable To Result List

​Inapplicable To Result List

​Discount

​Gift

​Order Calculated No Customer Data

​Order Item Calculated

​Session

​Applicable To

​Inapplicable To

​Amount

​Unit

​Unit Multiple

​Percent

​Fixed

​Customer Id

​Referrer Id

​Order Redemptions

​Applicable To Effect

​Discount Amount Vouchers Effect Types

​Discount Unit Vouchers Effect Types

​Simple Product Discount Unit

​Simple Sku Discount Unit

​One Unit

​Discount Percent Vouchers Effect Types

​Discount Fixed Vouchers Effect Types

Vouchers Validate Response Body

Vouchers Validate Valid Response Body

Vouchers Validate Invalid Response Body

Applicable To Result List

Inapplicable To Result List

Discount

Gift

Order Calculated No Customer Data

Order Item Calculated

Session

Applicable To

Inapplicable To

Amount

Unit

Unit Multiple

Percent

Fixed

Customer Id

Referrer Id

Order Redemptions

Applicable To Effect

Discount Amount Vouchers Effect Types

Discount Unit Vouchers Effect Types

Simple Product Discount Unit

Simple Sku Discount Unit

One Unit

Discount Percent Vouchers Effect Types

Discount Fixed Vouchers Effect Types