The Voucherify Developer Hub

Welcome to the Voucherify developer hub. You'll find comprehensive guides and documentation to help you start working with Voucherify as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Validation rules

Validations rules enable you to run promo campaigns valid only for predefined buying scenarios. Voucherify offers a great number of attributes you can tap into. The mechanics and details of all of them are described in the Help Center. In this tutorial, we will guide you through defining and managing validation rules with the API.

πŸ“˜

Object definition

Validation rule object reference

Creating validation rules

A validation rule object can be attached (and detached) to a campaign or a standalone voucher/promotion tier at any time. Assuming you have any of these objects created, let's see how you can add some business restrictions. In the following example, we're going to allow for 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 '{
        "name": "Order Amount more than 100$",
      "rules": {
        "1": {
            "name": "order.amount",
            "conditions": {
                "$more_than": [10000]
            }
        },
        "logic": "1"
      }
    }' "https://api.voucherify.io/v1/validation-rules"

As a result, the validation rule object is created and returned.

{
  "id": "val_269dXe4PYfqO",
  "name": "Order Amount more than 100$",
  "rules": {
    "1": {
      "name": "order.amount",
      "conditions": {
        "$more_than": [
          10000
        ]
      },
      "rules": {}
    },
    "logic": "1"
  },
  "createdAt": "2018-12-20T11:28:18Z",
  "updatedAt": null,
  "object": "validation_rules"
}

You can update and detach the validation rule object at any time. In this example, we attach it to a voucher.

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": "6QfHomd2"
}' \
"https://api.voucherify.io/v1/validation-rules/val_269dXe4PYfqO/assignments"

As a result, the Validation Rules Assignment object is created and returned.

{
  "id": "asgm_F8ckUWxH03PsZlSG",
  "rule_id": "val_269dXe4PYfqO",
  "related_object_id": "v_xQXXIOeKBUuFj9VbtvHjngQQ2MKupBT2",
  "related_object_type": "voucher",
  "created_at": "2018-12-20T11:31:36Z",
  "updated_at": null,
  "object": "validation_rules_assignment"
}

A voucher or a campaign can have only one 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 '{
          "rules": {
            "1": {
              "name": "order.amount",
              "conditions": {
                "$more_than": [5000] 
              }
            },
            "logic": "1"
          }
        }' "https://api.voucherify.io/v1/validation-rules/val_269dXe4PYfqO"

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_269dXe4PYfqO/assignments/asgm_F8ckUWxH03PsZlSG"

Validation rules with metadata

Payload format you should use to include metadata (custom fields) when creating a validation rule.

{
    "name": "A test rule",
    "rules": {
        "1": {
            "name": "redemption.metadata.",
            "property": "organizer",
            "conditions": { "$is": [ 4203 ] }
        },
        "logic": "1 and 2",
        "2": {
            "name": "redemption.metadata",
            "property": "serviceID",
            "conditions": { "$is": [ 46638 ] }
        }
    }
}

Checking redemption against validation rules

Voucherify automatically decides if a transaction matches the your business criteria. All you need to do is to pass all necessary objects (customer, products, order) within the redemption 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"

If it satisfies all validation rules, you'll get 200 and the redemption object will be set to SUCCESS. Otherwise, the API will return 400 and the redemption record will be marked as FAILED with a corresponding reason.

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

Joining 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 dashboard, but here is a reference for how to do it programmatically:

{
  "name": "Complex Validation Rule",
  "rules": {
    "1": {
      "name": "customer.segment",
      "conditions": {
        "$is": [ "seg_n3vVcU5t0m3rs4rEPr3C1oU5" ]
      }
    },
    "2": {
      "name": "product.id",
      "conditions": {
        "$is": [{ "id": "prod_ewGxJMm746Zvij", "source_id": "" }] 
      },
      "rules": {
        "1": {
          "name": "product.price",
          "conditions": {
            "$more_than_or_equal": [ 5000 ] 
          }
        },
        "logic": "1"
      }
    },
    "3": {
          "name": "order.amount",
      "conditions": {
        "$more_than": [10000] 
      }
    },
    "logic": "1 and 2 and 3"
  }
}

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:

{
  "name": "Discount Applicable To Product",
  "rules": {
    "1": {
      "name": "product.id",
      "conditions": {
        "$is": [{ "id": "prod_ewGxJMm746Zvij", "source_id": "" }] 
      },
      "rules": {
        "1": {
          "name": "product.discount_applicable",
          "conditions": {
            "$is": [ true ] 
          }
        },
        "logic": "1"
      }
    },
    "logic": "1"
  }
}

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

{  
  "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
  }
]
...

For more details visit the endpoint reference.

πŸ“˜

Postman

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

Product-specific rules without importing your catalog

You don't have to import your inventory to use product-specific rules in your campaigns. That means that there is no need of storing the products catalog in Voucherify upfront and up-to-date.

The Voucherify engine enables you to assign custom attributes as metadata to products/SKUs from the order in the moment of invoking a redemption.

πŸ“˜

Note

The same mechanism works for both Products and SKUs. Therefore, an application needs a clear definition of the order item type at the moment of invoking a request.

How does it work?

  1. Firstly, define custom attributes for your products (using UI or API request) which then, can be used while creating validation rules. In the Schema, you don't attach these attributes to specific products, you just define their names, types, and values (optional). The detailed guide describing how to add custom product attributes with Metadata Schema is here.

  2. When you have product metadata defined, you can create a promo campaign with validation rules based on product metadata. As a result, all the products in the order will be validated accordingly to the rules with product metadata. You can see how to add validation rules with product metadata in this section.

  3. While the campaign is fired off, your customers can start redeeming codes. When creating a redemption request via API, you can add products with metadata from scratch. When a redemption request gets to Voucherify, metadata assigned to ordered products will be compared to the validation rules with product metadata assigned to the code.

While invoking the redemption, you can add a product/products to the redemption request details. These products aren't in Voucherify inventory, they are created from scratch.

{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 70000,
    "items": [
      {"quantity": 1, "source_id": "FOR-1", "related_object": "product", "price": 30000, "amount": 60000, "product": { "metadata": { "Category": "Electronics" } } }
    ]
  }
}

In the next step, Voucherify will verify if validation rules attached to this code (Product metadata satisfy: Category is Electronics) are met by a customer and his/her order. In this case, Voucherify compares product metadata attached to the code (in a validation rules object) with product metadata attached to products in a customer's order. You can see some code samples in the next paragraph.

Exexmplary API requests.

  • Coupon Validation

Request Body:

{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 70000,
    "items": [
      {"quantity": 1, "source_id": "GEN-1", "related_object": "product", "price": 10000, "amount": 10000 },
      {"quantity": 2, "source_id": "FOR-1", "related_object": "product", "price": 30000, "amount": 60000, "product": { "metadata": { "formulary": true } } }
    ]
  },
  "metadata": {
    "test": true,
    "pickup_date": "2018-11-01T23:00:01.000Z"
  }
}

or:

{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 70000,
    "items": [
      {"quantity": 1, "product_id": "GEN-1", "price": 10000, "amount": 10000 },
      {"quantity": 2, "product_id": "FOR-1", "price": 30000, "amount": 60000, "product": { "metadata": { "formulary": true } } }
    ]
  },
  "metadata": {
    "test": true,
    "pickup_date": "2018-11-01T23:00:01.000Z"
  }
}
  • Coupon Redemption

Request Body:

{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 70000,
    "items": [
      {"quantity": 1, "source_id": "GEN-1", "related_object": "product", "price": 10000, "amount": 10000 },
      {"quantity": 2, "source_id": "FOR-1", "related_object": "product", "price": 30000, "amount": 60000, "product": { "metadata": { "formulary": true } } }
    ]
  },
  "metadata": {
    "test": true,
    "pickup_date": "2018-11-01T23:00:01.000Z"
  }
}

or:

{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 70000,
    "items": [
      {"quantity": 1, "product_id": "GEN-1", "price": 10000, "amount": 10000 },
      {"quantity": 2, "product_id": "FOR-1", "price": 30000, "amount": 60000, "product": { "metadata": { "formulary": true } } }
    ]
  },
  "metadata": {
    "test": true,
    "pickup_date": "2018-11-01T23:00:01.000Z"
  }
}
  • Optional parameter – override. By default it is set to false, so products and SKUs will not be updated in the Voucherify products catalog. For example:
{
  "customer": {
    "source_id": "[email protected]"
  },
  "order": {
    "amount": 10000,
    "items": [
      {"quantity": 1, "product_id": "iphone_8_silver_256gb-1", "price": 10000, "amount": 10000, "product":{"override":true, "metadata":{"lang":"eu"} }}
    ]
  },
  "metadata": {
    "sales_channel": "page_1"   
  }
}

Updated about a month ago

Validation rules


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.