Redemptions Redeem Response Body
Attributes | Description |
---|---|
redemptionsarray | Array of Simple Redemption |
parent_redemption | See: Simple Redemption |
order | Contains the order details associated with the redemption. Order Calculated |
inapplicable_redeemablesarray | Lists validation results of each inapplicable redeemable. Array of Inapplicable Redeemable |
skipped_redeemablesarray | Lists validation results of each redeemable. If a redeemable can be applied, the API returns |
Simple Redemption
Attributes | Description |
---|---|
idstring | Unique redemption ID. Example:r_0bc92f81a6801f9bca |
customer_idstring , null | Unique customer ID of the redeeming customer. Example:cust_i8t5Tt6eiKG5K79KQlJ0Vs64 |
tracking_idstring | Hashed customer source ID. |
datestring | Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example:2021-12-22T10:13:06.487Z |
amountinteger | For gift cards, this is a positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the number of redeemed credits. 10000 |
order | See: Simple Order |
reward | See: Simple Redemption Reward Result |
customer | See: Simple Customer |
resultstring | Redemption result. Available values:SUCCESS , FAILURE |
statusstring , null | Available values: SUCCEEDED , FAILED , ROLLED BACK |
voucher | Defines the details of the voucher being redeemed. Simple Voucher |
promotion_tier | See: Simple Promotion Tier |
redemptionstring | Unique redemption ID of the parent redemption. Example:r_0c656311b5878a2031 |
objectstring | The type of the object represented by the JSON. This object stores information about the |
Order Calculated
All of:
- Order Response Base
-
Order Calculated
Attributes Description customer One of: Customer Id referrer One of: Referrer Id
Inapplicable Redeemable
Attributes | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
statusstring | Indicates whether the redeemable can be applied or not applied based on the validation rules. Available values:INAPPLICABLE | ||||||||||||
idstring | Redeemable ID, i.e. the voucher code. | ||||||||||||
objectstring | Redeemable's object type. Available values:voucher , promotion_tier | ||||||||||||
resultobject | Includes the error object with details about the reason why the redeemable is inapplicable
| ||||||||||||
metadataobject | The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable. | ||||||||||||
categoriesarray | Array of Category |
Skipped Redeemable
Attributes | Description |
---|---|
statusstring | Indicates whether the redeemable can be applied or not applied based on the validation rules. Available values:SKIPPED |
idstring | Redeemable ID, i.e. the voucher code. |
objectstring | Redeemable's object type. Available values:voucher , promotion_tier |
resultobject | Provides details about the reason why the redeemable is skipped. |
metadataobject | The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable. |
categoriesarray | Array of Category |
Simple Order
Attributes | Description |
---|---|
idstring | Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request. |
source_idstring | 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 |
customer_idstring , null | Unique customer ID of the customer making the purchase. Example:cust_7iUa6ICKyU6gH40dBU25kQU1 |
referrer_idstring , null | Unique referrer ID. Example:cust_nM4jqPiaXUvQdVSA6vTRUnix |
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. |
applied_discount_amountinteger | This field shows the order-level discount applied. |
items_discount_amountinteger | Sum of all product-specific discounts applied to the order. |
items_applied_discount_amountinteger | Sum of all product-specific discounts applied in a particular request. |
total_discount_amountinteger | Sum of all order-level AND all product-specific discounts applied to the order. |
total_applied_discount_amountinteger | Sum of all order-level AND all product-specific discounts applied in a particular request. |
total_amountinteger | Order amount after undoing all the discounts through the rollback redemption. |
itemsarray | Array of items applied to the order. Array of Simple Order Item |
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. |
objectstring | The type of the object represented by JSON. Available values:order |
Simple Redemption Reward Result
Attributes | Description |
---|---|
customer | See: Simple Customer |
assignment_idstring | Unique reward assignment ID assigned by Voucherify. |
voucher | Defines of the voucher. Simple Voucher |
product | Defines of the product. Simple Product |
sku | Defines of the sku. Simple Sku |
loyalty_tier_idstring | Unique loyalty tier ID assigned by Voucherify. |
idstring | Unique reward ID, assigned by Voucherify. Example:rew_nIy4gHpQHle2c3pNMwuj7G6j |
objectstring | The type of the object represented by the JSON. This object stores information about the reward. Available values:reward |
namestring | Reward name. |
created_atstring | Timestamp representing the date and time when the reward was created. The value is shown in the ISO 8601 format. Example:2022-08-11T14:49:22.586Z |
updated_atstring , null | Timestamp representing the date and time when the reward was updated. The value is shown in the ISO 8601 format. Example:2022-08-11T16:01:34.885Z |
parametersobject | Defines how the reward is generated. |
typestring | Reward type. Available values:CAMPAIGN , COIN , MATERIAL |
Simple Customer
Attributes | Description |
---|---|
idstring | The ID of an existing customer that will be linked to redemption in this request. |
source_idstring | 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. |
namestring | Customer's first and last name. |
emailstring | Customer's email 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. |
objectstring | The type of the object represented by JSON. Available values:customer |
Simple Voucher
Attributes | Description | ||||||
---|---|---|---|---|---|---|---|
idstring | A unique identifier that represents the voucher assigned by Voucherify. | ||||||
codestring | Voucher code. | ||||||
gift | Gift object response. Gift | ||||||
discount | See: Discount | ||||||
loyalty_cardobject | Defines the loyalty card details. Simple Loyalty Card | ||||||
typestring | Type of the voucher. Available values:DISCOUNT_VOUCHER , LOYALTY_CARD , GIFT_VOUCHER | ||||||
campaignstring | Campaign name. | ||||||
campaign_idstring | Campaign unique ID. | ||||||
is_referral_codeboolean | Flag indicating whether this voucher is a referral code; | ||||||
holder_idstring | Unique customer ID of the campaign owner. Example:cust_eWgXlBBiY6THFRJwX45Iakv4 | ||||||
referrer_idstring | Unique identifier of the referrer assigned by Voucherify. Example:cust_nM4jqPiaXUvQdVSA6vTRUnix | ||||||
category_idstring , null | Unique identifier of the category that this voucher belongs to. Example:cat_0b6152ce12414820dc | ||||||
categoriesarray | Contains details about the category. Array of Category | ||||||
activeboolean | Shows whether the voucher is on or off. | ||||||
created_atstring | Timestamp representing the date and time when the order was created. Timestamp is presented in the ISO 8601 format. Example:2021-12-22T10:13:06.487Z | ||||||
updated_atstring | Timestamp representing the date and time when the voucher was updated in the ISO 8601 format. Example:2024-01-01T11:11:11.111Z | ||||||
redemptionobject | Defines the redemption limits on vouchers.
| ||||||
start_datestring | Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is inactive before this date. Example:2021-12-01T00:00:00.000Z | ||||||
expiration_datestring | Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is inactive after this date. Example:2021-12-31T00:00:00.000Z | ||||||
metadataobject | A set of custom key/value pairs that you can attach to a voucher. The metadata object stores all custom attributes assigned to the voucher. | ||||||
objectstring | The type of the object represented by JSON. Available values:voucher |
Simple Promotion Tier
Attributes | Description | ||||
---|---|---|---|---|---|
idstring | Unique promotion tier ID. Example:promo_63fYCt81Aw0h7lzyRkrGZh9p | ||||
namestring | Name of the promotion tier. | ||||
bannerstring | Text to be displayed to your customers on your website. | ||||
campaignobject | Contains details about promotion tier's parent campaign.
| ||||
metadataobject | A set of custom key/value pairs that you can attach to a promotion tier. The metadata object stores all custom attributes assigned to the promotion tier. |
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 | ||||
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 the object represented by JSON. Available values:order | ||||
redemptionsobject |
|
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
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 about 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 |
Category
Attributes | Description |
---|---|
idstring | Unique category ID assigned by Voucherify. |
namestring | Category name. |
hierarchyinteger | Category hierarchy. |
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 |
stacking_rules_typestring | The type of the stacking rule eligibility. Available values:JOINT , EXCLUSIVE |
Validations Redeemable Skipped Result Limit Exceeded
Attributes | Description |
---|---|
keystring | Available values: applicable_redeemables_limit_exceeded |
messagestring | Example: Applicable redeemables limit exceeded |
Validations Redeemable Skipped Result Category Limit Exceeded
Attributes | Description |
---|---|
keystring | Available values: applicable_redeemables_per_category_limit_exceeded |
messagestring | Example: Applicable redeemables limit per category exceeded |
Validations Redeemable Skipped Result Redeemables Limit Exceeded
Attributes | Description |
---|---|
keystring | Available values: applicable_exclusive_redeemables_limit_exceeded |
messagestring | Example: Applicable exclusive redeemables limit exceeded |
Validations Redeemable Skipped Result Redeemables Category Limit Exceeded
Attributes | Description |
---|---|
keystring | Available values: applicable_exclusive_redeemables_per_category_limit_exceeded |
messagestring | Example: Applicable exclusive redeemables limit per category exceeded |
Validations Redeemable Skipped Result Exclusion Rules Not Met
Attributes | Description |
---|---|
keystring | Available values: exclusion_rules_not_met |
messagestring | Example: Redeemable cannot be applied due to exclusion rules |
Validations Redeemable Skipped Result Preceding Validation Failed
Attributes | Description |
---|---|
keystring | Available values: preceding_validation_failed |
messagestring | Example: Redeemable cannot be applied due to preceding validation failure |
Simple Order Item
Attributes | Description |
---|---|
idstring | Unique identifier of the order line item. |
objectstring | The type of the object represented by JSON. This object stores information about the order_item |
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. |
related_objectstring | Used along with the product , sku |
product_idstring | Unique identifier of the product. It is assigned by Voucherify. |
sku_idstring | Unique identifier of the SKU. It is assigned by Voucherify. |
quantityinteger | Quantity of the particular item in the cart. |
applied_quantityinteger | 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_amountinteger | 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. |
discount_quantityinteger | Number of discounted items. |
applied_discount_quantityinteger | Number of the discounted items applied in the transaction. |
amountinteger | Total amount of the order item (price * quantity). |
discount_amountinteger | Sum of all order-item-level discounts applied to the order. |
applied_discount_amountinteger | Order-level discount amount applied in the transaction. |
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 |
Simple Product
Attributes | Description |
---|---|
idstring | Unique product ID. |
source_idstring | Product source id. |
namestring | Product name. |
Simple Sku
Attributes | Description |
---|---|
idstring | Unique sku ID. |
source_idstring | Sku source id. |
skustring | Sku name. |
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 |
Discount
Contains information about discount.
One of:
Amount, Unit, Unit Multiple, Percent, Fixed
Simple Loyalty Card
Attributes | Description |
---|---|
pointsinteger | Total points incurred over lifespan of loyalty card. |
balanceinteger | Points available for reward redemption. |
next_expiration_datestring | The next closest date when the next set of points are due to expire. |
next_expiration_pointsinteger | The amount of points that are set to expire next. |
Order Item
Attributes | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectstring | The type of the object represented by JSON. This object stores information about the order_item | ||||||||||||||
sku_idstring | Unique identifier of the SKU. It is assigned by Voucherify. | ||||||||||||||
product_idstring | Unique identifier of the product. It is 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. | ||||||||||||||
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. | ||||||||||||||
applied_discount_amountinteger | Order-level discount amount applied in the transaction. | ||||||||||||||
applied_discount_quantityinteger | Number of the discounted items applied in the transaction. | ||||||||||||||
applied_quantityinteger | 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_amountinteger | 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. | ||||||||||||||
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.
| ||||||||||||||
metadataobject | A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item 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. |
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. |
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