Qualification Object

👍

Scenario Guide

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

Qualifications Check Eligibility Response Body

AttributesDescription
redeemablesSee: 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
All of: 1. Order Calculated No Customer Data
2.
AttributesDescription
items
array

Array of items applied to the order. It can include up to 500 items.

stacking_rulesSee: Stacking Rules

Redeemables

AttributesDescription
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

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.

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED
amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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_amount
integer

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

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. It can be used to define business validation rules or discount formulas.

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

customerCustomer Id
referrerReferrer Id
redemptions
object
AttributesDescription
[propertyName]See: Order Redemptions

Stacking Rules

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

  1. Single redeemable
  2. AttributesDescription
    redeemables
    array
    Array of Single redeemable

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

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.

Single redeemable

AttributesDescription
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

resultSee: Redeemable Result
orderAll of: 1. Order Calculated No Customer Data
2.
AttributesDescription
items
array

Array of items applied to the order. It can include up to 500 items.

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_assignmentsSee: Validation Rules Assignments List

Redeemable Result

AttributesDescription
discountSee: Discount
giftSee: Redeemable Gift
loyalty_card

Loyalty Card object response

Redeemable Loyalty Card
error

Error in result

Error Object

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

Category with Stacking Rules Type

Category object with stacking_rules_type

All of:

  1. Category
  2. AttributesDescription
    stacking_rules_type
    string

    The type of the stacking rule eligibility.

    Available values: JOINT, EXCLUSIVE

Validation Rules Assignments List

AttributesDescription
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

AttributesDescription
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

AttributesDescription
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

AttributesDescription
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

error
object

Includes additional information about the error.

AttributesDescription
message
string

The message configured by the user in a validation rule.

Applicable To

AttributesDescription
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

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_units
array

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:
AttributesDescription
index
integer

Number assigned to the order line item in accordance with the order sent in the request.

units
array

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.

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. UNIT means particular units within an order line.

Available values: ITEM, UNIT

Inapplicable To

Applicable To

Category

AttributesDescription
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

AttributesDescription
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

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

Formula used to calculate the number of units.

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.

Loyalties Transfer Points

AttributesDescription
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

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

Formula used to calculate the number of units.

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