Exemplary Workflows

How to model basic promotions using Voucherify API and Campaign Manager

Fixed-code Coupon

1. Create voucher

// POST https://api.voucherify.io/v1/vouchers/sample10off
{
    "category": "New Customers",
    "type": "DISCOUNT_VOUCHER",
    "discount": {
        "percent_off": 10.0,
        "type": "PERCENT",
        "effect": "APPLY_TO_ORDER"
    },
    "start_date": "2021-01-01T00:00:00Z",
    "expiration_date": "2021-12-31T23:59:59Z",
    "redemption": {
        "quantity": 100 
    },
    "metadata": {
      "test": true,
      "locale": "de-en"
    }
}
{
    "id": "v_njn6RSORBuMPKVYaEi882HGaogpcmIzm",
    "code": "sample10off",
    "campaign": null,
    "campaign_id": null,
    "category": "New Customers",
    "type": "DISCOUNT_VOUCHER",
    "discount": {
        "type": "PERCENT",
        "percent_off": 10,
        "effect": "APPLY_TO_ORDER"
    },
    "gift": null,
    "loyalty_card": null,
    "start_date": "2021-01-01T00:00:00.000Z",
    "expiration_date": "2021-12-31T23:59:59.000Z",
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": null,
    "metadata": {
        "test": true,
        "locale": "de-en"
    },
    "assets": {
        "qr": {
            "id": "U2FsdGVkX19CP5Kbzog5YN/AAJhOc/PAEUWiBhcrQdCyG/pgE0CtjZ+4WKKsloaHeV9L56K7vh+Rk4FY7k7/w8ZQdOCCeNbSH/r/m/D02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19CP5Kbzog5YN%2FAAJhOc%2FPAEUWiBhcrQdCyG%2FpgE0CtjZ%2B4WKKsloaHeV9L56K7vh%2BRk4FY7k7%2Fw8ZQdOCCeNbSH%2Fr%2Fm%2FD02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA%3D%3D"
        },
        "barcode": {
            "id": "U2FsdGVkX1+TtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S/vnWP9SS37tM8eM2gA6dXto8JWFj+so+Eg1JAlxuE9Ur+DXqcQqDopmmoLxTTJBHYeFY/0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2BTtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S%2FvnWP9SS37tM8eM2gA6dXto8JWFj%2Bso%2BEg1JAlxuE9Ur%2BDXqcQqDopmmoLxTTJBHYeFY%2F0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A%3D%3D"
        }
    },
    "is_referral_code": false,
    "created_at": "2021-10-07T09:35:34.734Z",
    "updated_at": null,
    "redemption": {
        "quantity": 100,
        "redeemed_quantity": 0,
        "object": "list",
        "url": "/v1/vouchers/sample10off/redemptions?page=1&limit=10"
    },
    "publish": {
        "object": "list",
        "count": 0,
        "url": "/v1/vouchers/sample10off/publications?page=1&limit=10"
    },

In response, the API returns the details of a newly created voucher. (Vouchers which are not part of campaigns are called standalone.)

Read more:

📘

Creating campaigns

It's faster to create campaigns, validation rules, and vouchers using Campaign Manager.

2. Validate Voucher
At any point in time, you can validate a selected voucher to find out if the voucher is eligible for a given customer/order and to get the calculated discount to be shown at the checkout view.

Validation can only be performed via API.

// POST https://api.voucherify.io/v1/vouchers/sample10off/validate
{
    "customer": {
        "source_id": "[email protected]",
        "name": "Nana Lemon",
        "email": "[email protected]"
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"  
    },
    "order": {
        "amount": 200000,
        "items": [
            {
                "source_id": "apple534",
                "product_id": "prod_anJ03RZZq74z4v",
                "related_object": "product",
                "quantity": 2,
                "price": 50000,
                "product": {
                    "override": true,
                    "name": "Apple iPhone 8",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "electronics"
                    }
                },
                "metadata": {
                    "series": "2022-783CV"
                }
            },
            {
                "sku_id": "sku_0KtP4rvwEECQ2U",
                "source_id": "apple534-ihd5",
                "related_object": "sku",
                "quantity": 1,
                "price": 100000,
                "sku": {
                    "override": true,
                    "sku": "Apple iPad 10 Silver 64GB",
                    "metadata": {
                        "category": "electronics"
                    }
                }
            }
        ]
    }
}
{
    "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_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
    "order": {
        "amount": 200000,
        "discount_amount": 20000,
        "total_discount_amount": 20000,
        "total_amount": 180000,
        "applied_discount_amount": 20000,
        "total_applied_discount_amount": 20000,
        "items": [
            {
                "object": "order_item",
                "source_id": "apple534",
                "related_object": "product",
                "product_id": "prod_anJ03RZZq74z4v",
                "quantity": 2,
                "amount": 100000,
                "price": 50000,
                "subtotal_amount": 100000,
                "product": {
                    "id": "prod_09eb7c37e98a86267e",
                    "source_id": "prod_anJ03RZZq74z4v",
                    "name": "Apple iPhone 8",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "electronics"
                    },
                    "override": true
                },
                "metadata": {
                    "series": "2022-783CV"
                }
            },
            {
                "object": "order_item",
                "source_id": "apple534-ihd5",
                "related_object": "sku",
                "sku_id": "sku_0KtP4rvwEECQ2U",
                "quantity": 1,
                "amount": 100000,
                "price": 100000,
                "subtotal_amount": 100000,
                "sku": {
                    "sku": "Apple iPad 10 Silver 64GB",
                    "metadata": {
                        "category": "electronics"
                    },
                    "override": true
                }
            }
        ],
        "customer_id": null,
        "referrer_id": null,
        "object": "order"
    },
    "code": "sample10off",
    "discount": {
        "type": "PERCENT",
        "percent_off": 10,
        "effect": "APPLY_TO_ORDER"
    },
    "start_date": "2021-01-01T00:00:00.000Z",
    "expiration_date": "2021-12-31T23:59:59.000Z",
    "metadata": {
        "test": true,
        "locale": "de-en"
    }
}

3. Redeem Voucher
The voucher can be redeemed as many times as you defined – once, X number of times, or indefinitely. The history of the redemptions is accessible via API and dashboard.

// POST https://api.voucherify.io/v1/vouchers/sample10off/redemption
{
    "customer": {
        "source_id": "[email protected]",
        "name": "Nana Lemon",
        "email": "[email protected]"
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"  
    },
    "order": {
        "amount": 200000,
        "items": [
            {
                "source_id": "apple534",
                "product_id": "prod_anJ03RZZq74z4v",
                "related_object": "product",
                "quantity": 2,
                "price": 50000,
                "product": {
                    "override": true,
                    "name": "Apple iPhone 8",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "electronics"
                    }
                },
                "metadata": {
                    "series": "2022-783CV"
                }
            },
            {
                "sku_id": "sku_0KtP4rvwEECQ2U",
                "source_id": "apple534-ihd5",
                "related_object": "sku",
                "quantity": 1,
                "price": 100000,
                "sku": {
                    "override": true,
                    "sku": "Apple iPad 10 Silver 64GB",
                    "metadata": {
                        "category": "electronics"
                    }
                }
            }
        ]
    }
}
{
    "id": "r_L2GmyC0L7JWlF068fVwOTlhT",
    "object": "redemption",
    "date": "2021-10-07T09:42:30.624Z",
    "customer_id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
    "tracking_id": "track_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
    "order": {
        "id": "ord_GZJOUtYIByUdeFOdUtNZPQdE",
        "source_id": null,
        "created_at": "2021-10-07T09:42:30.437Z",
        "updated_at": null,
        "status": "PAID",
        "amount": 200000,
        "discount_amount": 20000,
        "total_discount_amount": 20000,
        "total_amount": 180000,
        "applied_discount_amount": 20000,
        "total_applied_discount_amount": 20000,
        "items": [
            {
                "object": "order_item",
                "source_id": "apple534",
                "related_object": "product",
                "product_id": "prod_anJ03RZZq74z4v",
                "quantity": 2,
                "amount": 100000,
                "price": 50000,
                "subtotal_amount": 100000,
                "product": {
                    "id": "prod_09eb7c37e98a86267e",
                    "source_id": "prod_anJ03RZZq74z4v",
                    "name": "Apple iPhone 8",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "electronics"
                    }
                },
                "metadata": {
                    "series": "2022-783CV"
                }
            },
            {
                "object": "order_item",
                "source_id": "apple534-ihd5",
                "related_object": "sku",
                "sku_id": "sku_0KtP4rvwEECQ2U",
                "quantity": 1,
                "amount": 100000,
                "price": 100000,
                "subtotal_amount": 100000,
                "sku": {
                    "sku": "Apple iPad 10 Silver 64GB",
                    "metadata": {
                        "category": "electronics"
                    }
                }
            }
        ],
        "customer": {
            "id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
            "object": "customer"
        },
        "customer_id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
        "referrer_id": null,
        "object": "order",
        "redemptions": {
            "r_L2GmyC0L7JWlF068fVwOTlhT": {
                "date": "2021-10-07T09:42:30.624Z",
                "related_object_type": "voucher",
                "related_object_id": "v_njn6RSORBuMPKVYaEi882HGaogpcmIzm"
            }
        }
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"
    },
    "result": "SUCCESS",
    "customer": {
        "id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
        "name": "Nana Lemon",
        "email": "[email protected]",
        "source_id": "[email protected]",
        "object": "customer"
    },
    "related_object_type": "voucher",
    "voucher": {
        "id": "v_njn6RSORBuMPKVYaEi882HGaogpcmIzm",
        "code": "sample10off",
        "campaign": null,
        "campaign_id": null,
        "category": "New Customers",
        "type": "DISCOUNT_VOUCHER",
        "discount": {
            "type": "PERCENT",
            "percent_off": 10,
            "effect": "APPLY_TO_ORDER"
        },
        "gift": null,
        "loyalty_card": null,
        "start_date": "2021-01-01T00:00:00.000Z",
        "expiration_date": "2021-12-31T23:59:59.000Z",
        "validity_timeframe": null,
        "validity_day_of_week": null,
        "active": true,
        "additional_info": null,
        "metadata": {
            "test": true,
            "locale": "de-en"
        },
        "assets": {
            "qr": {
                "id": "U2FsdGVkX19CP5Kbzog5YN/AAJhOc/PAEUWiBhcrQdCyG/pgE0CtjZ+4WKKsloaHeV9L56K7vh+Rk4FY7k7/w8ZQdOCCeNbSH/r/m/D02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19CP5Kbzog5YN%2FAAJhOc%2FPAEUWiBhcrQdCyG%2FpgE0CtjZ%2B4WKKsloaHeV9L56K7vh%2BRk4FY7k7%2Fw8ZQdOCCeNbSH%2Fr%2Fm%2FD02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA%3D%3D"
            },
            "barcode": {
                "id": "U2FsdGVkX1+TtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S/vnWP9SS37tM8eM2gA6dXto8JWFj+so+Eg1JAlxuE9Ur+DXqcQqDopmmoLxTTJBHYeFY/0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2BTtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S%2FvnWP9SS37tM8eM2gA6dXto8JWFj%2Bso%2BEg1JAlxuE9Ur%2BDXqcQqDopmmoLxTTJBHYeFY%2F0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A%3D%3D"
            }
        },
        "is_referral_code": false,
        "created_at": "2021-10-07T09:35:34.734Z",
        "updated_at": "2021-10-07T09:42:30.710Z",
        "validation_rules_assignments": {
            "object": "list",
            "data_ref": "data",
            "data": [],
            "total": 0…
        },
        "redemption": {
            "quantity": 100,
            "redeemed_quantity": 1,
            "object": "list",
            "url": "/v1/vouchers/sample10off/redemptions?page=1&limit=10"
        },
        "publish": {
            "object": "list",
            "count": 0,
            "url": "/v1/vouchers/sample10off/publications?page=1&limit=10"
        },
        "object": "voucher",
        "applicable_to": {
            "data": [],
            "total": 0,
            "data_ref": "data",
            "object": "list"
        },
        "inapplicable_to": {
            "data": [],
            "total": 0,
            "data_ref": "data",
            "object": "list"
        }
    }
}

4. Track Voucher
You can track the performance of the voucher via dashboard activity logs and charts in the dashboard. Call Get Voucher API endpoint to see details of a given voucher.

With Voucherify, you can also easily export voucher details and a list of redemptions to BI and analytics tools of your choice for improved tracking.

Read more in Fraud Prevention and Tracking and Data Export guides.

// GET https://api.voucherify.io/v1/vouchers/sample10off
{
    "id": "v_njn6RSORBuMPKVYaEi882HGaogpcmIzm",
    "code": "sample10off",
    "campaign": null,
    "category": "New Customers",
    "type": "DISCOUNT_VOUCHER",
    "discount": {
        "type": "PERCENT",
        "percent_off": 10.0,
        "effect": "APPLY_TO_ORDER"
    },
    "gift": null,
    "loyalty_card": null,
    "start_date": "2021-01-01T00:00:00Z",
    "expiration_date": "2021-12-31T23:59:59Z",
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "publish": {
        "object": "list",
        "count": 0,
        "data_ref": "entries",
        "entries": [],
        "total": 0,
        "url": "/v1/vouchers/sample10off/publications?page=1&limit=10"
    },
    "redemption": {
        "object": "list",
        "quantity": 100,
        "redeemed_quantity": 1,
        "data_ref": "redemption_entries",
        "redemption_entries": [],
        "total": 1,
        "url": "/v1/vouchers/sample10off/redemptions?page=1&limit=10"
    },
    "active": true,
    "additional_info": null,
    "metadata": {
        "test": true,
        "locale": "de-en"
    },
    "assets": {
        "qr": {
            "id": "U2FsdGVkX19CP5Kbzog5YN/AAJhOc/PAEUWiBhcrQdCyG/pgE0CtjZ+4WKKsloaHeV9L56K7vh+Rk4FY7k7/w8ZQdOCCeNbSH/r/m/D02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19CP5Kbzog5YN%2FAAJhOc%2FPAEUWiBhcrQdCyG%2FpgE0CtjZ%2B4WKKsloaHeV9L56K7vh%2BRk4FY7k7%2Fw8ZQdOCCeNbSH%2Fr%2Fm%2FD02Wo6xWSesp5h4Ke80yierRHwjzES45KrxEWHrPakIqzmsA%3D%3D"
        },
        "barcode": {
            "id": "U2FsdGVkX1+TtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S/vnWP9SS37tM8eM2gA6dXto8JWFj+so+Eg1JAlxuE9Ur+DXqcQqDopmmoLxTTJBHYeFY/0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2BTtEEGsVCq5gBYMBgpl2J3Bpyc9Z4mWzS5LR1S%2FvnWP9SS37tM8eM2gA6dXto8JWFj%2Bso%2BEg1JAlxuE9Ur%2BDXqcQqDopmmoLxTTJBHYeFY%2F0VLQYpVfW9B0uMYkUNZEPb21KUyMFNr6A%3D%3D"
        }
    },
    "is_referral_code": false,
    "updated_at": "2021-10-07T09:42:30Z",
    "created_at": "2021-10-07T09:35:34Z",
    "object": "voucher",
    "validation_rules_assignments": {
        "data": [],
        "object": "list",
        "total": 0,
        "data_ref": "data"
    }
}

5. Disable/Enable Voucher
Each voucher can be disabled and re-enabled on the fly. You can perform these activities with API or via the dashboard.

// POST https://api.voucherify.io/v1/vouchers/10off/disable
// POST https://api.voucherify.io/v1/vouchers/10off/enable

Cart-level Promotion (Auto-applied Discount)

1. Create Promotion
Cart discounts are applied automatically when the order and customer criteria are met (no code necessary).

This endpoint enables you to create cart-promotion via API but it's easier to configure all details and validation rules using the dashboard and the Campaign Manager.

Customizable promotion parameters include promotion type and value, timeframe, banner, and multiple discount tiers with validation rules.

In order to create a promotion, you need to specify at least one promotion tier object.

2. List Promotion Tiers
To display active promotions to customers, you should list all available promotion tiers. You can also list promotion tiers that belong to a specified campaign.

Listing Promotion tiers is only available via API.

// GET https://api.voucherify.io/v1/promotions/camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk/tiers
{
    "object": "list",
    "total": 3,
    "data_ref": "tiers",
    "tiers": [
        {
            "id": "promo_DkBL24GWmNZ1A75bhEiBTNWO",
            "object": "promotion_tier",
            "name": "10% off",
            "banner": "Spend $50 and get 10% off your order",
            "campaign": {
                "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
                "object": "campaign",
                "start_date": "2021-10-01T00:00:00Z",
                "expiration_date": "2021-10-31T00:00:00Z",
                "active": true
            },
            "action": {
                "discount": {
                    "type": "PERCENT",
                    "percent_off": 10.0,
                    "effect": "APPLY_TO_ORDER"
                }
            },
            "metadata": {},
            "summary": {
                "redemptions": {
                    "total_redeemed": 0
                },
                "orders": {
                    "total_amount": 0,
                    "total_discount_amount": 0
                }
            },
            "hierarchy": 3,
            "validation_rule_assignments": {
                "data": [
                    {
                        "id": "asgm_jDLQ7IgpA82GCcRZ",
                        "rule_id": "val_I9xZmL5QgAwq",
                        "related_object_id": "promo_DkBL24GWmNZ1A75bhEiBTNWO",…
                    }
                ],
                "object": "list",
                "total": 1,
                "data_ref": "data"
            },
            "active": true
        },
        {
            "id": "promo_LeDD8tSmLbVsA57LUFLF0IBc",
            "object": "promotion_tier",
            "name": "25% off",
            "banner": "Spend more than $100 and get 25% off!",
            "campaign": {
                "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
                "object": "campaign",
                "start_date": "2021-10-01T00:00:00Z",
                "expiration_date": "2021-10-31T00:00:00Z",
                "active": true
            },
            "action": {
                "discount": {
                    "type": "PERCENT",
                    "percent_off": 25.0,
                    "effect": "APPLY_TO_ORDER"
                }
            },
            "metadata": {},
            "summary": {
                "redemptions": {
                    "total_redeemed": 0
                },
                "orders": {
                    "total_amount": 0,
                    "total_discount_amount": 0
                }
            },
            "hierarchy": 2,
            "validation_rule_assignments": {
                "data": [
                    {
                        "id": "asgm_e8ciR53Gy31Rs74c",
                        "rule_id": "val_cqbLERV7VHtp",
                        "related_object_id": "promo_LeDD8tSmLbVsA57LUFLF0IBc",
                        "related_object_type": "promotion_tier",
                        "created_at": "2021-10-07T11:00:35Z",
                        "updated_at": null,
                        "object": "validation_rules_assignment"
                    }
                ],
                "object": "list",
                "total": 1,
                "data_ref": "data"
            },
            "active": true
        },
        {
            "id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
            "object": "promotion_tier",
            "name": "Free shipping",
            "banner": "Sale products are now shipped for free!",
            "campaign": {
                "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
                "object": "campaign",
                "start_date": "2021-10-01T00:00:00Z",
                "expiration_date": "2021-10-31T00:00:00Z",
                "active": true
            },
            "action": {
                "discount": {
                    "type": "UNIT",
                    "unit_off": 1.0,
                    "unit_type": "prod_5h1pp1ng",
                    "effect": "ADD_MISSING_ITEMS"
                }
            },
            "metadata": {},
            "summary": {
                "redemptions": {
                    "total_redeemed": 0
                },
                "orders": {
                    "total_amount": 0,
                    "total_discount_amount": 0
                }
            },
            "hierarchy": 1,
            "validation_rule_assignments": {
                "data": [
                    {
                        "id": "asgm_0n3MY9FlFJdx5fnE",
                        "rule_id": "val_8Vgj4wq3LDJP",
                        "related_object_id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
                        "related_object_type": "promotion_tier",
                        "created_at": "2021-10-07T11:00:34Z",
                        "updated_at": null,
                        "object": "validation_rules_assignment"
                    }
                ],
                "object": "list",
                "total": 1,
                "data_ref": "data"
            },
            "active": true
        }
    ],
    "has_more": false
}

3. Validate Promotion
Check if the cart structure and customer attributes match the conditions defined in active promotion tiers. If the order is eligible for promotion, specific promotion tiers will be returned by the API.

See details of Validate Promotions endpoint.

// POST https://api.voucherify.io/v1/promotions/validation
{
    "customer": {
        "source_id": "[email protected]"
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"
    },
    "order": {
        "amount": 9000,
        "items": [
            {
                "source_id": "inventory_number_73636",
                "product_id": "prod_anJ03RZZq74z4v",
                "related_object": "product",
                "quantity": 1,
                "price": 9000,
                "product": {
                    "name": "Headphones",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "SALE"
                    }
                }
            }
        ]
    }
}
{
    "valid": true,
    "tracking_id": "track_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
    "promotions": [
        {
            "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_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
            "order": {
                "amount": 9000,
                "discount_amount": 900,
                "total_discount_amount": 900,
                "total_amount": 8100,
                "applied_discount_amount": 900,
                "total_applied_discount_amount": 900,
                "items": [
                    {
                        "object": "order_item",
                        "source_id": "inventory_number_73636",
                        "related_object": "product",
                        "product_id": "prod_anJ03RZZq74z4v",
                        "quantity": 1,
                        "amount": 9000,
                        "price": 9000,
                        "subtotal_amount": 9000,
                        "product": {
                            "id": "prod_09eb7c37e98a86267e",
                            "source_id": "prod_anJ03RZZq74z4v",
                            "name": "Headphones",
                            "metadata": {
                                "shop": "citycenter",
                                "category": "SALE"
                            }
                        }
                    }
                ],
                "customer_id": null,
                "referrer_id": null,
                "object": "order"
            },
            "id": "promo_DkBL24GWmNZ1A75bhEiBTNWO",
            "name": "10% off",
            "banner": "Spend $50 and get 10% off your order",
            "discount": {
                "type": "PERCENT",
                "effect": "APPLY_TO_ORDER",
                "percent_off": 10
            },
            "start_date": "2021-10-01T00:00:00.000Z",
            "expiration_date": "2021-10-31T00:00:00.000Z",
            "campaign": {
                "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
                "start_date": "2021-10-01T00:00:00.000Z",
                "expiration_date": "2021-10-31T00:00:00.000Z",
                "active": true,
                "object": "campaign"
            },
            "hierarchy": 3,
            "discount_amount": 900,
            "applied_discount_amount": 900,
            "metadata": {},
            "object": "promotion_tier"
        },
        {
            "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_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
            "order": {
                "amount": 9000,
                "total_amount": 9000,
                "items": [
                    {
                        "object": "order_item",
                        "source_id": "inventory_number_73636",
                        "related_object": "product",
                        "product_id": "prod_anJ03RZZq74z4v",
                        "quantity": 1,
                        "amount": 9000,
                        "price": 9000,
                        "subtotal_amount": 9000,
                        "product": {
                            "id": "prod_09eb7c37e98a86267e",
                            "source_id": "prod_anJ03RZZq74z4v",
                            "name": "Headphones",
                            "metadata": {
                                "shop": "citycenter",
                                "category": "SALE"
                            }
                        }
                    },
                    {
                        "object": "order_item",
                        "product_id": "prod_5h1pp1ng",
                        "quantity": 1,
                        "discount_quantity": 1,
                        "initial_quantity": 0,
                        "product": {
                            "id": "prod_5h1pp1ng",
                            "source_id": "5h1pp1ng",
                            "name": "Shipping"
                        }
                    }
                ],
                "customer_id": null,
                "referrer_id": null,
                "object": "order"
            },
            "id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
            "name": "Free shipping",
            "banner": "Sale products are now shipped for free!",
            "discount": {
                "type": "UNIT",
                "effect": "ADD_MISSING_ITEMS",
                "unit_off": 1,
                "unit_type": "prod_5h1pp1ng"
            },
            "start_date": "2021-10-01T00:00:00.000Z",
            "expiration_date": "2021-10-31T00:00:00.000Z",
            "campaign": {
                "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
                "start_date": "2021-10-01T00:00:00.000Z",
                "expiration_date": "2021-10-31T00:00:00.000Z",
                "active": true,
                "object": "campaign"
            },
            "hierarchy": 1,
            "metadata": {},
            "object": "promotion_tier"
        }
    ]
}

The API returns a list of valid promotions for a given context (customer and order).

4. Redeem Promotion
The promotion tier can be redeemed as many times as you define – once, X number of times, or an unlimited number of times. The history of the redemptions is accessible via API and dashboard.

Learn more about redeeming promotions via API.

// POST https://api.voucherify.io/v1/promotions/tiers/promo_2X0DEfcD2mvtnjkf0gVAzFks/redemption
{
    "customer": {
        "source_id": "[email protected]"
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"
    },
    "order": {
        "amount": 9000,
        "items": [
            {
                "source_id": "inventory_number_73636",
                "product_id": "prod_anJ03RZZq74z4v",
                "related_object": "product",
                "quantity": 1,
                "price": 9000,
                "product": {
                    "name": "Headphones",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "SALE"
                    }
                }
            }
        ]
    }
}
{
    "id": "r_Zn89sYWUQRrEyvBsP5pl5WGQ",
    "object": "redemption",
    "date": "2021-10-07T12:05:05.320Z",
    "customer_id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
    "tracking_id": "track_otz3irNtDcvoZO+7uwUGiSTTeJ0BnNFq",
    "order": {
        "id": "ord_tp4T8C4j8l5EV2MtsRi0ZZVM",
        "source_id": null,
        "created_at": "2021-10-07T12:05:05.162Z",
        "updated_at": null,
        "status": "PAID",
        "amount": 9000,
        "total_amount": 9000,
        "items": [
            {
                "object": "order_item",
                "source_id": "inventory_number_73636",
                "related_object": "product",
                "product_id": "prod_anJ03RZZq74z4v",
                "quantity": 1,
                "amount": 9000,
                "price": 9000,
                "subtotal_amount": 9000,
                "product": {
                    "id": "prod_09eb7c37e98a86267e",
                    "source_id": "prod_anJ03RZZq74z4v",
                    "name": "Headphones",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "SALE"
                    }
                }
            },
            {
                "object": "order_item",
                "product_id": "prod_5h1pp1ng",
                "quantity": 1,
                "discount_quantity": 1,
                "product": {
                    "id": "prod_5h1pp1ng",
                    "source_id": "5h1pp1ng",
                    "name": "Shipping"
                }
            }
        ],
        "customer": {
            "id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
            "object": "customer"
        },
        "customer_id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
        "referrer_id": null,
        "object": "order",
        "redemptions": {
            "r_Zn89sYWUQRrEyvBsP5pl5WGQ": {
                "date": "2021-10-07T12:05:05.320Z",
                "related_object_type": "promotion_tier",
                "related_object_id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
                "related_object_parent_id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk"
            }
        }
    },
    "metadata": {
        "payment_method": "PayPal",
        "shipping-zone": "EU-Spain"
    },
    "result": "SUCCESS",
    "customer": {
        "id": "cust_2FJk3ugCZ1sevAFNAWDwW5dv",
        "name": "Nana Lemon",
        "email": "[email protected]",
        "source_id": "[email protected]",
        "object": "customer"
    },
    "related_object_type": "promotion_tier",
    "voucher": null,
    "promotion_tier": {
        "id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
        "name": "Free shipping",
        "banner": "Sale products are now shipped for free!",
        "action": {
            "discount": {
                "type": "UNIT",
                "effect": "ADD_MISSING_ITEMS",
                "unit_off": 1,
                "unit_type": "prod_5h1pp1ng"
            }
        },
        "metadata": {},
        "hierarchy": 1,
        "campaign": {
            "id": "camp_pq7y5ZSh2xt1NvC6Bl5Ymlzk",
            "start_date": "2021-10-01T00:00:00.000Z",
            "expiration_date": "2021-10-31T00:00:00.000Z",
            "active": true,
            "object": "campaign"
        },
        "active": true,
        "summary": {
            "redemptions": {
                "total_redeemed": 1
            },
            "orders": {
                "total_amount": 9000,
                "total_discount_amount": 0
            }
        },
        "object": "promotion_tier",
        "validation_rule_assignments": {
            "object": "list",
            "data_ref": "data",
            "data": [
                {
                    "id": "asgm_0n3MY9FlFJdx5fnE",
                    "rule_id": "val_8Vgj4wq3LDJP",
                    "related_object_id": "promo_2X0DEfcD2mvtnjkf0gVAzFks",
                    "related_object_type": "promotion_tier",
                    "object": "validation_rules_assignment"
                }
            ],
            "total": 1
        }
    }
}

Examine Promotion Qualification and Publish Unique Code

Let's analyze the following scenario: find if a customer is VIP (customer life time value > 3000) and send them a unique gift card.

Imagine that we have a gift card campaign only for VIP customers. We want to reward them with $100 gift when their total spend is greater than $3000.

In the Campaign Manager, we created a new gift card campaign with the following validation rule — include all customers with customer_life_time_value metadata field greater than 3000.

1. Examine Qualification
Now, let's qualify a customer when they log in to the app. Use Examine Qualification for unique campaign codes..

Note: for standalone coupons (fixed-code coupons like "BLCKFRDY") use Examine Qualification.

// POST https://api.voucherify.io/v1/campaigns/qualification
{
    "customer": {
        "source_id": "test_customer_id_2"
    }
}

// this customer has the following metadata, 
// schema is available in your sandbox account
// {
//   customer_life_time_value: 3500
// }
{
   "created_at" : "2022-02-17T13:02:51.733Z",
   "data" : [
      {
         "active" : true,
         "auto_join" : false,
         "campaign_type" : "GIFT_VOUCHERS",
         "created_at" : "2022-02-17T11:58:04.808Z",
         "creation_status" : "DONE",
         "id" : "camp_UfT9PCTEgxbVCmrJmbV5Y279",
         "join_once" : true,
         "metadata" : {},
         "name" : "VIP Gift Cards",
         "object" : "campaign",
         "protected" : false,
         "type" : "AUTO_UPDATE",
         "use_voucher_metadata_schema" : true,
         "validation_rules_assignments" : {
            "data" : [
               {
                  "id" : "asgm_KjPkPwvHA2ddH2nh",
                  "object" : "validation_rules_assignment",
                  "related_object_id" : "camp_UfT9PCTEgxbVCmrJmbV5Y279",
                  "related_object_type" : "campaign",
                  "rule" : {
                     "applicable_to" : {
                        "excluded" : [],
                        "included" : [],
                        "included_all" : false
                     },
                     "context_type" : "campaign.gift_vouchers.gift.apply_to_order",
                     "created_at" : "2022-02-17T11:58:04.521Z",
                     "id" : "val_etVPIsh1DiDX",
                     "name" : "Business Validation Rule - VIP Gift Cards",
                     "object" : "validation_rules",
                     "rules" : {
                        "1" : {
                           "conditions" : {
                              "$is" : [
                                 "seg_ckkhHLqsiEKNTdAts7tutrR1"
                              ]
                           },
                           "name" : "customer.segment",
                           "property" : null,
                           "rules" : {}
                        },
                        "logic" : "1"
                     },
                     "type" : "basic"
                  },
                  "rule_id" : "val_etVPIsh1DiDX"
               }
            ],
            "data_ref" : "data",
            "object" : "list",
            "total" : 1
         },
         "voucher" : {
            "code_config" : {
               "charset" : "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
               "pattern" : "TY-####"
            },
            "gift" : {
               "amount" : 10000,
               "effect" : "APPLY_TO_ORDER"
            },
            "is_referral_code" : false,
            "redemption" : {
               "quantity" : 1
            },
            "type" : "GIFT_VOUCHER"
         },
         "vouchers_count" : 1,
         "vouchers_generation_status" : "DONE"
      },
      // removed for brevity
   ],
   "data_ref" : "data",
   "id" : "qfl_x3CQWFV6cRP3ZQKMi7uMmgIZ",
   "object" : "list",
   "total" : 6,
   "tracking_id" : "track_Pw6r3ejnml43kIwNS4Zj09KZ67xOfLUy"
}

Voucherify responds with the list of all active campaigns that are eligible for this customer. One of them is our gift card campaign. Note that you can also pass the order object to get a list of eligible promotions right at the checkout stage.

Now we can publish a unique gift card to this customer.

2. Publish Unique Gift Card
The publication endpoint is used to assign a selected code to specific customer. More than 1 codes can be published with a single request.

// POST https://api.voucherify.io/v1/publications?join_once=true
{
    "campaign": {
        "name": "VIP Gift Cards",
        "count": 1
    },
    "customer": {
        "source_id": "test_customer_id_2"
    }
}
{
   "channel" : "API",
   "created_at" : "2022-02-17T13:26:17.990Z",
   "customer" : {
      "email" : "[email protected]",
      "id" : "cust_JpLhfWwf0BmjNvMerqEdawnC",
      "metadata" : {
         "customer_life_time_value" : 3500,
         "lang" : "en",
         "test" : true
      },
      "name" : "Jane Doe",
      "object" : "customer",
      "source_id" : "test_customer_id_2"
   },
   "customer_id" : "cust_JpLhfWwf0BmjNvMerqEdawnC",
   "id" : "pub_pfUQoMuPcZQHrF5erx9IWzhR5qxz6b27",
   "metadata" : {},
   "object" : "publication",
   "result" : "SUCCESS",
   "source_id" : null,
   "tracking_id" : "test_customer_id_2",
   "voucher" : {
      "active" : true,
      "additional_info" : null,
      "assets" : {
         "barcode" : {
            "id" : "U2FsdGVkX19YkAnIOnRJQpeEWohIJ1fzvz5NDfUlVMR5XT7WxRu+5JdnQerKJhwmY/tsgj5diQyx8ShR7bHzQT4tkZHNusEJKIAeF81USenIjKE5o37uanhqajXWAJ9F9oTAH/Hmc6K+tPpK5QZmeQ==",
            "url" : "https://dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19YkAnIOnRJQpeEWohIJ1fzvz5NDfUlVMR5XT7WxRu%2B5JdnQerKJhwmY%2Ftsgj5diQyx8ShR7bHzQT4tkZHNusEJKIAeF81USenIjKE5o37uanhqajXWAJ9F9oTAH%2FHmc6K%2BtPpK5QZmeQ%3D%3D"
         },
         "qr" : {
            "id" : "U2FsdGVkX1/DxyvSkkZ/uawLdHD80BA6UZiNGpCA5zxR45DeT/qprnKOB+f4rfc186OnZtH9/PyBMbJ6FI0swaoN4ZZ8AZvT979grSJ/zOrEQPCYfiP6zH7hzgimv8C5n6fDbLX0MRqSYP2nXuhScA==",
            "url" : "https://dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2FDxyvSkkZ%2FuawLdHD80BA6UZiNGpCA5zxR45DeT%2FqprnKOB%2Bf4rfc186OnZtH9%2FPyBMbJ6FI0swaoN4ZZ8AZvT979grSJ%2FzOrEQPCYfiP6zH7hzgimv8C5n6fDbLX0MRqSYP2nXuhScA%3D%3D"
         }
      },
      "campaign" : "VIP Gift Cards",
      "campaign_id" : "camp_UfT9PCTEgxbVCmrJmbV5Y279",
      "category" : null,
      "code" : "TY-OeR0",
      "created_at" : "2022-02-17T11:58:06.389Z",
      "discount" : null,
      "expiration_date" : null,
      "gift" : {
         "amount" : 10000,
         "balance" : 10000,
         "effect" : "APPLY_TO_ORDER"
      },
      "holder_id" : "cust_JpLhfWwf0BmjNvMerqEdawnC",
      "id" : "v_32vO3U2wlyhiAGEyYWDVoBhpgOSscmnW",
      "is_referral_code" : false,
      "loyalty_card" : null,
      "metadata" : {},
      "object" : "voucher",
      "publish" : {
         "count" : 1,
         "object" : "list",
         "url" : "/v1/vouchers/TY-OeR0/publications?page=1&limit=10"
      },
      "redemption" : {
         "object" : "list",
         "quantity" : 1,
         "redeemed_amount" : 0,
         "redeemed_quantity" : 0,
         "url" : "/v1/vouchers/TY-OeR0/redemptions?page=1&limit=10"
      },
      "start_date" : null,
      "type" : "GIFT_VOUCHER",
      "updated_at" : "2022-02-17T13:26:17.992Z",
      "validity_day_of_week" : null,
      "validity_timeframe" : null
   },
   "vouchers_id" : [
      "v_32vO3U2wlyhiAGEyYWDVoBhpgOSscmnW"
   ]
}

Voucherify responds with a newly assigned gift card code, you can show it to the customer.


Did this page help you?