Welcome to Voucherify! We’re excited to be your partner in building a future-proof promotion engine. Let’s start with a simple promotional scenario — applying a $10 off BLCKFRDY coupon to the cart — to learn how Voucherify works.

To begin with Voucherify, you must first create an account — Voucherify offers a free tier (“Sandbox project”) you can use to build a proof of concept and, further, test it with production.

Join the dashboard

After you create your account, you get access to the Sandbox dashboard. Sandbox comes with a set of predefined promotional scenarios. That’s why when you browse through the views, you can see several objects already created. One of the essential objects in Voucherify is a voucher. In a nutshell, it represents a code that serves as an identifier for promotions supported by the Voucherify engine including a coupon, referral code, or a gift card.

Type BLCKFRDY in the search bar and Voucherify will redirect you to the voucher page which displays the basic information about the discount it carries. Let’s redeem the code with the API.

Get your API keys

The Sandbox Project Dashboard is already showing your default API keys for the Sandbox project. You can also navigate to Project Settings to find the Authentication section.

Make a test API request

Within the Sandbox, you get 100 API calls per hour. Visit Limits to learn how to monitor your usage. With the first API request, we’ll redeem our coupon. This function is essential to Voucherify workflow as it takes care of:

checking if the code is recognizable with your account,
validating if it satisfies the business rules,
calculating and returning the discount value,
marking the code as used.

Note: while calling the redemption endpoint is enough to satisfy a basic promo code flow, it's useful to add validation to the flow every time the promo code or cart changes. Validation performs 1-3 points but it doesn't marks the code as used one.

Let’s call a test redemption. Use the following snippet with the keys copied from the Project Settings. Make sure you choose the correct API endpoint for the region you selected when creating your account.

(You can also check out our SDKs and call our API right from your development environment).

curl -X POST \
-H "X-App-Id: ID" \
-H "X-App-Token: SECRET KEY" \
-H "Content-Type: application/json" \
-d '{"order": {"amount": 20000} }' "https://api.voucherify.io/v1/vouchers/BLCKFRDY/redemption"

const { VoucherifyServerSide } = require('@voucherify/sdk')

const client = VoucherifyServerSide({
    applicationId: 'ID',
    secretKey: 'TOKEN',
    // apiUrl: 'https://<region>.api.voucherify.io'
})

client.redemptions.redeem("BLCKFRDY", {"order" : {"amount": 20000}}).then(console.log)

Voucherify should reply with the redemption details as in the screenshot below. If Voucherify doesn’t reply with a 20x status, check the error code to find the reason.

{
    "id": "r_1utfsnmdnq9KMh4xEKjcZT3m",
    "object": "redemption",
    "date": "2022-02-16T07:39:21.575Z",
    "customer_id": null,
    "tracking_id": null,
    "metadata": null,
    "result": "SUCCESS",
    "order": {
        "id": "ord_0r32g8iQNp0WA84fBK814RgG",
        "source_id": null,
        "created_at": "2022-02-16T07:39:21.546Z",
        "updated_at": null,
        "status": "PAID",
        "amount": 20000,
        "discount_amount": 1000,
        "total_discount_amount": 1000,
        "total_amount": 19000,
        "applied_discount_amount": 1000,
        "total_applied_discount_amount": 1000,
        "customer_id": null,
        "referrer_id": null,
        "object": "order",
        "redemptions": {
            "r_1utfsnmdnq9KMh4xEKjcZT3m": {
                "date": "2022-02-16T07:39:21.575Z",
                "related_object_type": "voucher",
                "related_object_id": "v_MMn7nc75rwUjdPnfl4X6NtCAK5MDNgNk"
            }
        }
    },
    "customer": null,
    "related_object_type": "voucher",
    "related_object_id": "v_MMn7nc75rwUjdPnfl4X6NtCAK5MDNgNk",
    "voucher": {
        "id": "v_MMn7nc75rwUjdPnfl4X6NtCAK5MDNgNk",
        "code": "BLCKFRDY",
        "campaign": null,
        "campaign_id": null,
        "category": "showcase",
        "type": "DISCOUNT_VOUCHER",
        "discount": {
            "type": "AMOUNT",
            "amount_off": 1000
        },
        "gift": null,
        "loyalty_card": null,
        "start_date": null,
        "expiration_date": null,
        "validity_timeframe": null,
        "validity_day_of_week": null,
        "active": true,
        "additional_info": null,
        "metadata": {
            "name": "Black Friday Coupon"
        },
        "assets": {
            "qr": {
                "id": "U2FsdGVkX1/FEz2OO26+KPxsV7dn/EFfzLbdGNArC+25Y8CX1j+beNmaxFcbOTVHnHHvmHzc50VdE+D0Cimz+7ZMJC92PSvshoCDBEnu5T10TOKozvVTaZn5O1NfaR5q+3zDnWRoFhfCcg/TilTQng==",
                "url": "https://dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2FFEz2OO26%2BKPxsV7dn%2FEFfzLbdGNArC%2B25Y8CX1j%2BbeNmaxFcbOTVHnHHvmHzc50VdE%2BD0Cimz%2B7ZMJC92PSvshoCDBEnu5T10TOKozvVTaZn5O1NfaR5q%2B3zDnWRoFhfCcg%2FTilTQng%3D%3D"
            },
            "barcode": {
                "id": "U2FsdGVkX1+Pgk0VxfAp5EbUgyoJxdy9Dcnnt4YYF64Kdk4o3GXzc3NeOvi6wFL27I2/j8bbMm8xZxETc6C0xgV9DcDUarJhpYjA4k+EhSu0dvoqrkSuGo1Pk+yFAeu7dieakoIR2xv+5B2ebqXstQ==",
                "url": "https://dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2BPgk0VxfAp5EbUgyoJxdy9Dcnnt4YYF64Kdk4o3GXzc3NeOvi6wFL27I2%2Fj8bbMm8xZxETc6C0xgV9DcDUarJhpYjA4k%2BEhSu0dvoqrkSuGo1Pk%2ByFAeu7dieakoIR2xv%2B5B2ebqXstQ%3D%3D"
            }
        },
        "is_referral_code": false,
        "created_at": "2022-02-16T06:58:29.207Z",
        "updated_at": "2022-02-16T07:39:21.576Z",
        "validation_rules_assignments": {
            "object": "list",
            "data_ref": "data",
            "data": [],
            "total": 0
        },
        "redemption": {
            "quantity": null,
            "redeemed_quantity": 1,
            "object": "list",
            "url": "/v1/vouchers/BLCKFRDY/redemptions?page=1&limit=10"
        },
        "publish": {
            "object": "list",
            "count": 0,
            "url": "/v1/vouchers/BLCKFRDY/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"
        }
    }
}

Because BLCKFRDY doesn’t have any redemption limits, you can use it multiple times.

Review logs in the dashboard

Every redemption can be listed with the API or in the dashboard. When you go to the voucher view, in “Recent changes” you’ll see operations performed on the object. You can switch to the REDEMPTIONS HISTORY tab to track all redemptions.

To monitor and filter the list of all API calls for your project, you can go the Audit log:

Test more promo scenarios with “Hot beans” demo store

Hot beans simulates a simple ecommerce engine allowing your team to verify the look and feel of the promotion customer journey. It supports coupons (including “BLCKFRDY”) and cart-level promotions; the full list of supported scenarios can be found in the Testing section.

You can access Hot Beans directly from your Voucherify dashboard. Hot beans’ checkout is automatically connected to your Voucherify account and the side panel shows all the requests sent to Voucherify API.

Try redeeming BLCKFRDY to go through the coupon flow end-to-end (make sure “cart discounts” is disabled to unlock the coupon input).

What's next

The BLCKFRDY coupon redemption uses only the minimum business context (order amount). To enable advanced promotional rules, go to the integration checklist and explore the Voucherify building blocks to learn what data you can share with Voucherify.