Qualification Object

👍
Scenario Guide
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_id `string`	This identifier is generated during voucher qualification based on your internal id (e.g., email, database ID). This is a hashed customer source ID.
order `object`	Order Calculated No Customer Data
stacking_rules	See: Stacking Rules

Redeemables

Attributes	Description
object `string`	The type of the object represented by JSON. Default is `list`. Available values: `list`
data_ref `string`	Identifies the name of the attribute that contains the array of qualified redeemables. Available values: `data`
data `array`	Array of qualified redeemables. Array of Combined response of redeemable object and multiple redeemables within
total `integer`	The number of redeemables returned in the API request. Example: 5
has_more `boolean`	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_after `string`	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

id
string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

source_id
string, null

Unique source ID of an existing order that will be linked to the redemption of this request.

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

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. It can include up 500 items.

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.

object
string

The type of the object represented by JSON.

Available values: order

created_at
string

Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.

Example:

2021-12-22T10:13:06.487Z

updated_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example:

2021-12-22T10:14:45.316Z

customer_id
string, null

Unique customer ID of the customer making the purchase.

Example:

cust_7iUa6ICKyU6gH40dBU25kQU1

referrer_id
string, null

Unique referrer ID.

Example:

cust_nM4jqPiaXUvQdVSA6vTRUnix

customer Customer Id

referrer Referrer Id

redemptions
object

Attributes	Description
[propertyName]	See: Order Redemptions

Stacking Rules

Attributes	Description
redeemables_limit `integer`	Defines how many redeemables can be sent in one stacking request (note: more redeemables means more processing time!).
applicable_redeemables_limit `integer`	Defines how many of the sent redeemables will be applied to the order. For example, a user can select 30 discounts but only 5 will be applied to the order and the remaining will be labelled as SKIPPED.
applicable_redeemables_per_category_limit `integer`	Defines how many redeemables per category can be applied in one request.
applicable_exclusive_redeemables_limit `integer`	Defines how many redeemables with an exclusive category can be applied in one request.
applicable_exclusive_redeemables_per_category_limit `integer`	Defines how many redeemables with an exclusive category per category in stacking rules can be applied in one request.
exclusive_categories `array`	Lists all 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_categories `array`	Lists all joint categories. A campaign with a joint category is always applied regardless of the exclusivity of other campaigns.
redeemables_application_mode `string`	Defines redeemables application mode. Available values: `ALL`, `PARTIAL`
redeemables_sorting_rule `string`	Defines redeemables sorting rule. Available values: `CATEGORY_HIERARCHY`, `REQUESTED_ORDER`
redeemables_products_application_mode `string`	Defines redeemables products application mode. Available values: `STACK`, `ONCE`
redeemables_no_effect_rule `string`	Defines redeemables no effect rule. Available values: `REDEEM_ANYWAY`, `SKIP`

Combined response of redeemable object and multiple redeemables within

All of:

Single redeemable
Attributes Description
redeemables
array Array of Single redeemable

Attributes	Description
redeemables `array`	Array of Single redeemable

Order Item Calculated

Attributes Description

id
string

Unique identifier of the order line item.

sku_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

product_id
string

Unique identifier of the product. It is assigned by Voucherify.

related_object
string

Used along with the source_id property, can be set to either sku or product.

Available values: product, sku

source_id
string

The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service.

quantity
integer

The quantity of the particular item in the cart.

discount_quantity
integer

Number of dicounted items.

initial_quantity
integer

A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.

amount
integer

The total amount of the order item (price * quantity).

discount_amount
integer

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

applied_discount_amount
integer

This field shows the order-level discount applied.

applied_discount_quantity
integer

Number of the discounted items applied in the transaction.

applied_quantity
integer

Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

applied_quantity_amount
integer

Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

initial_amount
integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

price
integer

Unit price of an item. 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.

Attributes	Description
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.

Attributes	Description
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.

Customer Id

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

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback_id `string`	Unique ID of the redemption rollback. Example: rr_0c63c84eb78ee0a6c0
rollback_date `string`	Timestamp representing the date and 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.

Single redeemable

Attributes	Description
id `string`	Id of the redeemable.
object `string`	Object type of the redeemable. Available values: `campaign`, `promotion_tier`, `promotion_stack`, `voucher`
created_at `string`	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	See: Order Calculated No Customer Data
validation_rule_id `string`	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
metadata `object`	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.
categories `array`	List of category information. Array of Category with Stacking Rules Type
banner `string`	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
name `string`	Name of the redeemable. Example: promotion_tier_get_points
campaign_name `string`	Name of the campaign associated to the redeemable. This field is available only if object is not `campaign` Example: PromotionCampaign
campaign_id `string`	Id of the campaign associated to the redeemable. This field is available only if object is not `campaign` Example: camp_Mow7u4gSxagLlZ2oDQ01ZS5N
validation_rules_assignments	See: Validation Rules Assignments List

Redeemable Result

Attributes	Description
discount	See: Discount
gift	See: Redeemable Gift
loyalty_card	Loyalty Card object response Redeemable Loyalty Card
error	Error in result Error Object

Applicable To Result List

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

Inapplicable To Result List

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

Category with Stacking Rules Type

Category object with stacking_rules_type

All of:

Category
Attributes Description
stacking_rules_type
string
The type of the stacking rule eligibility.
Available values: JOINT, EXCLUSIVE

Attributes	Description
stacking_rules_type `string`	The type of the stacking rule eligibility. Available values: `JOINT`, `EXCLUSIVE`

Validation Rules Assignments List

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

Discount

Contains information about discount.

One of:

Amount, Unit, Unit Multiple, Percent, Fixed

Redeemable Gift

Attributes	Description
balance `number`	Available funds. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000.
credits `number`	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. Value is multiplied by 100 to precisely represent 2 decimal places. For example `10000 cents` for `$100.00`.

Redeemable Loyalty Card

Attributes	Description
points `integer`	Total points incurred over the lifespan of the loyalty card. Example: 7000
balance `integer`	Points available for reward redemption. Example: 6970
exchange_ratio `number`	The cash equivalent of the points defined in the points_ratio property.
points_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the exchange_ratio property.
transfers `array`	Array of Loyalties Transfer Points

Error Object

Attributes	Description
code `integer`	Error's HTTP status code.
key `string`	Short string describing the kind of error which occurred.
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
request_id `string`	This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team. Example: v-0a885062c80375740f
resource_id `string`	Unique resource ID that can be used in another endpoint to get more details. Example: rf_0c5d710a87c8a31f86
resource_type `string`	The resource type. Example: voucher

Applicable To

Attributes	Description
object `string`	This object stores information about the resource to which the discount is applicable. Available values: `product`, `sku`, `products_collection`
id `string`	Unique product collection, product, or SKU identifier assigned by Voucherify.
source_id `string`	The source identifier from your inventory system.
product_id `string`	Parent product's unique ID assigned by Voucherify.
product_source_id `string`	Parent product's source ID from your inventory system.
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`	Determines the order in which the discount is applied to the products or SKUs sent in the `order` object in the request. The counting begins from `0`.
repeat `integer`	Determines the recurrence of the discount, e.g. `"repeat": 3` means that the discount is applied to every third item.
skip_initially `integer`	Determines how many items are skipped before the discount is applied.
target `string`	Determines to which kinds of objects the discount is applicable. `"ITEM"` includes products and SKUs. Available values: `ITEM`

Inapplicable To

Applicable To

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created_at `string`	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_at `string`	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
id `string`	The unique identifier for a assignment
rule_id `string`	The unique identifier for a rule
related_object_id `string`	The unique identifier for a related object
related_object_type `string`	The type of related object
created_at `string`	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_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation_rules_assignment`
validation_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY_VALID`, `INVALID`
validation_omitted_rules `array`	The list of omitted rules

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount_off `number`	Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.
amount_off_formula `string`
aggregated_amount_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

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

Unit Multiple

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

Percent

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

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed_amount `number`	Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the fallback value. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value.
fixed_amount_formula `string`
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.

Loyalties Transfer Points

Attributes	Description
code `string`	Unique loyalty card code from which the user wants to transfer loyalty points (source).
points `integer`	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).
reason `string`	Reason for the transfer.
source_id `string`	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
id `string`	Unique product ID, assigned by Voucherify.
source_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

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

One Unit

Attributes	Description
unit_off `number`	Number of units to be granted a full value discount.
unit_off_formula `string`
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

👍Scenario Guide

Qualifications Check Eligibility Response Body

Redeemables

Order Calculated No Customer Data

Stacking Rules

Combined response of redeemable object and multiple redeemables within

Order Item Calculated

Customer Id

Referrer Id

Order Redemptions

Single redeemable

Redeemable Result

Applicable To Result List

Inapplicable To Result List

Category with Stacking Rules Type

Validation Rules Assignments List

Discount

Redeemable Gift

Redeemable Loyalty Card

Error Object

Applicable To

Inapplicable To

Category

Business Validation Rule Assignment

Amount

Unit

Unit Multiple

Percent

Fixed

Loyalties Transfer Points

Applicable To Effect

Discount Amount Vouchers Effect Types

Discount Unit Vouchers Effect Types

Simple Product Discount Unit

Simple Sku Discount Unit

One Unit

Discount Percent Vouchers Effect Types

Discount Fixed Vouchers Effect Types

👍
Scenario Guide