Create Validation Rules

Create a validation rule.

🚧 Managing validation rules

It is recommended to create or update validation rules in the Voucherify dashboard. The rule builder in the dashboard helps configuring the desired conditions in a convenient way. The API should not be used as a preferable way to create and manage validation rules.

POST /v1/validation-rules

Create Validation Rules

cURL

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/validation-rules \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "Set of Validation Rules",
  "error": {
    "message": "Your order does not meet at least one of the required criteria."
  },
  "applicable_to": {
    "included_all": false,
    "excluded": [
      {
        "object": "product",
        "id": "prod_0bae45ffc7003ffc52",
        "source_id": "second_product",
        "effect": "APPLY_TO_EVERY"
      }
    ],
    "included": [
      {
        "object": "product",
        "id": "prod_0b72b00ffed198e344",
        "source_id": null,
        "effect": "APPLY_TO_MOST_EXPENSIVE",
        "quantity_limit": 1
      },
      {
        "object": "products_collection",
        "id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
        "source_id": null,
        "effect": "APPLY_TO_EVERY",
        "quantity_limit": 5
      }
    ]
  },
  "rules": {
    "1": {
      "name": "order.metadata",
      "property": "location",
      "rules": {},
      "conditions": {
        "$is": [
          "Santorini"
        ]
      },
      "error": {
        "message": "Your order must be placed at one of our Santorini shops."
      }
    },
    "2": {
      "name": "custom_event.metadata",
      "property": "test",
      "rules": {},
      "conditions": {
        "$greater_than_or_equal": [
          1
        ]
      }
    },
    "3": {
      "name": "order.items.every",
      "rules": {
        "1": {
          "name": "order.items.metadata",
          "property": "test",
          "rules": {},
          "conditions": {
            "$greater_than_or_equal": [
              1
            ]
          }
        }
      },
      "conditions": {
        "$is": [
          {
            "id": "<PROD_ID>",
            "effect": "APPLY_TO_EVERY",
            "object": "product",
            "source_id": "<SOURCE_ID>"
          }
        ]
      }
    },
    "logic": "1 or 2"
  }
}
'

200

{
  "id": "val_eR1c41hu0vUU",
  "name": "Business Validation Rule",
  "rules": {
    "1": {
      "name": "string",
      "property": "string",
      "conditions": {
        "$one_of_voucherify_conditions": [
          "string"
        ]
      },
      "rules": {
        "1": {
          "name": "string",
          "property": "string",
          "conditions": {},
          "rules": {}
        },
        "logic": "string"
      },
      "error": {
        "message": "string"
      }
    },
    "logic": "(1 and 2) and (3)"
  },
  "error": {
    "message": "string"
  },
  "applicable_to": {
    "excluded": [
      {
        "object": "product",
        "id": "string",
        "source_id": "string",
        "effect": "APPLY_TO_EVERY"
      }
    ],
    "included": [
      {
        "object": "product",
        "id": "string",
        "source_id": "string",
        "effect": "APPLY_TO_EVERY",
        "quantity_limit": 0
      }
    ],
    "included_all": true
  },
  "created_at": "2022-03-23T07:44:00.444Z",
  "updated_at": "2022-04-26T08:35:54.960Z",
  "type": "basic",
  "context_type": "earning_rule.order.paid",
  "object": "validation_rules"
}

Authorizations

X-App-Id & X-App-TokenX-Voucherify-OAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Body

application/json

Specify the validation rules parameters.

Request body schema for POST v1/validation-rules.

name · string · required

Custom, unique name for set of validation rules.

Example:

"Business Validation Rule"

rules · Validation Rule Rules · object

Contains all the rule definitions for the validation rule. It is a set of key value pairs representing the rules and logic between the rules. The keys are numbered consecutively beginning from 1. The values are objects containing the rule conditions.

Show child attributes

bundle_rules · Validation Rule Bundle Rules · object

Contains all the definitions for the bundle rules. It is a set of key value pairs representing the rules and logic between them. The keys are numbered consecutively beginning from 1. The values are objects containing the rule conditions.

While updating with the PUT method, you can pass "bundle_rules": null to delete the configuration; in the response, an empty object is then returned.

Show child attributes

error · object

Contains the error message returned from API when validation / redemption fails to meet requirements of defined rules.

Show child attributes

applicable_to · object

Show child attributes

type · enum<string> · default: expression

Type of validation rule.

Available options: expression, basic, advanced, complex

context_type · enum<string> · default: global

Validation rule context type.

Context Type	Definition
earning_rule.order.paid
earning_rule.custom_event
earning_rule.customer.segment.entered
campaign.discount_coupons
campaign.discount_coupons.discount.apply_to_order
campaign.discount_coupons.discount.apply_to_items
campaign.discount_coupons.discount.apply_to_items_proportionally
campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity
campaign.discount_coupons.discount.fixed.apply_to_items
campaign.gift_vouchers
campaign.gift_vouchers.gift.apply_to_order
campaign.gift_vouchers.gift.apply_to_items
campaign.referral_program
campaign.referral_program.discount.apply_to_order
campaign.referral_program.discount.apply_to_items
campaign.referral_program.discount.apply_to_items_proportionally
campaign.referral_program.discount.apply_to_items_proportionally_by_quantity
campaign.referral_program.discount.fixed.apply_to_items
campaign.promotion
campaign.promotion.discount.apply_to_order
campaign.promotion.discount.apply_to_items
campaign.promotion.discount.apply_to_items_proportionally
campaign.promotion.discount.apply_to_items_proportionally_by_quantity
campaign.promotion.discount.fixed.apply_to_items
campaign.loyalty_program
voucher.discount_voucher
voucher.discount_voucher.discount.apply_to_order
voucher.discount_voucher.discount.apply_to_items
voucher.discount_voucher.discount.apply_to_items_proportionally
voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity
voucher.discount_voucher.discount.fixed.apply_to_items
voucher.gift_voucher
voucher.gift_voucher.gift.apply_to_order
voucher.gift_voucher.gift.apply_to_items
voucher.loyalty_card
distribution.custom_event
reward_assignment.pay_with_points
global

Available options: earning_rule.order.paid, earning_rule.custom_event, earning_rule.customer.segment.entered, earning_rule.customer.tier.joined, earning_rule.customer.tier.left, earning_rule.customer.tier.upgraded, earning_rule.customer.tier.downgraded, earning_rule.customer.tier.prolonged, campaign.discount_coupons, campaign.discount_coupons.discount.apply_to_order, campaign.discount_coupons.discount.apply_to_items, campaign.discount_coupons.discount.apply_to_items_proportionally, campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity, campaign.discount_coupons.discount.apply_to_items_by_quantity, campaign.discount_coupons.discount.fixed.apply_to_items, campaign.discount_coupons.discount.percent.apply_to_items, campaign.gift_vouchers, campaign.gift_vouchers.gift.apply_to_order, campaign.gift_vouchers.gift.apply_to_items, campaign.referral_program, campaign.referral_program.discount.apply_to_order, campaign.referral_program.discount.apply_to_items, campaign.referral_program.discount.apply_to_items_proportionally, campaign.referral_program.discount.apply_to_items_proportionally_by_quantity, campaign.referral_program.discount.apply_to_items_by_quantity, campaign.referral_program.discount.fixed.apply_to_items, campaign.referral_program.discount.percent.apply_to_items, campaign.promotion, campaign.promotion.discount.apply_to_order, campaign.promotion.discount.apply_to_items, campaign.promotion.discount.apply_to_items_proportionally, campaign.promotion.discount.apply_to_items_proportionally_by_quantity, campaign.promotion.discount.apply_to_items_by_quantity, campaign.promotion.discount.fixed.apply_to_items, campaign.promotion.discount.percent.apply_to_items, campaign.loyalty_program, voucher.discount_voucher, voucher.discount_voucher.discount.apply_to_order, voucher.discount_voucher.discount.apply_to_items, voucher.discount_voucher.discount.apply_to_items_proportionally, voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity, voucher.discount_voucher.discount.apply_to_items_by_quantity, voucher.discount_voucher.discount.fixed.apply_to_items, voucher.discount_voucher.discount.percent.apply_to_items, voucher.gift_voucher, voucher.gift_voucher.gift.apply_to_order, voucher.gift_voucher.gift.apply_to_items, voucher.loyalty_card, distribution.custom_event, distribution.order.paid, distribution.order.created, distribution.order.canceled, distribution.order.updated, reward_assignment.pay_with_points, global

Response

200

application/json

Returns a validation rule object.

Response body schema for POST v1/validation-rules.

name · string · required

Custom, unique name for set of validation rules.

Example:

"Business Validation Rule"

rules · Validation Rule Rules · object · required

Contains all the rule definitions for the validation rule. It is a set of key value pairs representing the rules and logic between the rules. The keys are numbered consecutively beginning from 1. The values are objects containing the rule conditions.

Show child attributes

applicable_to · object · required

Show child attributes

type · enum<string> · default: expression · required

Type of validation rule.

Available options: expression, basic, advanced, complex

context_type · enum<string> · default: global · required

Validation rule context type.

Context Type	Definition
earning_rule.order.paid
earning_rule.custom_event
earning_rule.customer.segment.entered
campaign.discount_coupons
campaign.discount_coupons.discount.apply_to_order
campaign.discount_coupons.discount.apply_to_items
campaign.discount_coupons.discount.apply_to_items_proportionally
campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity
campaign.discount_coupons.discount.fixed.apply_to_items
campaign.gift_vouchers
campaign.gift_vouchers.gift.apply_to_order
campaign.gift_vouchers.gift.apply_to_items
campaign.referral_program
campaign.referral_program.discount.apply_to_order
campaign.referral_program.discount.apply_to_items
campaign.referral_program.discount.apply_to_items_proportionally
campaign.referral_program.discount.apply_to_items_proportionally_by_quantity
campaign.referral_program.discount.fixed.apply_to_items
campaign.promotion
campaign.promotion.discount.apply_to_order
campaign.promotion.discount.apply_to_items
campaign.promotion.discount.apply_to_items_proportionally
campaign.promotion.discount.apply_to_items_proportionally_by_quantity
campaign.promotion.discount.fixed.apply_to_items
campaign.loyalty_program
voucher.discount_voucher
voucher.discount_voucher.discount.apply_to_order
voucher.discount_voucher.discount.apply_to_items
voucher.discount_voucher.discount.apply_to_items_proportionally
voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity
voucher.discount_voucher.discount.fixed.apply_to_items
voucher.gift_voucher
voucher.gift_voucher.gift.apply_to_order
voucher.gift_voucher.gift.apply_to_items
voucher.loyalty_card
distribution.custom_event
reward_assignment.pay_with_points
global

Available options: earning_rule.order.paid, earning_rule.custom_event, earning_rule.customer.segment.entered, earning_rule.customer.tier.joined, earning_rule.customer.tier.left, earning_rule.customer.tier.upgraded, earning_rule.customer.tier.downgraded, earning_rule.customer.tier.prolonged, campaign.discount_coupons, campaign.discount_coupons.discount.apply_to_order, campaign.discount_coupons.discount.apply_to_items, campaign.discount_coupons.discount.apply_to_items_proportionally, campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity, campaign.discount_coupons.discount.apply_to_items_by_quantity, campaign.discount_coupons.discount.fixed.apply_to_items, campaign.discount_coupons.discount.percent.apply_to_items, campaign.gift_vouchers, campaign.gift_vouchers.gift.apply_to_order, campaign.gift_vouchers.gift.apply_to_items, campaign.referral_program, campaign.referral_program.discount.apply_to_order, campaign.referral_program.discount.apply_to_items, campaign.referral_program.discount.apply_to_items_proportionally, campaign.referral_program.discount.apply_to_items_proportionally_by_quantity, campaign.referral_program.discount.apply_to_items_by_quantity, campaign.referral_program.discount.fixed.apply_to_items, campaign.referral_program.discount.percent.apply_to_items, campaign.promotion, campaign.promotion.discount.apply_to_order, campaign.promotion.discount.apply_to_items, campaign.promotion.discount.apply_to_items_proportionally, campaign.promotion.discount.apply_to_items_proportionally_by_quantity, campaign.promotion.discount.apply_to_items_by_quantity, campaign.promotion.discount.fixed.apply_to_items, campaign.promotion.discount.percent.apply_to_items, campaign.loyalty_program, voucher.discount_voucher, voucher.discount_voucher.discount.apply_to_order, voucher.discount_voucher.discount.apply_to_items, voucher.discount_voucher.discount.apply_to_items_proportionally, voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity, voucher.discount_voucher.discount.apply_to_items_by_quantity, voucher.discount_voucher.discount.fixed.apply_to_items, voucher.discount_voucher.discount.percent.apply_to_items, voucher.gift_voucher, voucher.gift_voucher.gift.apply_to_order, voucher.gift_voucher.gift.apply_to_items, voucher.loyalty_card, distribution.custom_event, distribution.order.paid, distribution.order.created, distribution.order.canceled, distribution.order.updated, reward_assignment.pay_with_points, global

id · string · required

Unique validation rule ID.

Example:

"val_eR1c41hu0vUU"

created_at · string<date-time> · required

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

Example:

"2022-03-23T07:44:00.444Z"

object · string · default: validation_rules · required

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

bundle_rules · Validation Rule Bundle Rules · object

Contains all the definitions for the bundle rules. It is a set of key value pairs representing the rules and logic between them. The keys are numbered consecutively beginning from 1. The values are objects containing the rule conditions.

While updating with the PUT method, you can pass "bundle_rules": null to delete the configuration; in the response, an empty object is then returned.

Show child attributes

error · object

Contains the error message returned from API when validation / redemption fails to meet requirements of defined rules.

Show child attributes

updated_at · string<date-time>

Timestamp representing the date and time when the validation rule was updated. The value is shown in the ISO 8601 format.

Example:

"2022-04-26T08:35:54.960Z"

assignments_count · integer

The number of instances the validation rule has been assigned to different types of redeemables.