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
validboolean	Indicates whether the voucher is valid within the context of the parameters provided in the request body.
codestring	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
campaignstring	Voucher’s parent campaign name.
campaign_idstring	Voucher’s parent campaign’s unique ID.
metadataobject	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
loyaltyobject	Contains the cost of reward in points.Attributes Descriptionpoints_costnumber Number of points that wlil be deducted from loyaty card for the associated reward.
rewardobject	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_datestring	Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is inactive before this date.
expiration_datestring	Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is inactive after this date.
tracking_idstring	Hashed order source ID.

Vouchers Validate Invalid Response Body

Attributes	Description
validboolean	Indicates whether the voucher is valid within the context of the parameters provided in the request body.
codestring	Voucher code.
errorobject	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_idstring	Hashed customer source ID.
customer_idstring	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.
metadataobject	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.
reasonstring

Applicable To Result List

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

Inapplicable To Result List

Attributes	Description
dataarray	Contains array of items to which the discount cannot apply.Array of Inapplicable To
totalinteger	Total number of objects defining included products, SKUs, or product collections.
objectstring	The type of the object represented by JSON.Available values: list
data_refstring	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
amountnumber	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_amountinteger	Total amount of subtracted credits over the gift card lifetime.
balancenumber	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.
effectstring	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
idstring	Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.
source_idstring, null	Unique source ID of an existing order that will be linked to the redemption of this request.
statusstring	The order status.Available values: CREATED, PAID, CANCELED, FULFILLED
amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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_amountinteger	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
metadataobject	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.
objectstring	The type of the object represented by JSON.Available values: order
created_atstring	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_atstring, 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_idstring, null	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.Example:cust_7iUa6ICKyU6gH40dBU25kQU1
referrer_idstring, null	Unique referrer ID.Example:cust_nM4jqPiaXUvQdVSA6vTRUnix
customer	Customer Id
referrer	Referrer Id
redemptionsobject	Attributes Description[propertyName] See: Order Redemptions

Order Item Calculated

Attributes	Description
idstring	Unique identifier of the order line item.
sku_idstring	Unique identifier of the SKU. It is assigned by Voucherify.
product_idstring	Unique identifier of the product. It is assigned by Voucherify.
related_objectstring	Used along with the source_id property, can be set to either sku or product.Available values: product, sku
source_idstring	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.
quantityinteger	The quantity of the particular item in the cart.
discount_quantityinteger	Number of dicounted items.
initial_quantityinteger	A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items’ quantity.
amountinteger	The total amount of the order item (price * quantity).
discount_amountinteger	Sum of all order-item-level discounts applied to the order.
applied_discount_amountinteger	This field shows the order-level discount applied.
applied_discount_quantityinteger	Number of the discounted items applied in the transaction.
applied_quantityinteger	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_amountinteger	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_amountinteger	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.
priceinteger	Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
subtotal_amountinteger	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
productobject	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).
skuobject	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.
objectstring	The type of the object represented by JSON.Available values: order_item
metadataobject	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
keystring	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.
typestring	This parameter is required to establish a new session.Available values: LOCK
ttlnumber	Value for the period of time that the session is active. Units for this parameter are defined by the session.ttl_unit parameter.
ttl_unitstring	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
objectstring	This object stores information about the resource to which the discount is applicable.Available values: product, sku, products_collection
idstring	Unique product collection, product, or SKU identifier assigned by Voucherify.
source_idstring	The source identifier from your inventory system.
product_idstring	Parent product’s unique ID assigned by Voucherify.
product_source_idstring	Parent product’s source ID from your inventory system.
pricenumber	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_formulanumber	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_limitinteger	The maximum number of units allowed to be discounted per order line item.
aggregated_quantity_limitinteger	The maximum number of units allowed to be discounted combined across all matched order line items.
amount_limitinteger	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_limitinteger	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
typestring	Defines the type of the voucher.Available values: AMOUNT
amount_offnumber	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_formulastring	Formula used to dynamically calculate the discount.
aggregated_amount_limitinteger	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer’s order.Discount Amount Vouchers Effect Types
is_dynamicboolean	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
typestring	Discount type.Available values: UNIT
unit_offinteger	Number of units to be granted a full value discount.
unit_off_formulastring	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_typestring	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_dynamicboolean	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes	Description
typestring	Discount type.Available values: UNIT
effectstring	Defines how the discount is applied to the customer’s order.Available values: ADD_MANY_ITEMS
unitsarray	Array of One Unit

Percent

Attributes	Description
typestring	Defines the type of the voucher.Available values: PERCENT
percent_offnumber	The percent discount that the customer will receive.
percent_off_formulastring	Formula used to dynamically calculate the discount.
amount_limitnumber	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_limitinteger	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer’s order.Discount Percent Vouchers Effect Types
is_dynamicboolean	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
typestring	Defines the type of the voucher.Available values: FIXED
fixed_amountnumber	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_formulastring	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_dynamicboolean	Flag indicating whether the discount was calculated using a formula.

Customer Id

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

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
datestring	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_idstring	Unique ID of the redemption rollback.Example:rr_0c63c84eb78ee0a6c0
rollback_datestring	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_typestring	The source of the incentive.
related_object_idstring	Unique ID of the parent redemption.Example:r_0ba186c4824e4881e1
related_object_parent_idstring	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.
stackedarray	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback_stackedarray	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
idstring	Unique product ID, assigned by Voucherify.
source_idstring	Product’s source ID.
namestring	Product name.

Simple Sku Discount Unit

Attributes	Description
idstring	Unique SKU ID, assigned by Voucherify.
source_idstring	Product variant’s source ID.
namestring	Sku name

One Unit

Attributes	Description
unit_offnumber	Number of units to be granted a full value discount.
unit_off_formulastring	Formula used to dynamically calculate the number of units.
effectstring	Defines how the unit is added to the customer’s order.Available values: ADD_NEW_ITEMS, ADD_MISSING_ITEMS
unit_typestring	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