Validation rules

Validations rules enable you to run promo campaigns valid only for some predefined buying scenarios. There are over a dozen attributes you can tap into. The mechanics and details of all of them are described in the Help Center. In this tutorial, we will will guide you through defining and managing validation rules from the API point of view.

📘
Dashboard mode
If you are interested in knowing how you can configure validation rules with the dashboard go straight to this tutorial.

Creating validation rules

First of all, a validation rules entity is always assigned either to a campaign or a standalone voucher, so make sure you have created one. In our case, it's 50% off standalone voucher code with unlimited number of uses:

{
  "code": "6QfHomd2",
  "campaign": null,
  "category": null,
  "type": "DISCOUNT_VOUCHER",
  "discount": {
    "type": "PERCENT",
    "percent_off": 50
  },
  "gift": null,
  "start_date": null,
  "expiration_date": null,
  "publish": {
    "object": "list",
    "count": 0,
    "data_ref": "entries",
    "entries": [],
    "total": 0,
    "url": "/v1/vouchers/6QfHomd2/publications?page=1&limit=10"
  },
  "redemption": {
    "object": "list",
    "quantity": null,
    "redeemed_quantity": 0,
    "data_ref": "redemption_entries",
    "redemption_entries": [],
    "total": 0,
    "url": "/v1/vouchers/6QfHomd2/redemptions?page=1&limit=10"
  },
  "active": true,
  "additional_info": null,
  "metadata": null,
  "is_referral_code": false,
  "updated_at": null,
  "object": "voucher"
}

Now, let's add our first validation rule. We're going to limit the redemption only if the total order amount is greater than 100:

curl -X POST \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
-d '{
    "voucher_code" : "6QfHomd2",
    "orders": {
        "total_amount": {
            "$more_than":[10000]
        }
      }
}' "https://api.voucherify.io/v1/validation-rules"

A validation rule object is created:

{  
  "id":"val_1gFVT6YrLkJm",
  "created_at":"2017-05-19T09:59:30Z",
  "updated_at":null,
  "voucher_code":"6QfHomd2",
  "junction":"AND",
  "orders":{  
    "junction":null,
    "total_amount":{  
      "$more_than":[  
        10000
      ]
    }
  },
  "object":"validation_rules"
}

A voucher or a campaign can have only 1 validation rule entry assigned. However, you can update the rules later on:

curl -X PUT \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
-d '{
    "orders": {
        "total_amount": {
            "$more_than":[5000]
        }
    }
}' "https://api.voucherify.io/v1/validation-rules/val_1gFVT6YrLkJm"

Finally, you can detach the validation rule from the voucher:

curl -X DELETE \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
"https://api.voucherify.io/v1/validation-rules/val_1gFVT6YrLkJm"

Validation rules and redemption

Having validation rules assigned to a voucher or campaign, we can test redemptions. This is how to pass the order details in a request:

curl -X POST \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
-d '{
    "order": {
      "amount": 3000
    }
}' "https://api.voucherify.io/v1/vouchers/6QfHomd2/redemption"

Now if we put an amount less than 100, the redemption will fail:

{  
  "code":400,
  "message":"order does not match validation rules",
  "details":"6QfHomd2",
  "key":"order_rules_violated"
}

Combined validation rules

Validation rules are flexible; you can mix different limits taking into account customer segments, product items, order size, or the amount. Most probably, your marketing team will be creating them using the creator, but here is a reference for how to do it programmatically:

{  
  "segments":{  
    "junction":"AND",
    "conditions":{  
      "$is":[  
        "seg_n3vVcU5t0m3rs4rEPr3C1oU5",
        "seg_Rvsjn5PygnamKjRbwVP6Kmqf"
      ],
      "$is_not":[  
        "seg_v5wv7NTTepm1b24kuiJLO9Wj"
      ]
    }
  },
  "products":{  
    "junction":"AND",
    "conditions":{  
      "$is":[  
        {  
          "id":"prod_ewGxJMm746Zvij",
          "source_id":null
        }
      ],
      "$is_not":[  
        {  
          "id":"prod_anJ03RZZq74z4v",
          "source_id":null
        }
      ]
    }
  },
  "skus":{  
    "junction":"AND",
    "conditions":{  
      "$is":[  
        {  
          "id":"sku_dSbRQfbyUMyHnt",
          "source_id":null
        }
      ]
    }
  },
  "order":{  
    "junction":"OR",
    "total_amount":{  
      "$more_than":[  
        100000
      ]
    },
    "products_count":{  
      "$more_than":[  
        5
      ]
    }
  }
}

The JSON above is the counterpart of:

Discount per product

As you might've noticed, some validation rules are based on the structure of products in the cart. Sometimes you want to make a discount applicable only to particular items (products and skus). This can be achieved with discount_applicable property. Once your marketing team defines applicable only to rule by following this guide, the validation rule entity will look like this:

{
  "object":{
    "code":"p5XX27rG",
    "object":"voucher"
  },
  "related_object":{
    "id":"val_R6Eg20JrO11h",
    "object":"validation_rules",
    "junction":"AND",
    "products":{
      "junction":"AND",
      "conditions":{
        "$is":[
          {
            "id":"prod_iGEzVplfJVolP3",
            "source_id":null,
            "discount_applicable":false
          },
          {
            "id":"prod_RGFbFNXFxoGbJr",
            "source_id":null,
            "discount_applicable":true
          }
        ]
      }
    },
    "created_at":1499780307979,
    "updated_at":null,
    "voucher_code":"p5XX27rG"
  },
  "previous_attributes":{

  }
}

Now let's see how to implement a corresponding redemption request, let's assume we want to apply a 10% off discount to two product items:

{  
  "order":{  
    "items":[  
      {  
        "product_id":"prod_iGEzVplfJVolP3",
        "quantity":"1",
        "amount":12000
      },
      {  
        "product_id":"prod_RGFbFNXFxoGbJr",
        "quantity":"1",
        "amount":22000
      }
    ]
  }
}

The redemption response will store items section which has new, discounted amounts per product:

...

"items":[  
  {  
    "source_id":null,
    "object":"order_item",
    "product_id":"prod_iGEzVplfJVolP3",
    "sku_id":null,
    "quantity":1,
    "amount":12000,
    "discount_amount":1200
  },
  {  
    "source_id":null,
    "object":"order_item",
    "product_id":"prod_RGFbFNXFxoGbJr",
    "sku_id":null,
    "quantity":1,
    "amount":22000,
    "discount_amount":2200
  }
]
...

Reference

For more details visit the endpoint reference.

Parameter	Options	Description
`junction`	`OR` `AND`	Decide whether all or any conditions have to be met
`total_amount`, `products_count`	`$more_than` `$less_than` `$exactly` `$in_range`	Note: to handle decimals all amounts are multiplied by 100 before they get persisted.
`conditions`	`$is` `$is_not`	Decide if a customer, a product or a SKU belongs to one or more characteristics

📘
Postman
You can play around with this endpoint with our Postman examples- catalog TC6 - Campaign with Validation Rules

Validation rules

📘
Dashboard mode

Validation rules and redemption

Combined validation rules

Discount per product

Reference

📘
Postman

📘Dashboard mode

Validation rules and redemption

Combined validation rules

Discount per product

Reference

📘Postman

📘
Dashboard mode

📘
Postman