Overview

Read our dedicated guide to learn about some use cases these endpoints can cover here.

Qualifications Check Eligibility Response Body

Attributes	Description
redeemables	See: Redeemables
tracking_idstring	This identifier is generated during voucher qualification based on your internal id (e.g., email, database ID). This is a hashed customer source ID.
orderobject	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.
stacking_rules	See: Stacking Rules

Redeemables

Attributes	Description
objectstring	The type of the object represented by JSON. Default is list.Available values: list
data_refstring	Identifies the name of the attribute that contains the array of qualified redeemables.Available values: data
dataarray	Array of qualified redeemables.Array of Combined response of redeemable object and multiple redeemables within
totalinteger	The number of redeemables returned in the API request.Example:5
has_moreboolean	As results are always limited, the has_more flag indicates if there are more records for given parameters. This lets you know if you can run another request (with different options) to get more records returned in the results.
more_starting_afterstring	Timestamp representing the date and time to use in starting_after cursor to get more redeemables.Example:2023-10-31T12:13:16.374Z

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

Stacking Rules

Attributes	Description
redeemables_limitinteger	Defines how many redeemables can be sent in one request. Note: more redeemables means more processing time.
applicable_redeemables_limitinteger	Defines how many redeemables can be applied in one request. The number must be less than or equal to redeemables_limit. For example, a user can select 30 discounts but only 5 will be applied to the order and the remaining will be SKIPPED according to the redeemables_sorting_rule.
applicable_redeemables_per_category_limitinteger	Defines how many redeemables with the same category can be applied in one request. The number must be less than or equal to applicable_redeemables_limit. The ones above the limit will be SKIPPED according to the redeemables_sorting_rule.
applicable_exclusive_redeemables_limitinteger	Defines how many redeemables with an assigned exclusive category can be applied in one request. The ones above the limit will be SKIPPED according to the redeemables_sorting_rule.
applicable_exclusive_redeemables_per_category_limitinteger	Defines how many redeemables with an exclusive category per category in stacking rules can be applied in one request. The ones above the limit will be SKIPPED according to the redeemables_sorting_rule.
exclusive_categoriesarray	Lists the IDs of exclusive categories. A redeemable from a campaign with an exclusive category is the only redeemable to be redeemed when applied with redeemables from other campaigns unless these campaigns are exclusive or joint.
joint_categoriesarray	Lists the IDs of the joint categories. A campaign with a joint category is always applied regardless of the exclusivity of other campaigns.
redeemables_application_modestring	Defines the application mode for redeemables."ALL" means that all redeemables must be validated for the redemption to be successful."PARTIAL" means that only those redeemables that can be validated will be redeemed. The redeemables that fail validaton will be skipped.Available values: ALL, PARTIAL
redeemables_sorting_rulestring	Defines redeemables sorting rule. CATEGORY_HIERARCHY means that redeemables are applied oaccording to the category priority. REQUESTED_ORDER means that redeemables are applied in the sequence provided in the request.Available values: CATEGORY_HIERARCHY, REQUESTED_ORDER
redeemables_products_application_modestring	Defines redeemables products application mode. STACK means that multiple discounts can be applied to a product. ONCE means that only one discount can be applied to the same product.Available values: STACK, ONCE
redeemables_no_effect_rulestring	Defines redeemables no effect rule. REDEEM_ANYWAY means that the redeemable will be redeemed regardless of any restrictions or conditions in place. SKIP means that the redeemable will be processed only when an applicable effect is calculated.Available values: REDEEM_ANYWAY, SKIP
no_effect_skip_categoriesarray	Lists category IDs. Redeemables with a given category are skipped even if the redeemables_no_effect_rule is set to REDEEM_ANYWAY. Category IDs can’t overlap with the IDs in no_effect_redeem_anyway_categories.
no_effect_redeem_anyway_categoriesarray	Lists category IDs. Redeemables with a given category are redeemed anyway even if the redeemables_no_effect_rule is set to SKIP. Category IDs can’t overlap with the IDs in no_effect_skip_categories.
redeemables_rollback_order_modestring	Defines the rollback mode for the order. WITH_ORDER is a default setting. The redemption is rolled back together with the data about the order, including related discount values. WITHOUT_ORDER allows rolling the redemption back without affecting order data, including the applied discount values.Available values: WITH_ORDER, WITHOUT_ORDER

Combined response of redeemable object and multiple redeemables within

All of:

1. Single redeemable

2. Attributes	Description
   redeemablesarray	Array of Single redeemable

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.

Single redeemable

Attributes	Description
idstring	ID of the redeemable. For a voucher, it’s its code value.
objectstring	Object type of the redeemable.Available values: campaign, promotion_tier, promotion_stack, voucher
created_atstring	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.Example:2022-03-09T11:19:04.819Z
result	See: Redeemable Result
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.
validation_rule_idstring	A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance.
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
metadataobject	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.
categoriesarray	List of category information.Array of Category with Stacking Rules Type
bannerstring	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.Example:Order Paid - You will get 100 points
namestring	Name of the redeemable.Example:promotion_tier_get_points
campaign_namestring	Name of the campaign associated to the redeemable. This field is available only if object is not campaignExample:PromotionCampaign
campaign_idstring	Id of the campaign associated to the redeemable. This field is available only if object is not campaignExample:camp_Mow7u4gSxagLlZ2oDQ01ZS5N
validation_rules_assignments	See: Validation Rules Assignments List

Redeemable Result

Attributes	Description
discount	See: Discount
bundle	See: Bundle Details
gift	See: Redeemable Gift
loyalty_card	Loyalty Card object responseRedeemable Loyalty Card
error	Error in resultError Object

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

Category with Stacking Rules Type

Category object with stacking_rules_type

All of:

1. Category

2. Attributes	Description
   stacking_rules_typestring	The type of the stacking rule eligibility.Available values: JOINT, EXCLUSIVE

Validation Rules Assignments List

Attributes	Description
objectstring	The type of the object represented by JSON. This object stores information about validation rules assignments.Available values: list
data_refstring	Identifies the name of the attribute that contains the array of validation rules assignments.Available values: data
dataarray	Contains array of validation rules assignments.Array of Business Validation Rule Assignment
totalinteger	Total number of validation rules assignments.

Discount

Contains information about discount.

One of:

Amount, Unit, Unit Multiple, Percent, Fixed

Bundle Details

Attributes	Description
quantityinteger	Determines how many bundles are qualified. If there are missing bundle products, the value is 0. If the bundle is qualified, the value is 1. The maximum number of identified bundles can equal the number set in limit. Also defines the multiplier of the discount for AMOUNT, PERCENT, and UNIT discount types. To inform end-customers that more products can be added to meet additional bundles, compare this parameter with limit.
limitinteger	Determines the maximum number of identified bundles. This also defines the maximum multiplier of the bundle discount.
identifiedarray	Determines products from the customer’s order items that meet bundle conditions. SKUs meet the conditions for their product that is used in the bundle. Returns only the products and their quantity that meet the bundle.Array of:Attributes Descriptionidstring Unique identifier of the product or SKU that meets the bundle condition. This is an ID assigned by Voucherify. objectstring Determines the type of the object that meets the bundle condition. Available values: product, sku item_indexinteger Number assigned to the order line item in accordance with the order sent in the request. It starts with 0 for the first order line item in the request. item_quantityinteger Quantity of items that meet the bundle conditions. If the quantity in the order is higher than the quantity required by the bundle, this returns only the number that meets the bundle. For example, if the bundle requires 5 coffees, but the order includes 10 coffees, item_quantity returns 5.
missingarray	Determines products, SKUs, or collections from the bundle that are missing in the customer’s order items. Determines also the missing quantity. For collections, this means that order items do not include a sufficient number of items that belong to the collection. Not returned when all required bundle items are in the order.Array of:Attributes Descriptionidstring Unique identifier of the collection, product, or SKU that is missing in the customer’s order items. This is an ID assigned by Voucherify. objectstring Determines the type of the object that is missing in the customer’s order items. Available values: product, products_collection, sku item_quantityinteger Quantity of items that are missing in the order items to meet the bundle conditions.

Redeemable Gift

Attributes	Description
balancenumber	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
creditsnumber	The number of credits that the user wants to use from the gift card to fulfil the order. The value of credits cannot be higher than the current balance on the gift card. If the user gives more points than he has on the gift card, the application will return an error code in response. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
locked_creditsnumber	The number of credits that are locked under a validation session. This is returned if the qualification request includes session.type: LOCK parameter in the body. The value is multiplied by 100 to represent 2 decimal places. For example 10000 for $100.00. Returns 0 if there aren’t any active validation sessions for the gift card.

Redeemable Loyalty Card

Attributes	Description
pointsinteger	Total number of points added to the loyalty card over its lifespan.Example:7000
balanceinteger	Points available for reward redemption. This is calculated as follows: balance = points - expired_points - subtracted_points - redemption.redeemed_points.Example:6970
exchange_rationumber	The cash equivalent of the points defined in the points_ratio property.
points_ratiointeger	The number of loyalty points that will map to the predefined cash amount defined by the exchange_ratio property.
transfersarray	Array of Loyalties Transfer Points

Error Object

Attributes	Description
codeinteger	Error’s HTTP status code.
keystring	Short string describing the kind of error which occurred.
messagestring	A human-readable message providing a short description of the error.
detailsstring	A human-readable message providing more details about the error.
request_idstring	This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team.Example:v-0a885062c80375740f
resource_idstring	Unique resource ID that can be used in another endpoint to get more details.Example:rf_0c5d710a87c8a31f86
resource_typestring	The resource type.Example:voucher
errorobject	Includes additional information about the error.Attributes Descriptionmessagestring The message configured by the user in a validation rule.

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

Category

Attributes	Description
idstring	Unique category ID assigned by Voucherify.
namestring	Category name.
hierarchyinteger	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
objectstring	The type of the object represented by the JSON. This object stores information about the category.Available values: category
created_atstring	Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.Example:2022-07-14T10:45:13.156Z
updated_atstring	Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.Example:2022-08-16T10:52:08.094Z

Business Validation Rule Assignment

Attributes	Description
idstring	The unique identifier for a assignment
rule_idstring	The unique identifier for a rule
related_object_idstring	The unique identifier for a related object
related_object_typestring	The type of related object
created_atstring	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.Example:2022-03-09T11:19:04.819Z
updated_atstring	Timestamp representing the date and time when the object was last updated in ISO 8601 format.Example:2022-03-09T11:19:04.819Z
objectstring	The type of the object represented by JSON.Available values: validation_rules_assignment
validation_statusstring	The validation status of the assignmentAvailable values: VALID, PARTIALLY_VALID, INVALID
validation_omitted_rulesarray	The list of omitted rules

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.

Loyalties Transfer Points

Attributes	Description
codestring	Unique loyalty card code from which the user wants to transfer loyalty points (source).
pointsinteger	The number of loyalty points that the user wants to transfer to another loyalty card. The number of points cannot be higher than the current balance on the loyalty card (source).
reasonstring	Reason for the transfer.
source_idstring	The merchant’s transaction ID if it is different from the Voucherify transaction ID. It is really useful in case of an integration between multiple systems. It can be a transaction ID from a CRM system, database or 3rd-party service.

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