Give item(s) for free - unit discount

How to add free items to customers’ orders?

Suggest Edits

Voucherify enables you to offer products or shipping for free with a unit discount type. While creating a unique codes campaign, you can choose a unit discount type where the unit represents an item(s) that you want to offer for free.

As a result, when a customer is eligible for a promotion and redeems a code, the item(s) defined by the unit type will be automatically discounted.

Unit discount overview

To set up a unit discount via the dashboard, you need to provide the following information:

Unit value defines the number of free items attached to the code. Unit type is a product offered for free chosen from your Product Inventory.

Please note that this type of discount is based on the Product inventory added to the Products section in your dashboard. If you haven’t synced your products yet, please follow this guide first.

Discount effect tells Voucherify if it should add items to the cart in quantity equal to the unit value.

There are three discount effects available with unit discount:

• Add new order items – results in adding items to the cart in number defined by unit value. For example, if the code gives one free t-shirt, then no matter if a customer has the t-shirt already in the cart or not, a free t-shirt will always be added to the order and discounted.

• Add missing order items to match total discount units count – the second option adds items to the cart only if a customer has fewer free items than offered to the code. For example, let’s assume that the code gives one free t-shirt:

  – If a customer doesn’t have the t-shirt already in the cart, then a free t-shirt will be added to the order. – If a customer already has this item in their cart, then the number of t-shirts already matches the units count. As a result, after applying the code, a discount will be applied to the item which is already in the cart and no items will be added.

• Add multiple item types - the third option gives multiple types of free item(s) to customers. Free item units are always added to the customer’s cart based on either the Add missing items or Add new order items effects.

Let’s see how it works using the following example:

We’re going to create three unique code campaigns. In each of the examples, each coupon gives a free t-shirt to a customer but the chosen discount effect applied while redeeming the code is different.

Create a unique codes campaign with unit discount

Firstly, we need to create campaigns of unique codes, each code will have the value of one t-shirt.

There are many attributes and details you can customize while creating a campaign (start and expiration date, validation rules, and many more). If you’re not familiar with all the options, please visit this guide first.

You can create this campaign in the dashboard (recommended) or use the Create Campaign method to do it via API.

Below, you can see three campaigns with the same unit discount and different discount effects.

• Create Campaign with discount effect “Add new order items”

POST Create campaign

{
    "name": "Get free T-shirt v1",
    "start_date": "2020-08-16T00:00:00Z",
  	"expiration_date": "2021-12-26T00:00:00Z",
  	"vouchers_count": 1,
    "voucher": {
        "type": "DISCOUNT_VOUCHER",
        "discount": {
            "type": "UNIT",
            "unit_off": 1.0,
            "unit_type": "prod_xoOl0M0AGbmkLp",
            "effect": "ADD_NEW_ITEMS"
        },
         "redemption": {
          "quantity": 1
       }
    },
      "type": "AUTO_UPDATE"

}

• Create Campaign with discount effect “Add missing order items” to match total discount units count

Create campaign

{
    "name": "Get free T-shirt v2",
    "start_date": "2020-08-16T00:00:00Z",
  	"expiration_date": "2021-12-26T00:00:00Z",
  	"vouchers_count": 1,
    "voucher": {
        "type": "DISCOUNT_VOUCHER",
        "discount": {
            "type": "UNIT",
            "unit_off": 1.0,
            "unit_type": "prod_xoOl0M0AGbmkLp",
            "effect": "ADD_MISSING_ITEMS"
        },
         "redemption": {
          "quantity": 1
       }
    },
      "type": "AUTO_UPDATE"

}

• Create Campaign with discount effect “Add multiple order items” with different discount effects for each item type.

POST Create campaign

{
    "name": "Get free T-shirt v3",
    "start_date": "2020-08-16T00:00:00Z",
    "expiration_date": "2022-12-26T00:00:00Z",
    "vouchers_count": 1,
    "voucher": {
        "type": "DISCOUNT_VOUCHER",
        "discount": {
            "type": "UNIT",
            "effect": "ADD_MANY_ITEMS",
            "units": [
                {
                    "unit_off": 1,
                    "unit_type": "prod_0a9f9ab4ab019a42d5",
                    "effect": "ADD_MISSING_ITEMS"
                },
                {
                    "unit_off": 1,
                    "unit_type": "prod_0a9f9aeddb019a42db",
                    "effect": "ADD_NEW_ITEMS"
                }
            ]
        }
    },
    "type": "AUTO_UPDATE"
}

Publish voucher to a customer

Let’s publish one of the unique codes from each of the campaigns to a customer.

Publish voucher

{
    "campaign": { 
      "name": "Get free T-shirt v1", 
      "count": 1 
    },
    "customer": {
      "source_id": "[email protected]",
      "email": "[email protected]",
      "name": "John Smith"
    }
}

Validate and redeem unit discount codes

Now, let’s create an exemplary order to test different discount effects. Before redemption, you should invoke validate method for published vouchers to check if a customer and their cart match the promotion criteria.

POST Validate voucher

{
    "customer" : {
      "id" : "cust_Jj3aDTzKJygmdxe20huwpDkn",
      "source_id" : "[email protected]",
      "name": "John Smith"
    },
    "order" : {
      "amount" : 2900,
      "items": [
        { "product_id": "prod_xoOl0M0AGbmkLp", "quantity": "1", "price": 2900 }
      ]
    }
  }

In the order object, you can see that the customer already has a t-shirt in their cart (it’s the same product that our codes offer for free).

Order object

    "order" : {
      "amount" : 2900,
      "items": [
        { "product_id": "prod_xoOl0M0AGbmkLp", "quantity": "1", "price": 2900 }
      ]
    }

Let’s Redeem Vouchers from all of the campaigns and test the different discount effects.

Redemption of the code with discount effect ADD_NEW_ITEMS

In the response body, you can see that despite that one t-shirt is already in the cart, one additional t-shirt was added to the customer order and discounted.

Example order

{
    "customer" : {
      "id" : "cust_Jj3aDTzKJygmdxe20huwpDkn",
      "source_id" : "[email protected]",
      "name": "John Smith"
    },
    "order" : {
      "amount" : 2900,
      "items": [
        { "product_id": "prod_xoOl0M0AGbmkLp", "quantity": "1", "price": 2900 }
      ]
    }
  }

In the order items object, you can see that a free item was added to the cart.

Redemption of the code with discount effect ADD_MISSING_ITEMS

Now, let’s use the same order while redeeming a discount code with the same value and a different discount effect.

POST Redeem voucher

{
    "customer" : {
      "id" : "cust_Jj3aDTzKJygmdxe20huwpDkn",
      "source_id" : "[email protected]",
      "name": "John Smith"
    },
    "order" : {
      "amount" : 2900,
      "items": [
        { "product_id": "prod_xoOl0M0AGbmkLp", "quantity": "1", "price": 2900 }
      ]
    }
}

As you can see in the response body, the discount was applied to the product already added to the cart by a customer. The number of items in the cart matched the number of free units from the code so there were no additional items added by Voucherify.

Redemption of the code with discount effect ADD_MANY_ITEMS

Finally, let’s redeem a discount code for multiple free item types.

POST Redeem voucher

{
    "customer": {
        "id": "cust_gN9KgORZECfdhG9qT6n82Zr7",
        "source_id": "[email protected]",
        "name": "John Smith"
    },
    "order": {
        "amount": 6000,
        "items": [
            {
                "product_id": "prod_0a9f9ab4ab019a42d5",
                "quantity": "1",
                "price": 2900
            },
            {
                "product_id": "prod_0a9f9aeddb019a42db",
                "quantity": "1",
                "price": 3100
            }
        ]
    }
}

As you can see in the response body, the discount was applied to the products in the cart. Each item type was added according the discount effect defined for that particular item type.

---

• Table of Contents

• • Unit discount overview
  • Create a unique codes campaign with unit discount
  • Publish voucher to a customer
    • Validate and redeem unit discount codes
  • Redemption of the code with discount effect ADD_NEW_ITEMS
  • Redemption of the code with discount effect ADD_MISSING_ITEMS
  • Redemption of the code with discount effect ADD_MANY_ITEMS