Web & Apps Playbook
Voucherify API is built with developer-friendliness and speed of integration with customer touchpoints in mind. It is ready to cover the whole customer journey to enable the fastest possible time-to-market.
If you want to display data to your customers on your website or app, your app has to first fetch it from Voucherify and present it, for example in an e-mail or on the customer profile section. With Voucherify API it can be done in no time thanks to various API endpoints that help you display data, which reduces the amount of coding needed to be done by your developers.
This article is going to explore various possibilities for UI-facing API uses including:
- Client-side API endpoints
- Customizable UI widgets.
- Backend-side API and exemplary customer journeys.
- Landing pages creator.
- Email designer.
- Customer cockpits.
- Code patterns.
All of these features are crucially important if you want to quickly integrate customer touchpoints with Voucherify.
Connecting the API
There are two ways of connecting your web&apps to Voucherify API:
- Client-side – the action takes place on the user’s website or mobile application. It is faster to integrate because you only need to include voucherify.js or iOS/Android library respectively. Your developers can call requests directly from the app code. However, bear in mind that some functionalities might be limited due to security reasons in this type of set-up.
- Backend-side (server-side) – the action takes place on a web server. It is longer to integrate than the client-side API however it offers full functionality. It requires a secured middleware that will load data from Voucherify and push it forward to the app.
Client-side API endpoints
Voucherify offers separate API keys for client-side methods which you can find and reset (if needed) in the Project Settings. You can therefore safely use the limited set of endpoints directly in the web/app code. As an extra security measure, Voucherify can limit the client-side calls only to those coming from specific URLs.
The available client-side API methods are as follows:
|Validate voucher/promotion||This method is used to validate a client's request to redeem a voucher or promotion without marking it as used. This endpoint does not only return the information about the code/promotion validity but may also create a new customer object as Voucherify can help you track anonymous customers.|
|Redeem voucher/promotion/reward||This endpoint is used to redeem a voucher/promotion/reward. It will also automatically update the total redemption count and the redeemed object history. Be careful, as placing this functionality directly at your client-side set up (website or mobile app), may lead to vouchers being modified before being sent to the server.|
|List promotion tiers||Promotion tiers are used in the auto-applied (cart) discounts and so they do not require a unique code. By using this API method, you will receive a list of all promotion tiers from a given campaign. The next step is to validate the promotions to potentially match a valid promotion to the contents of the customer's cart.|
|Get consents||In compliance with GDPR and other data privacy regulations, you need to obtain an explicit customer consent in order to contact them. You can create consents using Voucherify Dashboard and use this API endpoint to list all marketing permissions in the Project.|
|Update customer consents||This API method is very handy if you want to automatically update consents given or revoked by customers. This method will update the consents for the given customer leaving you with reliable and up-to-date customer data.|
|Track custom event||Custom events are nothing more than the actions taken by your customers. You can track such events (after creating an event object and linking it to customers who perform the given action) and later on use them as reward triggers in your loyalty and referral programs.|
Ready UI widgets
On top of client-side and back-end API methods used for modeling your promotional workflows, we’ve also built ready UI widgets which make the integration process even faster. They can be also used for the prototyping stage.
These UI widgets can serve different purposes (e.g., validate promotion, redeem a code) and can be freely branded to resemble your brand style 1:1 with custom HTML and CSS.
What is a UI widget?
Visit this section for more details.
Examples of Voucherify widgets:
Imagine you want to assign and display unique codes to customers visiting one of your landing pages. Or you need a quick way to increase your customer email base with a smart subscription widget. With Voucherify widgets it’s as easy as 1 2 3.
Widgets can be placed on your websites outside Voucherify. You can copy a sample of code which when placed on your website will display simple web form. The forms are fully customizable. You can decide which fields are visible and which are mandatory.
Follow this article for detailed installation instruction.
Here are some examples of widgets built with Voucherify library:
- Validation widget
With this widget, customers may check the validity of their incentives without marking them as used.
Visit our documentation to learn more about the validation widget.
- Redemption widget
Thanks to the redemption widget, you can manage redemptions of already published (sent) incentives.
Visit our documentation to learn more about the redemption widget.
- Publication widget
In Voucherify, the publication of code to a customer is synonymous with a code assignment to a customer profile. With a publication widget in place, customers can publish (assign) unique codes to their profiles.
Visit our documentation to learn more about the publication widget.
- Listing widget
You can use this widget to list all available types of vouchers from the given campaign or category. You can use it to for instance display all available promotions in the check-out.
This widget is very handy in the creation of custom coupon codes sites and coupon aggregate websites. Coupon aggregates act like a landing page that allows your customers to easily find your store's best and most exciting offers and discounts which significantly boost customer satisfaction and in turn increases your company’s revenue.
We built a showcase landing page using the list.vouchers method.
Visit our documentation to learn more about the listing widget.
- Subscription/sign up form widget
Customer subscription widgets allow you to expand your customer base by allowing customers to sign up on your website by themselves. This part of Voucherify.js offers an easy way to add customers straight from the web.
Visit our documentation to learn more about the subscription widget.
Backend-side API and SDKs
Client-side API, UI widgets, and other customer-facing features are all very handy, but if you want to get a full-blown integration with maximum personalization capabilities and branding, we should start with the proper API integration.
Voucherify API is easy-to-use and developer-friendly. It has a predictable, resource-oriented URL and uses HTTP response codes to notify you about any errors.
We highly recommend that you check out our Developers' Documentation to learn more about our API.
We also offer SDKs for all major programming languages:
Below, we have prepared some examples of available API endpoints that help you put together web&app UI for your customers. Keep in mind that it’s just a fraction of the full scope of our API.
Follow this link for the full API reference.
| List the history of customer’s earning/spending activities. Useful when you want to present it in the profile section or for tracking purposes
| You can use this endpoint to verify a voucher code given by a customer. It will generate a response – voucher valid or invalid, and if not valid it will provide a reason.
| This endpoint lists all cart-level promotions valid for the customer and its current cart structure.
|Validates a voucher and marks it as redeemed.|
|Through this method, an integration exchanges points from a loyalty card for a specified reward. This API method returns an assigned award in response. It means that if a requesting customer gets a coupon code with a discount for the next order, that discount code will be visible in response.|
| This method adds balance to an existing loyalty card.
| This endpoint selects a valid voucher code and assigns it to a customer so that it won’t be used again by another customer. The returned voucher code can be published on a webpage or included in the email message.
| It helps your developer team sort and filter data, saving them time if you want to have a bit more advanced UI for your users.
Modeling customer journeys with API
- Create a customer – https://docs.voucherify.io/reference#create-customer
- Publish code to a customer – https://docs.voucherify.io/reference#create-publication
- Validate the code – https://docs.voucherify.io/reference#validate-voucher
- Redeem the code – https://docs.voucherify.io/reference#redeem-voucher
Auto-applied discount campaign:
- Create a new campaign – https://docs.voucherify.io/reference#create-promotion-campaign
- Create a validation rule and assign it to the particular promotion tier – https://docs.voucherify.io/reference#create-validation-rules
- List all promotion tiers so that customer visiting your shop may see all available promotions – https://docs.voucherify.io/v2017-04-20/reference#list-promotion-tiers
- Each time, a change occurs to customer’s cart, validate the content of their basket to match proper promotion tier – https://docs.voucherify.io/reference#validate-promotions-1
- Call the redemption endpoint to redeem a promotion – https://docs.voucherify.io/v2017.0.0-04-20/reference-link/redeem-promotion
- Create a reward – https://docs.voucherify.io/reference#create-reward
- Track a custom conversion event – https://docs.voucherify.io/reference#create-custom-event
- Use a webhook to send the referral reward to the referrer and the referee if the conversion criteria are met.
- Create an order – https://docs.voucherify.io/reference#create-order
- Create a reward – https://docs.voucherify.io/reference#create-reward
- List customer activity and rewards in a customer cockpit – https://docs.voucherify.io/reference#list-rewardshttps://docs.voucherify.io/reference#get-member-activities
- Exchange loyalty points for rewards – https://docs.voucherify.io/reference#redeem-loyalty-card
Landing pages creator
To allow for even quicker integration with customer-facing parts of your website or app, you can also publish and host landing pages with Voucherify promotions.
What’s in it for you? You get to create and publish landing pages where your customers can gain and redeem incentives themselves making up for not only an improved customer UX but also taking the burden off your developers’ shoulders.
With built-in templates, you can collect new signups, invite customers to your referral/loyalty campaigns, allow for client-side redemptions, and more.
All templates are freely customizable allowing you to design a page that reflects your marketing principles and branding style 1:1.
Take a look at some examples of a landing page created with Voucherify:
Follow this link for more information about Voucherify landing pages.
The built-in email editor allows you to implement your branding style. It means that even without a dedicated external app with ready-to-go templates, you can design emails with incentives that are adjusted to your brand style and messaging conventions.
To personalize your messaging better, you can use the following merge variables in the content of your message:
- Customer email address.
- Customer name.
- Link to individual customer cockpit.
- Name of the referral/loyalty reward.
- Discount coupon numerical and QR code, and value.
- Promotion name, banner, and value.
Each customer in your Voucherify account has their individual cockpit presenting details of their loyalty programs, assigned referral codes, and owned incentives (discounts, gift cards).
Voucherify gives you a possibility to freely customize what your customers are able to see in their cockpits, you can enable and disable certain views. You can also change the colors and logos to add your branding.
While creating a new campaign of unique codes, fixed codes, loyalty, or referral program you can precisely define codes/cards structure:
Developer-friendly building blocks
Leverage developer-friendly building blocks for a shorter time-to-market:
- Flexible REST API
- SDK for major programming languages
- UI widgets
- Custom fields
- All top-level API resources have support for fetches via "list" API methods
- API methods for fetching resources offers extended capabilities for filtering data
- 99.9% uptime
- Webhooks for 56 events
- Redundant AWS data center
- Role-based API-keys
- GDPR, PCI, and CCPA compliance