curl --request POST \
  --url https://{cluster}.voucherify.io/v1/promotions/tiers/{tierId}/validation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "test-user@email.io"
  },
  "order": {
    "id": "ord_71uW6qnB5CFZlLHCeCNC4qtS"
  }
}
'

{
  "valid": true,
  "applicable_to": {
    "data": [],
    "total": 0,
    "data_ref": "data",
    "object": "list"
  },
  "inapplicable_to": {
    "data": [],
    "total": 0,
    "data_ref": "data",
    "object": "list"
  },
  "tracking_id": "track_OWyBVb1mg1qnieLLNygh19A0Ia7FsJck",
  "order": {
    "id": "ord_71uW6qnB5CFZlLHCeCNC4qtS",
    "source_id": null,
    "created_at": "2022-11-17T12:17:55.096Z",
    "updated_at": null,
    "status": "CREATED",
    "amount": 9918200,
    "initial_amount": 468200,
    "items_discount_amount": 9450000,
    "total_discount_amount": 9450000,
    "total_amount": 468200,
    "items_applied_discount_amount": 9450000,
    "total_applied_discount_amount": 9450000,
    "items": [
      {
        "object": "order_item",
        "source_id": "webinar_BF_sweater_pink_sweater",
        "related_object": "product",
        "quantity": 1,
        "amount": 6500,
        "price": 6500,
        "subtotal_amount": 6500
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_pants_navy_sweat_pants",
        "related_object": "product",
        "quantity": 1,
        "amount": 6000,
        "price": 6000,
        "subtotal_amount": 6000
      },
      {
        "object": "order_item",
        "source_id": "5h1pp1ng",
        "related_object": "product",
        "quantity": 1,
        "amount": 2000,
        "price": 2000,
        "subtotal_amount": 2000,
        "product": {
          "id": "prod_5h1pp1ng",
          "source_id": "5h1pp1ng",
          "name": "Shipping"
        }
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_pants_gray_sweat_pants",
        "related_object": "product",
        "quantity": 2,
        "amount": 10000,
        "price": 5000,
        "subtotal_amount": 10000
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_sweater_pearl",
        "related_object": "product",
        "quantity": 2,
        "amount": 22000,
        "price": 11000,
        "subtotal_amount": 22000
      },
      {
        "object": "order_item",
        "product_id": "prod_0b7d7dfb05cbe5c616",
        "sku_id": "sku_0b7d7dfb090be5c619",
        "quantity": 1,
        "amount": 1700,
        "price": 1700,
        "subtotal_amount": 1700,
        "product": {
          "id": "prod_0b7d7dfb05cbe5c616",
          "source_id": "Books",
          "name": "Comic Books1",
          "price": 2100
        },
        "sku": {
          "id": "sku_0b7d7dfb090be5c619",
          "source_id": "ComicBook_1",
          "sku": "Comics1",
          "price": 1700
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0bae32322150fd0546",
        "quantity": 2,
        "amount": 420000,
        "price": 210000,
        "subtotal_amount": 420000,
        "product": {
          "id": "prod_0bae32322150fd0546",
          "name": "Samsung Phone",
          "price": 210000
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0bae2dc5a090fd0184",
        "sku_id": "sku_0bae3b28f610fd0da1",
        "quantity": 45,
        "discount_quantity": 45,
        "initial_quantity": 0,
        "amount": 9450000,
        "discount_amount": 9450000,
        "initial_amount": 0,
        "applied_discount_amount": 9450000,
        "price": 210000,
        "subtotal_amount": 0,
        "product": {
          "id": "prod_0bae2dc5a090fd0184",
          "source_id": "first_product",
          "name": "Samsung Phone 1",
          "price": 220000
        },
        "sku": {
          "id": "sku_0bae3b28f610fd0da1",
          "source_id": "first_product_sku_1",
          "sku": "Samsung phone 256GB",
          "price": 210000
        }
      }
    ],
    "metadata": {},
    "customer_id": null,
    "referrer_id": null,
    "object": "order"
  },
  "id": "promo_ZWkx6R0I1Ts3N9HL4kfTdxOm",
  "name": "Add new SKU",
  "discount": {
    "type": "UNIT",
    "effect": "ADD_NEW_ITEMS",
    "unit_off": 45,
    "unit_type": "sku_0bae3b28f610fd0da1",
    "sku": {
      "id": "sku_0bae3b28f610fd0da1",
      "source_id": "first_product_sku_1",
      "sku": "Samsung phone 256GB"
    },
    "product": {
      "id": "prod_0bae2dc5a090fd0184",
      "source_id": "first_product",
      "name": "Samsung Phone 1"
    }
  },
  "campaign": {
    "id": "camp_40LC42P5NFbkkD4RWoJ4btks",
    "start_date": null,
    "expiration_date": null,
    "active": true,
    "object": "campaign"
  },
  "hierarchy": 4,
  "discount_amount": 9450000,
  "applied_discount_amount": 9450000,
  "metadata": {},
  "object": "promotion_tier"
}

Validate Promotion Tier

❗️ Deprecated

This endpoint represents the deprecated version of the API responsible for promotion tier redemption, and we do not recommend using it. The new Stackable Discounts API introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. 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.

To verify whether the promotion tier discount can be applied to an order. This method is designed for server side integration which means that it is accessible only through private keys.

POST

promotions

tiers

{tierId}

validation

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/promotions/tiers/{tierId}/validation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "test-user@email.io"
  },
  "order": {
    "id": "ord_71uW6qnB5CFZlLHCeCNC4qtS"
  }
}
'

{
  "valid": true,
  "applicable_to": {
    "data": [],
    "total": 0,
    "data_ref": "data",
    "object": "list"
  },
  "inapplicable_to": {
    "data": [],
    "total": 0,
    "data_ref": "data",
    "object": "list"
  },
  "tracking_id": "track_OWyBVb1mg1qnieLLNygh19A0Ia7FsJck",
  "order": {
    "id": "ord_71uW6qnB5CFZlLHCeCNC4qtS",
    "source_id": null,
    "created_at": "2022-11-17T12:17:55.096Z",
    "updated_at": null,
    "status": "CREATED",
    "amount": 9918200,
    "initial_amount": 468200,
    "items_discount_amount": 9450000,
    "total_discount_amount": 9450000,
    "total_amount": 468200,
    "items_applied_discount_amount": 9450000,
    "total_applied_discount_amount": 9450000,
    "items": [
      {
        "object": "order_item",
        "source_id": "webinar_BF_sweater_pink_sweater",
        "related_object": "product",
        "quantity": 1,
        "amount": 6500,
        "price": 6500,
        "subtotal_amount": 6500
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_pants_navy_sweat_pants",
        "related_object": "product",
        "quantity": 1,
        "amount": 6000,
        "price": 6000,
        "subtotal_amount": 6000
      },
      {
        "object": "order_item",
        "source_id": "5h1pp1ng",
        "related_object": "product",
        "quantity": 1,
        "amount": 2000,
        "price": 2000,
        "subtotal_amount": 2000,
        "product": {
          "id": "prod_5h1pp1ng",
          "source_id": "5h1pp1ng",
          "name": "Shipping"
        }
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_pants_gray_sweat_pants",
        "related_object": "product",
        "quantity": 2,
        "amount": 10000,
        "price": 5000,
        "subtotal_amount": 10000
      },
      {
        "object": "order_item",
        "source_id": "webinar_BF_sweater_pearl",
        "related_object": "product",
        "quantity": 2,
        "amount": 22000,
        "price": 11000,
        "subtotal_amount": 22000
      },
      {
        "object": "order_item",
        "product_id": "prod_0b7d7dfb05cbe5c616",
        "sku_id": "sku_0b7d7dfb090be5c619",
        "quantity": 1,
        "amount": 1700,
        "price": 1700,
        "subtotal_amount": 1700,
        "product": {
          "id": "prod_0b7d7dfb05cbe5c616",
          "source_id": "Books",
          "name": "Comic Books1",
          "price": 2100
        },
        "sku": {
          "id": "sku_0b7d7dfb090be5c619",
          "source_id": "ComicBook_1",
          "sku": "Comics1",
          "price": 1700
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0bae32322150fd0546",
        "quantity": 2,
        "amount": 420000,
        "price": 210000,
        "subtotal_amount": 420000,
        "product": {
          "id": "prod_0bae32322150fd0546",
          "name": "Samsung Phone",
          "price": 210000
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0bae2dc5a090fd0184",
        "sku_id": "sku_0bae3b28f610fd0da1",
        "quantity": 45,
        "discount_quantity": 45,
        "initial_quantity": 0,
        "amount": 9450000,
        "discount_amount": 9450000,
        "initial_amount": 0,
        "applied_discount_amount": 9450000,
        "price": 210000,
        "subtotal_amount": 0,
        "product": {
          "id": "prod_0bae2dc5a090fd0184",
          "source_id": "first_product",
          "name": "Samsung Phone 1",
          "price": 220000
        },
        "sku": {
          "id": "sku_0bae3b28f610fd0da1",
          "source_id": "first_product_sku_1",
          "sku": "Samsung phone 256GB",
          "price": 210000
        }
      }
    ],
    "metadata": {},
    "customer_id": null,
    "referrer_id": null,
    "object": "order"
  },
  "id": "promo_ZWkx6R0I1Ts3N9HL4kfTdxOm",
  "name": "Add new SKU",
  "discount": {
    "type": "UNIT",
    "effect": "ADD_NEW_ITEMS",
    "unit_off": 45,
    "unit_type": "sku_0bae3b28f610fd0da1",
    "sku": {
      "id": "sku_0bae3b28f610fd0da1",
      "source_id": "first_product_sku_1",
      "sku": "Samsung phone 256GB"
    },
    "product": {
      "id": "prod_0bae2dc5a090fd0184",
      "source_id": "first_product",
      "name": "Samsung Phone 1"
    }
  },
  "campaign": {
    "id": "camp_40LC42P5NFbkkD4RWoJ4btks",
    "start_date": null,
    "expiration_date": null,
    "active": true,
    "object": "campaign"
  },
  "hierarchy": 4,
  "discount_amount": 9450000,
  "applied_discount_amount": 9450000,
  "metadata": {},
  "object": "promotion_tier"
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

tierId

string

required

Unique promotion tier ID.

Body

application/json

Provide the customer and order context.

Request schema model for validating a promotion using POST v1/promotions/tiers/{tierId}/validation.

customer

Customer ID · object

Customer's information.

Customer ID
Customer Source ID
Customer

Show child attributes

customer.id

string

The ID of an existing customer that will be linked to redemption in this request.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

order

Order ID · object

Order information.

Order ID
Order Source ID
Orders Create Request Body

Show child attributes

order.id

string

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

metadata

object

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.

Response

200 - application/json

Returns validation result in valid key of the promotion tier object. Returns true if the promotion tier rules and validation rules are satisfied given the request body parameters. Returns false if the data provided in the payload does not meet validation rules or promotion tier requirements.

Promotion Tier Valid
Promotion Tier Not Valid

Response schema model for validating a promotion using POST v1/promotions/tiers/{tierId}/validation.

valid

string

Indicates whether the promotion is valid within the context of the parameters provided in the request body and filters in the query parameters.

applicable_to

Included Items · object

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

applicable_to.data

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

applicable_to.data.object

string

default:products_collection

This object stores information about the product collection.

applicable_to.data.id

string

Unique product collection ID assigned by Voucherify.

Example:

"pc_4ndRXAsTOzwSdHcQcxf489uU"

applicable_to.data.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_EVERY,

APPLY_TO_CHEAPEST,

APPLY_TO_MOST_EXPENSIVE

applicable_to.total

integer

Total number of objects defining included products, SKUs, or product collections.

applicable_to.data_ref

string

default:data

Identifies the name of the attribute that contains the array of included objects.

applicable_to.object

string

default:list

The type of the object represented by JSON. This object stores information about included products, SKUs, or product collections in a dictionary.

inapplicable_to

Excluded Items · object

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

inapplicable_to.data

(Product Collection · object | Product · object | SKU · object)[]

Contains array of items to which the discount cannot apply.

Contains definition for a product collection.

Product Collection
Product
SKU

Show child attributes

inapplicable_to.data.object

string

default:products_collection

This object stores information about the product collection.

inapplicable_to.data.id

string

Unique product collection ID assigned by Voucherify.

Example:

"pc_4ndRXAsTOzwSdHcQcxf489uU"

inapplicable_to.data.effect

enum<string>

default:APPLY_TO_EVERY

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_EVERY

inapplicable_to.total

integer

Total number of objects defining excluded products, SKUs, or product collections.

inapplicable_to.data_ref

string

default:data

Identifies the name of the attribute that contains the array of excluded objects.

inapplicable_to.object

string

default:list

The type of the object represented by JSON. This object stores information about excluded products, SKUs, or product collections in a dictionary.

tracking_id

string

Hashed customer source ID.

order

Order object - Effect: Apply to order · object

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

order.id

string

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.

Example:

"ord_OLWs41pBk7VFn6ZTyX9U6keh"

order.source_id

string

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.

order.created_at

string<date-time>

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.

Example:

"2022-10-06T11:40:48.705Z"

order.updated_at

string<date-time>

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.

Example:

"2022-10-06T11:47:20.760Z"

order.status

enum<string>

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.

Available options:

CREATED,

PAID,

CANCELED,

FULFILLED

order.amount

integer

Order amount before applying any discount.

order.discount_amount

integer

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

order.total_discount_amount

integer

Sum of all order-level discounts.

order.total_amount

integer

Order amount after applying all the discounts.
total_amount = amount - total_discount_amount

order.applied_discount_amount

integer

This field shows the order-level discount applied.

order.total_applied_discount_amount

integer

This field sums up all order-level discounts applied to the order.

order.items

object[]

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

order.items.object

string

default:order_item

The type of the object represented by JSON. This object stores information about the order_item.

order.items.product_id

string

A unique identifier that represents the product and is assigned by Voucherify.

Example:

"prod_5h0wc453_1"

order.items.sku_id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_prod_5h0wc453_1_1"

order.items.quantity

integer

Quantity of the item in the cart.

order.items.amount

integer

Represents a total pre-discount amount of order item (price * quantity).

order.items.price

integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.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-discount_amount

order.items.product

object

This object stores more information about the related product.

Show child attributes

order.items.product.id

string

A unique identifier that represents the product and is assigned by Voucherify.

Example:

"prod_5h0wc453_1"

order.items.product.source_id

string

A unique product identifier from your inventory system.

Example:

"illy-arabica"

order.items.product.name

string

Product name.

Example:

"Brewing System"

order.items.product.price

integer

Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.sku

object

This object stores more information about the related SKU.

Show child attributes

order.items.sku.id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_prod_5h0wc453_1_1"

order.items.sku.source_id

string

A unique SKU identifier from your inventory system.

Example:

"illy-arabica-250g"

order.items.sku.sku

string

SKU name.

order.items.sku.price

integer

Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.metadata

object

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.

order.customer

object

Object containing information about the customer that is making the purchase.

Show child attributes

order.customer.id

string

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.customer.object

string

default:customer

Type of object represented by the customer object.

order.referrer

object

Object containing information about the referrer.

Show child attributes

order.referrer.id

string

Unique referrer ID, who referred the customer making the purchase.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.referrer.object

string

default:customer

Type of object represented by the referrer object.

order.customer_id

string

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.referrer_id

string

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

order.object

string

default:order

The type of the object represented by JSON. This object stores information about the order.

string

Unique promotion tier ID.

Example:

"promo_4TqHr24boFISDrcOHSlfAxwm"

name

string

Custom promotion tier name.

banner

string

Text to be displayed to your customers on your website.

Example:

"Get 45% off items"

discount

Amount Discount · object

Contains information about the discount to be applied to the order.

Show child attributes

discount.type

string

default:AMOUNT

Defines the type of the voucher.

discount.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

discount.amount_off

integer

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.

start_date

string<date-time>

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Campaign is inactive before this date.

Example:

"2022-11-02T00:00:00.000Z"

expiration_date

string<date-time>

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example:

"2022-11-04T00:00:00.000Z"

campaign

object

Show child attributes

campaign.id

string

Unique promotion tier ID.

Example:

"camp_h8RyP6FV94F3Ev2odP24j5p1"

campaign.start_date

string<date-time>

Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.

Example:

"2022-11-01T00:00:00.000Z"

campaign.expiration_date

string<date-time>

Activation timestamp defines when the campaign expires in ISO 8601 format. Promotion tier is inactive after this date.

Example:

"2022-11-30T00:00:00.000Z"

campaign.active

boolean

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.

true indicates an active campaign
false indicates an inactive campaign

campaign.categories

Category · object

This is an object representing a category.

Show child attributes

campaign.categories.id

string

required

Unique category ID assigned by Voucherify.

campaign.categories.name

string

required

Category name.

campaign.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

campaign.categories.object

enum<string>

default:category

required

The type of the object represented by the JSON. This object stores information about the category.

Available options:

category

campaign.categories.created_at

string<date-time>

required

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"

campaign.categories.updated_at

string<date-time>

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"

campaign.object

string

default:campaign

The type of the object represented by the campaign object. This object stores information about the campaign.

hierarchy

integer

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.

discount_amount

integer

The calculated discount amount based on the discount type and effect.

applied_discount_amount

integer

The effective discount amount that would be applied to the order.

metadata

object

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.

object

string

default:promotion_tier

The type of the object represented by JSON. This object stores information about the promotion tier.

Last modified on December 11, 2025

Validate Promotions Redemption Object

⌘I

Introduction

Endpoints

Events

Validate Promotion Tier

Authorizations

Path Parameters

Body

Response