Endpoints
curl --request POST \
--url https://{cluster}.voucherify.io/v1/promotions/validation \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-App-Id: <api-key>' \
--header 'X-App-Token: <api-key>' \
--data '
{
"customer": {
"id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
},
"order": {
"id": "<string>"
},
"metadata": {},
"options": {
"expand": [
"category"
]
}
}
'{
"valid": true,
"tracking_id": "<string>",
"promotions": [
{
"valid": "<string>",
"applicable_to": {
"data": [
{
"object": "products_collection",
"id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"effect": "APPLY_TO_EVERY"
}
],
"total": 123,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [
{
"object": "products_collection",
"id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"effect": "APPLY_TO_EVERY"
}
],
"total": 123,
"data_ref": "data",
"object": "list"
},
"tracking_id": "<string>",
"order": {
"id": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"source_id": "<string>",
"created_at": "2022-10-06T11:40:48.705Z",
"updated_at": "2022-10-06T11:47:20.760Z",
"status": "CREATED",
"amount": 123,
"discount_amount": 123,
"total_discount_amount": 123,
"total_amount": 123,
"applied_discount_amount": 123,
"total_applied_discount_amount": 123,
"items": [
{
"object": "order_item",
"product_id": "prod_5h0wc453_1",
"sku_id": "sku_prod_5h0wc453_1_1",
"quantity": 123,
"amount": 123,
"price": 123,
"subtotal_amount": 123,
"product": {
"id": "prod_5h0wc453_1",
"source_id": "illy-arabica",
"name": "Brewing System",
"price": 123
},
"sku": {
"id": "sku_prod_5h0wc453_1_1",
"source_id": "illy-arabica-250g",
"sku": "<string>",
"price": 123
}
}
],
"metadata": {},
"customer": {
"id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"object": "customer"
},
"referrer": {
"id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"object": "customer"
},
"customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"object": "order"
},
"id": "promo_4TqHr24boFISDrcOHSlfAxwm",
"name": "<string>",
"banner": "Get 45% off items",
"discount": {
"type": "AMOUNT",
"effect": "APPLY_TO_ORDER",
"amount_off": 123
},
"start_date": "2022-11-02T00:00:00.000Z",
"expiration_date": "2022-11-04T00:00:00.000Z",
"campaign": {
"id": "camp_h8RyP6FV94F3Ev2odP24j5p1",
"start_date": "2022-11-01T00:00:00.000Z",
"expiration_date": "2022-11-30T00:00:00.000Z",
"active": true,
"categories": {
"id": "<string>",
"name": "<string>",
"hierarchy": 1,
"object": "category",
"created_at": "2022-07-14T10:45:13.156Z",
"updated_at": "2022-08-16T10:52:08.094Z"
},
"object": "campaign"
},
"hierarchy": 123,
"discount_amount": 123,
"applied_discount_amount": 123,
"metadata": {},
"object": "promotion_tier",
"category_id": "cat_0c9da30e7116ba6bba",
"categories": {
"id": "<string>",
"name": "<string>",
"hierarchy": 1,
"object": "category",
"created_at": "2022-07-14T10:45:13.156Z",
"updated_at": "2022-08-16T10:52:08.094Z"
}
}
]
}Validate Promotions
❗️ Deprecated
This endpoint represents the deprecated version of the API responsible for qualification, and we do not recommend using it. The new Qualifications API introduces additional features and improvements while maintaining backward compatibility. Developers are encouraged to migrate to the latest version to take advantage of the latest enhancements and bug fixes. No updates will be provided to the deprecated endpoint.
❗️ Limitation
Only the first 150 most recent promotion tiers are checked for eligibility. Older promotion tiers are ignored and not returned.
Use this method to get valid promotions for a given customer and order.
Advanced validation filters
You can narrow down a validation to a specific promotion ID or tier metadata.
curl --request POST \
--url https://{cluster}.voucherify.io/v1/promotions/validation \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-App-Id: <api-key>' \
--header 'X-App-Token: <api-key>' \
--data '
{
"customer": {
"id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
},
"order": {
"id": "<string>"
},
"metadata": {},
"options": {
"expand": [
"category"
]
}
}
'{
"valid": true,
"tracking_id": "<string>",
"promotions": [
{
"valid": "<string>",
"applicable_to": {
"data": [
{
"object": "products_collection",
"id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"effect": "APPLY_TO_EVERY"
}
],
"total": 123,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [
{
"object": "products_collection",
"id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"effect": "APPLY_TO_EVERY"
}
],
"total": 123,
"data_ref": "data",
"object": "list"
},
"tracking_id": "<string>",
"order": {
"id": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"source_id": "<string>",
"created_at": "2022-10-06T11:40:48.705Z",
"updated_at": "2022-10-06T11:47:20.760Z",
"status": "CREATED",
"amount": 123,
"discount_amount": 123,
"total_discount_amount": 123,
"total_amount": 123,
"applied_discount_amount": 123,
"total_applied_discount_amount": 123,
"items": [
{
"object": "order_item",
"product_id": "prod_5h0wc453_1",
"sku_id": "sku_prod_5h0wc453_1_1",
"quantity": 123,
"amount": 123,
"price": 123,
"subtotal_amount": 123,
"product": {
"id": "prod_5h0wc453_1",
"source_id": "illy-arabica",
"name": "Brewing System",
"price": 123
},
"sku": {
"id": "sku_prod_5h0wc453_1_1",
"source_id": "illy-arabica-250g",
"sku": "<string>",
"price": 123
}
}
],
"metadata": {},
"customer": {
"id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"object": "customer"
},
"referrer": {
"id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"object": "customer"
},
"customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"object": "order"
},
"id": "promo_4TqHr24boFISDrcOHSlfAxwm",
"name": "<string>",
"banner": "Get 45% off items",
"discount": {
"type": "AMOUNT",
"effect": "APPLY_TO_ORDER",
"amount_off": 123
},
"start_date": "2022-11-02T00:00:00.000Z",
"expiration_date": "2022-11-04T00:00:00.000Z",
"campaign": {
"id": "camp_h8RyP6FV94F3Ev2odP24j5p1",
"start_date": "2022-11-01T00:00:00.000Z",
"expiration_date": "2022-11-30T00:00:00.000Z",
"active": true,
"categories": {
"id": "<string>",
"name": "<string>",
"hierarchy": 1,
"object": "category",
"created_at": "2022-07-14T10:45:13.156Z",
"updated_at": "2022-08-16T10:52:08.094Z"
},
"object": "campaign"
},
"hierarchy": 123,
"discount_amount": 123,
"applied_discount_amount": 123,
"metadata": {},
"object": "promotion_tier",
"category_id": "cat_0c9da30e7116ba6bba",
"categories": {
"id": "<string>",
"name": "<string>",
"hierarchy": 1,
"object": "category",
"created_at": "2022-07-14T10:45:13.156Z",
"updated_at": "2022-08-16T10:52:08.094Z"
}
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Query Parameters
If you add a query param AudienceRulesOnly=true, the request will be validated against customer-related rules only, the rest of attached limits and rules will be ignored.
Filter conditions. Promotion filter conditions.
Show child attributes
Show child attributes
Allows you to create a filter based on the conditions set for promotion metadata values. The metadata object stores all custom attributes assigned to the promotion tier. A set of key/value pairs that are attached to a promotion tier object. Stores additional information about the promotion tier in a structured format.
Allows you to create a filter based on the unique promotion ID.
Body
Provide the customer and order context.
Request schema model for validating a promotion using POST v1/promotions/validation.
A set of key/value pairs that you can send in the request body to check against vouchers requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.
Configure parameters returned in the response.
Show child attributes
Show child attributes
The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. Add category as a string in the array to include a categories object in the response.
category Response
Returns a list of valid promotions for a given context (customer and order). You can then choose which promotion to apply, i.e. the highest discount amount.
Response schema model for validating a promotion using POST v1/promotions/validation.
Indicates whether the promotion is valid within the context of the parameters provided in the request body and filters in the query parameters.
Hashed customer source ID.
Contains an array of promotion tier objects.
Show child attributes
Show child attributes
Indicates whether the promotion is valid within the context of the parameters provided in the request body and filters in the query parameters.
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.
Show child attributes
Show child attributes
Contains array of items to which the discount can apply.
Contains definition for a product collection.
- Product Collection
- Product Collection for Unit Discount
- Product Collection for Fixed Amount Discount
- Product
- Product for Unit Discount
- Product for Fixed Amount Discount
- SKU
- SKU for Unit Discount
- SKU for Amount Discount
Show child attributes
Show child attributes
This object stores information about the product collection.
Unique product collection ID assigned by Voucherify.
"pc_4ndRXAsTOzwSdHcQcxf489uU"
Defines how the discount is applied to the customer's order.
APPLY_TO_EVERY, APPLY_TO_CHEAPEST, APPLY_TO_MOST_EXPENSIVE Total number of objects defining included products, SKUs, or product collections.
Identifies the name of the attribute that contains the array of included objects.
The type of the object represented by JSON. This object stores information about included products, SKUs, or product collections in a dictionary.
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.
Show child attributes
Show child attributes
Contains array of items to which the discount cannot apply.
Contains definition for a product collection.
- Product Collection
- Product
- SKU
Show child attributes
Show child attributes
This object stores information about the product collection.
Unique product collection ID assigned by Voucherify.
"pc_4ndRXAsTOzwSdHcQcxf489uU"
Defines how the discount is applied to the customer's order.
APPLY_TO_EVERY Total number of objects defining excluded products, SKUs, or product collections.
Identifies the name of the attribute that contains the array of excluded objects.
The type of the object represented by JSON. This object stores information about excluded products, SKUs, or product collections in a dictionary.
Hashed customer source ID.
This is an object representing an order with calculated discounts applied using the voucher code.
- Order object - Effect: Apply to order
- Order object - Effect: Apply to items
Show child attributes
Show child attributes
Unique order ID, assigned by Voucherify. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the order.id parameter in the request body.
"ord_OLWs41pBk7VFn6ZTyX9U6keh"
The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the order.id parameter in the request body.
Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the order.id parameter in the request body.
"2022-10-06T11:40:48.705Z"
Timestamp representing the date and time when the order was updated. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the order.id parameter in the request body.
"2022-10-06T11:47:20.760Z"
Order status. This parameter is returned if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the order.id parameter in the request body or if you send the request body parameter when defining an order in the request body. This parameter can be passed but it's not required for validation at all. It's used in the redemption process. Normally after the redemption is done, the order is automatically to a PAID status. To avoid such default behaviour, the user can pass any of the other status options and it will be set the order status after the redemption instead of the default PAID.
CREATED, PAID, CANCELED, FULFILLED Order amount before applying any discount.
Sum of all order-level discounts applied to the order.
Sum of all order-level discounts.
Order amount after applying all the discounts.
total_amount = amount - total_discount_amount
This field shows the order-level discount applied.
This field sums up all order-level discounts applied to the order.
Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.
Show child attributes
Show child attributes
The type of the object represented by JSON. This object stores information about the order_item.
A unique identifier that represents the product and is assigned by Voucherify.
"prod_5h0wc453_1"
A unique identifier that represents the SKU and is assigned by Voucherify.
"sku_prod_5h0wc453_1_1"
Quantity of the item in the cart.
Represents a total pre-discount amount of order item (price * quantity).
Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
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-discount_amount
This object stores more information about the related product.
Show child attributes
Show child attributes
A unique identifier that represents the product and is assigned by Voucherify.
"prod_5h0wc453_1"
A unique product identifier from your inventory system.
"illy-arabica"
Product name.
"Brewing System"
Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
This object stores more information about the related SKU.
Show child attributes
Show child attributes
A unique identifier that represents the SKU and is assigned by Voucherify.
"sku_prod_5h0wc453_1_1"
A unique SKU identifier from your inventory system.
"illy-arabica-250g"
SKU name.
Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format.
Object containing information about the customer that is making the purchase.
Object containing information about the referrer.
Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.
"cust_7iUa6ICKyU6gH40dBU25kQU1"
Unique referrer ID.
"cust_nM4jqPiaXUvQdVSA6vTRUnix"
The type of the object represented by JSON. This object stores information about the order.
Unique promotion tier ID.
"promo_4TqHr24boFISDrcOHSlfAxwm"
Custom promotion tier name.
Text to be displayed to your customers on your website.
"Get 45% off items"
Contains information about the discount to be applied to the order.
- Amount Discount
- Percent Discount
- Fixed Discount
- Unit Discount, Product
- Unit Discount, SKU
- Unit Discount, multiple items
- Shipping Discount
Show child attributes
Show child attributes
Defines the type of the voucher.
Defines how the discount is applied to the customer's order.
APPLY_TO_ORDER, APPLY_TO_ITEMS, APPLY_TO_ITEMS_PROPORTIONALLY, APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY, APPLY_TO_ITEMS_BY_QUANTITY 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.
Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Campaign is inactive before this date.
"2022-11-02T00:00:00.000Z"
Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.
"2022-11-04T00:00:00.000Z"
Show child attributes
Show child attributes
Unique promotion tier ID.
"camp_h8RyP6FV94F3Ev2odP24j5p1"
Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.
"2022-11-01T00:00:00.000Z"
Activation timestamp defines when the campaign expires in ISO 8601 format. Promotion tier is inactive after this date.
"2022-11-30T00:00:00.000Z"
A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the start_date and expiration_date.
trueindicates an active campaignfalseindicates an inactive campaign
This is an object representing a category.
Show child attributes
Show child attributes
Unique category ID assigned by Voucherify.
Category name.
Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
x >= 0The type of the object represented by the JSON. This object stores information about the category.
category Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.
"2022-07-14T10:45:13.156Z"
Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.
"2022-08-16T10:52:08.094Z"
The type of the object represented by the campaign object. This object stores information about the campaign.
The promotions hierarchy defines the order in which the discounts from different tiers will be applied to a customer's order. If a customer qualifies for discounts from more than one tier, discounts will be applied in the order defined in the hierarchy.
The calculated discount amount based on the discount type and effect.
The effective discount amount that would be applied to the order.
The metadata object stores all custom attributes assigned to the promotion tier. A set of key/value pairs that you can attach to a promotion tier object. It can be useful for storing additional information about the promotion tier in a structured format.
The type of the object represented by JSON. This object stores information about the promotion tier.
Promotion tier category ID.
"cat_0c9da30e7116ba6bba"
Details about the category assigned to the promotion tier.
Show child attributes
Show child attributes
Unique category ID assigned by Voucherify.
Category name.
Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
x >= 0The type of the object represented by the JSON. This object stores information about the category.
category Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.
"2022-07-14T10:45:13.156Z"
Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.
"2022-08-16T10:52:08.094Z"
Was this page helpful?