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
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 response Gift | ||||||||
loyaltyobject | Contains the cost of reward in points.
| ||||||||
rewardobject | Contains information about the reward that is being validated.
| ||||||||
order | See: 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_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.
| ||||||||||||||||
tracking_idstring | Hashed customer source ID. | ||||||||||||||||
customer_idstring | Unique customer ID of the customer making the purchase. | ||||||||||||||||
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 object represented by JSON. Available values:list |
data_refstring | The type of 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 object represented by JSON. Available values:list |
data_refstring | The type of 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. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000. |
balancenumber | Available funds. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000. |
effectstring | Defines how the credits are applied to the customer's order. Available values:APPLY_TO_ORDER , APPLY_TO_ITEMS |
Order Calculated
All of:
- Order Response Base
-
Order Calculated
Attributes Description customer One of: Customer With Summary Loyalty Referrals, Customer Id referrer One of: Referrer With Summary Loyalty Referrals, Referrer Id
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. Available values:LOCK |
typestring | This parameter is required to establish a new session. The session locks the redemption quantity by 1. 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 product collection. Available values:product , sku , products_collection |
idstring | Unique product collection ID assigned by Voucherify. |
source_idstring | The source ID 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. |
strictboolean | |
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 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:
|
order_item_indicesarray |
Inapplicable 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 | |
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 | |
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 | |
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_formulastring | |
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. |
Order Response Base
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. | ||||
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 | ||||
statusstring | The order status. Available values:CREATED , PAID , CANCELED , FULFILLED | ||||
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. | ||||
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. | ||||
discount_amountinteger | Sum of all order-level discounts applied to the order. | ||||
items_discount_amountinteger | Sum of all product-specific discounts applied to the order. | ||||
total_discount_amountinteger | Sum of all order-level AND all product-specific discounts applied to the order. | ||||
total_amountinteger | Order amount after undoing all the discounts through the rollback redemption. | ||||
applied_discount_amountinteger | This field shows the order-level discount applied. | ||||
items_applied_discount_amountinteger | Sum of all product-specific discounts applied in a particular request. | ||||
total_applied_discount_amountinteger | Sum of all order-level AND all product-specific discounts applied in a particular request. | ||||
itemsarray | Array of items applied to the order. Array of Order Item Calculated | ||||
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. | ||||
customer_idstring , null | Unique customer ID of the customer making the purchase. Example:cust_7iUa6ICKyU6gH40dBU25kQU1 | ||||
referrer_idstring , null | Unique referrer ID. Example:cust_nM4jqPiaXUvQdVSA6vTRUnix | ||||
objectstring | The type of object represented by JSON. Available values:order | ||||
redemptionsobject |
|
Customer With Summary Loyalty Referrals
All of:
-
Customer Response Data
Attributes Description id string
The ID of an existing customer that will be linked to redemption in this request.
source_id string
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.
summary Customer Summary loyalty Customer Loyalty referrals Customer Referrals system_metadata object
Object used to store system metadata information.
created_at string
Timestamp representing the date and time when the customer was created. The value is shown in the ISO 8601 format.
Example:2022-08-30T06:32:07.380Z
updated_at string
Timestamp representing the date and time when the customer was updated. The value is shown in the ISO 8601 format.
Example:2022-08-31T06:32:07.380Z
assets object
Contains information about the customer's cockpit.
Attributes Description cockpit_url string
Customer's cockpit URL address.
object string
The type of object represented by JSON.
Available values:customer
- Customer Base
Customer Id
Attributes | Description |
---|---|
idstring | A unique identifier of an existing customer. |
objectstring | The type of object represented by JSON. Available values:customer |
Referrer With Summary Loyalty Referrals
Customer With Summary Loyalty Referrals
Referrer 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
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 | |
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
Order Item Calculated
Attributes | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sku_idstring | A unique SKU ID assigned by Voucherify. | ||||||||||||||
product_idstring | A unique product ID 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. | ||||||||||||||
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. | ||||||||||||||
total_applied_discount_amountinteger | Sum of all order-level AND all product-specific discounts applied in a particular request. | ||||||||||||||
priceinteger | Unit price of an item. Value is multiplied by 100 to precisely represent 2 decimal places. For example | ||||||||||||||
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 | ||||||||||||||
productobject | An object containing details of the related product.
| ||||||||||||||
skuobject | An object containing details of the related SKU.
| ||||||||||||||
objectstring | The type of object represented by JSON. Available values:order_item | ||||||||||||||
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. |
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 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_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. |
Customer Summary
Attributes | Description |
---|---|
redemptions | See: Customer Summary Redemptions |
orders | See: Customer Summary Orders |
Customer Loyalty
Attributes | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pointsinteger | Customer's loyalty points. | ||||||||||||
referred_customersinteger | Total number of customers referred by the customer. | ||||||||||||
campaignsobject | Contains campaigns with details about point balances and how many customers were referred by the customer.
|
Customer Referrals
Customer Base
Attributes | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namestring | Customer's first and last name. | ||||||||||||||
descriptionstring | An arbitrary string that you can attach to a customer object. | ||||||||||||||
emailstring | Customer's email address. | ||||||||||||||
phonestring | Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. | ||||||||||||||
birthdaystring |
| ||||||||||||||
birthdatestring | Customer's birthdate; format YYYY-MM-DD. | ||||||||||||||
addressobject , null | Customer's address.
| ||||||||||||||
metadataobject | 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. |
Customer Summary Redemptions
Attributes | Description | ||||||
---|---|---|---|---|---|---|---|
total_redeemedinteger | Total number of redemptions made by the customer. | ||||||
total_failedinteger | Total number of redemptions that failed. | ||||||
total_succeededinteger | Total number of redemptions that succeeded. | ||||||
total_rolled_backinteger | Total number of redemptions that were rolled back for the customer. | ||||||
total_rollback_failedinteger | Total number of redemption rollbacks that failed. | ||||||
total_rollback_succeededinteger | Total number of redemption rollbacks that succeeded. | ||||||
giftobject | Summary of gift card credits.
| ||||||
loyalty_cardobject | Summary of loyalty points.
|
Customer Summary Orders
Attributes | Description |
---|---|
total_amountinteger | The total amount spent by the customer. Value is multiplied by 100 to precisely represent 2 decimal places. For example |
total_countinteger | Total number of orders made by the customer. |
average_amountinteger | Average amount spent on orders. |
last_order_amountinteger | Amount spent on last order. Value is multiplied by 100 to precisely represent 2 decimal places. For example |
last_order_datestring | Timestamp representing the date and time of the customer's last order in ISO 8601 format. Example:2022-08-30T11:51:08.029Z |