Custom voucher rewards are available on Shopify, from the Small Business plan up, and they are not enabled by default. If you would like this reward type added to your account, reach out to our Support team.
In this article:
Overview
A Custom voucher reward pays out a discount code from a pool that you upload to LoyaltyLion. You create the discount codes in Shopify yourself, then upload them to LoyaltyLion as a CSV file. Every code must already exist in Shopify, with the discount value you want it to carry, before you upload it. When a customer claims the reward, we hand them one unused code from that pool.
The codes are yours, not ours. We never create them and we do not read what discount each one carries, so a Custom voucher reward has no discount value, expiry date or discount combination settings of its own. It has a points cost, a pool of codes, and a title your customers see. There is no inventory limit either, because the pool of codes is the inventory.
How Custom voucher rewards can help you
Every other LoyaltyLion voucher reward generates its own discount codes to a pattern we control. A Custom voucher reward hands that back to you, which is useful when the code itself matters:
Discounts our reward types do not express. Shopify supports discount rules beyond what our reward forms offer. Build the code in Shopify with exactly the conditions you want, and let your customers earn it with points.
A fixed, pre-approved batch. Because you create every code yourself, you decide exactly how many exist and what each is worth before a single customer sees one.
Codes you need to recognise. You choose the code text, so loyalty codes can carry whatever naming your reporting or your finance team needs.
How to set up a Custom voucher reward
Create your codes before you start. LoyaltyLion cannot generate them for you, and a Custom voucher reward cannot be created without a pool to draw from.
Generate your codes in the system that will accept them, and export them as a CSV file. Put one code per line with no header row. Extra columns are ignored, so a wider export still works as long as the code is the first column.
In LoyaltyLion, go to Program, and then Rewards.
Click Create reward, and then choose Custom voucher.
Set the Points cost. If your program uses tiers, you can set a different cost for each tier.
Under Voucher codes, upload your CSV file by dragging it onto the upload area or clicking to browse. Click Download example CSV if you want to check the format first.
Choose When codes run out: either show the reward as "Out of stock", or hide it from your customers until you've added more.
Optionally, tick Limit how many times a customer can redeem this reward and set the count and frequency.
Add the Title and Description your customers will see, then click Create.
You'll land on the reward's edit page, where the Voucher codes section shows how many codes are available. That count is your confirmation that the pool uploaded.
Managing your voucher codes
CSV requirements
Your uploads must meet the following requirements:
A
.csvfile, smaller than 5MBOne code per line, with no header row. A header row would be imported as a voucher code
Up to 100,000 codes per file. Split a larger batch across several uploads
We ignore any code that already exists anywhere in your program, whether it's in this reward's pool or another's. Matching ignores capitalization, so SUMMER-A1B2 and summer-a1b2 count as the same code. If every code in a file is already in your program, we reject the whole upload and tell you, rather than adding nothing and reporting success.
Adding more codes
You can top up a pool at any time, from either of two places:
On the reward's edit page, in the Voucher codes section, click Add more codes
On the Program > Rewards list, open the reward's ⋯ menu and click Manage codes, then click Upload CSV
Keeping an eye on the pool
The Voucher codes section on the reward's edit page shows how many codes are still available, and adds a Running low badge as the pool gets close to empty. We also email your account owner when a reward's pool is running low, at most once a week per reward. If you'd like us to change the level your reward warns you at, contact our Support team.
Once the pool is empty, customers can't claim the reward at all. Depending on your "When codes run out" setting, they'll either see it marked as out of stock or not see it. Top the pool up before it empties.
Seeing which code went to which customer
To see every code in a reward's pool, go to Program > Rewards, open the reward's ⋯ menu, and click Manage codes. Each code shows who claimed it, when it was used, when it expires, and the order it was used with. You can filter by status, which is one of Available, Claimed, Used or Expired, and search by customer, order or code.
Redeeming Custom voucher rewards outside your online store
Custom voucher rewards are available on every sales channel, including point of sale. Merchants running their own till use this to let a customer spend points in store and hand back one of your Shopify discount codes. That takes a small amount of development work on your side, and it runs through our Headless API rather than anything you configure in LoyaltyLion.
In outline, your backend:
Looks up the customer to see their points balance and which rewards they can afford, and identifies the reward you want to offer at the till
Calls the custom reward redemption endpoint with that customer and reward, sending
posas the channelReads the code out of the response and shows it to your staff, who apply it to the transaction
The code comes back inside the claimed reward on that response, and stays readable afterwards on the customer, so a POS can show a customer a code they claimed earlier without redeeming a second one.
If the pool is empty when your backend tries to redeem, the request fails with an out-of-stock error rather than issuing a code.
Before you build, check that your point of sale can do what a loyalty integration needs, particularly whether it accepts discount codes it didn't create.
Where to go next:
Custom POS Integration Framework to work out whether your point of sale can support a loyalty integration at all, and what your own backend has to provide
API keys to create the key your backend will authenticate with. This is the one step you do in LoyaltyLion yourself
Headless API documentation to hand to your developer. It covers looking up a customer and the rewards they can afford, and the custom reward redemption endpoint that spends the points and returns the code
Telling us when a code has been used
Claiming a Custom voucher reward and using it are two separate things. We know the moment a customer claims a code, because we issued it. We only know it was spent when an order carrying that code reaches us.
If your orders reach LoyaltyLion already, whether through your ecommerce platform or because you send them to us, include the discount code on the order and we'll mark the matching code as used and link it to that order. Nothing else is needed.
If your in-store orders never reach LoyaltyLion, we have no way to know a code was spent. Those codes stay Available in the code list even after a customer has used them at the till.
If you need to start sending us your in-store orders, our Create an order reference lists the fields we expect, including the discount codes an order carries.
FAQ
Can LoyaltyLion generate the codes for me?
No. A Custom voucher reward exists precisely so you can use codes from your own system, so the pool is always yours to create and upload. If you want us to create discount codes automatically, use one of our other voucher rewards instead.
Where do I set the discount value?
You don't. The value lives in the code itself, in whichever system you created it in, so set it there before you upload. That also means we can't check it: if a code is worth more or less than you intended, we'll still hand it out.
What happens if I upload the same code twice?
We skip it. A code that already exists anywhere in your program is ignored, and we tell you how many were added and how many were duplicates. If a whole file is duplicates, we reject the upload.
If I refund a claimed reward, does the code go back into the pool?
No. The customer gets their points back and the claim is voided, but the code stays assigned to them and stays out of the pool, and it stays live in whichever system you created it in. If you don't want the customer to be able to use it, cancel the code there yourself.
Can I give the codes an expiry date?
Not in LoyaltyLion. Set the expiry on the code in the system that issued it, and it will apply when the customer tries to use it.
Can customers claim these rewards on my loyalty page as well as in store?
Yes. A Custom voucher reward is available on your loyalty page, in store, and anywhere else you offer rewards, and it draws from the same pool wherever it's claimed. If a code only works in one place, say so in the reward's description so customers know where to use it.