Validation Object

Vouchers Validate Response Body

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

One of:

Vouchers Validate Valid Response Body, Vouchers Validate Invalid Response Body

Vouchers Validate Valid Response Body

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

discountSee: Discount
gift

Gift object response

Gift
loyalty
object

Contains the cost of reward in points.

AttributesDescription
points_cost
number

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.

AttributesDescription
id
string

Unique reward ID assigned by Voucherify.

assignment_id
string

Unique reward assignment ID assigned by Voucherify.

points
number

Number of points applied to the reward.

orderSee: Order 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

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

AttributesDescription
code
number

Voucher code.

key
string
message
string

Customized error message.

details
string
request_id
string
resource_id
string
resource_type
string
tracking_id
string

Hashed customer source ID.

customer_id
string

Unique customer ID of the customer making the purchase.

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

AttributesDescription
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

AttributesDescription
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

AttributesDescription
amount
number

Total gift card income over the lifetime of the card. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000.

balance
number

Available funds. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000.

effect
string

Defines how the credits are applied to the customer's order.

Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS

Order Calculated

All of:

  1. Order Response Base
  2. Order Calculated

    AttributesDescription
    customerOne of: Customer Id
    referrerOne of: Referrer Id

Session

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

Available values: LOCK
type
string

This parameter is required to establish a new session. The session locks the redemption quantity by 1.

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

AttributesDescription
object
string

This object stores information about the product collection.

Available values: product, sku, products_collection
id
string

Unique product collection ID assigned by Voucherify.

source_id
string

The source ID 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.

strict
boolean
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 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_indices
array

Inapplicable To

Applicable To

Amount

AttributesDescription
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
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

AttributesDescription
type
string

Discount type.

Available values: UNIT
unit_off
integer

Number of units to be granted a full value discount.

unit_off_formula
string
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
skuSee: Simple Sku Discount Unit
is_dynamic
boolean

Flag indicating whether the discount was calculated using a formula.

Unit Multiple

AttributesDescription
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

AttributesDescription
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
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

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

Order Response Base

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

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED
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.

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.

discount_amount
integer

Sum of all order-level discounts applied to the order.

items_discount_amount
integer

Sum of all product-specific discounts applied to the order.

total_discount_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order.

total_amount
integer

Order amount after undoing all the discounts through the rollback redemption.

applied_discount_amount
integer

This field shows the order-level discount applied.

items_applied_discount_amount
integer

Sum of all product-specific discounts applied in a particular request.
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.
total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount

items
array

Array of items applied to the order.

Array of Order Item Calculated
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.

customer_id
string, null

Unique customer ID of the customer making the purchase.

Example:

cust_7iUa6ICKyU6gH40dBU25kQU1

referrer_id
string, null

Unique referrer ID.

Example:

cust_nM4jqPiaXUvQdVSA6vTRUnix

object
string

The type of the object represented by JSON.

Available values: order
redemptions
object
AttributesDescription
[propertyName]See: Order Redemptions

Customer Id

AttributesDescription
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

Applicable To Effect

Available values: APPLY_TO_EVERY, APPLY_TO_CHEAPEST, APPLY_TO_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

AttributesDescription
id
string

Unique product ID, assigned by Voucherify.

source_id
string

Product's source ID.

name
string

Product name.

Simple Sku Discount Unit

AttributesDescription
id
string

Unique SKU ID, assigned by Voucherify.

source_id
string

Product variant's source ID.

name
string

Sku name

One Unit

AttributesDescription
unit_off
number

Number of units to be granted a full value discount.

unit_off_formula
string
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

Order Item Calculated

AttributesDescription
sku_id
string

A unique SKU ID assigned by Voucherify.

product_id
string

A unique product ID 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.

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.

total_applied_discount_amount
integer

Sum of all order-level AND all product-specific discounts applied in a particular request.
total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount

price
integer

Unit price of an item. Value is multiplied by 100 to precisely 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.

AttributesDescription
id
string

A unique identifier that represents the product and is assigned by Voucherify.

source_id
string

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.

override
boolean

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.

name
string

Product name.

metadata
object

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.

price
number

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.

AttributesDescription
id
string

A unique identifier that represents the SKU and is assigned by Voucherify.

source_id
string

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.

override
boolean

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.

sku
string

The SKU name.

price
number

SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

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 SKU. It can be useful for storing additional information about the SKU in a structured format.

Order Redemptions

AttributesDescription
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 tiem 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.