Background

These set of end points will get you started with an end to end Loyalty program that you can white label. You will not have to maintain separate infrastructure or worry about building new features, which will cost you multiple software engineers (SWE) and several quarters to build your very first version and will spend a bomb to continue to maintain it. Many a times, the value generated from the rewards program is drained due to poor design and implementation.

To make it easy for you, we made some assumptions to get you started without worrying how to structure the program. Should you have 3 tiers or 4 tiers? What percentage points to offer? Should 1 point equal $1 or ¢1? What should be the range for each of the tiers? Do you determine the tiers based on the points or the spend? Too many things for you to think about which makes it harder to get started. With this set of APIs, most of these will have default values and these default values will work for most of the businesses. If you have a need to try a different configuration and you are in one of the paid tiers, please email support@1card.ai with your subscription details and we will respond at the earliest (we are generally responsive unless something major going on with the team).

These set of APIs are designed to cater to your online business and integrate with your website. The following tutorial assumes you are an online business and want to offer a loyalty program without building your own. Please note if you are a retail business or a company that offers Point of Sale (POS) systems and want to offer or integrate Loyalty program with yours, these set of APIs can still be used but the flow may be slightly different.

Program Design

We mentioned we have made some assumptions to get you started without too much thinking. Here are some of the details.

There are 5 tiers with the below ranges
* Bronze (spend < 5000)
* Silver (5000 <= spend < 15000)
* Gold (15000 <= spend < 30000)
* Diamond (30000 <= spend < 70000)
* Platinum (70000 <= spend)

Note that there is no currency mentioned above. This is because the ranges are currency agnostic (we understand this is not ideal and working on providing different ranges for different currencies).

The reward percentage is based on the tier when the call is made.
* Bronze - 3%
* Silver - 5%
* Gold - 7%
* Diamond - 10%
* Platinum - 15%

Again, soon we will offer an option to configure these to different values but these values should get you started to understand and figure out what works best for your business.

The tier determination is based on the spend amount and not on the points earned. For instance, if your currency is USD ($), then a customer has to spend $5000 which will earn them $150 worth of points (15,000 points) to attain Silver tier.

The tier amounts are always reset at the start of the year (Jan 1st) and the previous year status will determine the current year earning tier rate. For example, if you end with Gold tier on Dec 31st last year, your earning rate will be 7% or better for the current year.

Any spend that did NOT qualify for earning the next tier will automatically carry over to the next year status earning. For example, if you spend $22,000 in a year, you would have earned the Gold tier status (more than $15,000 spend) The $7000 that did not qualify for the Diamond status in the year will be carried forward to the next year and will automatically earn the Silver status. This is to encourage the users to continue to spend and earn at a higher rate. Without this feature, the rewards program breaks down quickly once a user reaches a higher tier and determines they will not be able to reach the next tier within the year.

This is how most of the airline miles program work.

Credit Points

You will pass in the billed amount in the /creditPoints end point and the reward points are calculated as per the user tier; For instance if the billed amount is $100, and the use is in the Bronze tier, the reward is 3% and hence $3 worth of points will be credited. As each currency unit ($1, ₹1, £1, etc.) are worth 100 points, in this instance, 300 points will be credited to the user account.

Remember to send the billed amount you want the reward to be calculated on and not the points to be credited to the account. Also, if you do not want the tax amount to be rewarded with points, please do not include that amount in the /creditPoints end point call

Redeem Points

Each currency unit is ($1, ₹1, £1, etc.) is worth 100 points and this cannot be changed. We have put lot of thought into this and this kind of conversion helps multiple stakeholders (business owner, end consumer, etc.) in ease of calculation. Also, your customers will be able to earn points for amounts less than standard unit of currency (cents, paise, etc.)

APIs

There are Five End points in this API.

/registerBusiness
/getPoints
/creditPoints
/redeemPoints
/verifyTransaction

/registerBusiness
You will call /registerBusiness end point only once to register your business. Please note most of the parameters are immutable after this call. Pay particular attention to the country of choice as this will auto determine the currency code, currency symbol and the country code that is prefixed to the phone numbers. We will add additional end points to add more location if you have a multi-location business.

/getPoints
The /getPoints end point is called once your user logs into your system (website, mobile app, etc.) to show them how many reward points they have that can be redeemed.

/creditPoints
The /creditPoints end point is called when your customer places an order with you and you are able to confirm the order. Depending on your particular use case, you may want to make this call once the payment is confirmed. Please note the billed amount is passed in this call and consider excluding any tax amount.

If the customer already has earned points, you would have ideally called redeem points before making this call. We are considering an end point that will both redeem and credit points at the same time but we will need to think this through before we expose this to public.

/redeemPoints

If the /getPoints call returned a non-zero amount of points (generally significant number of points), customers may want to redeem those towards a purchase. Before they place the order, have them redeem the points. This helps you determine the outstanding amount to be charged to the customer and also the amount to be rewarded on the current transaction.

This will send a SMS to the registered phone number of the user (which you pass in the request) and will not deduct the points until verifyTransaction is called successfully.

For example, assume the current transaction is $572 and the /getPoints when the user logged in retruned 10000 points. The user wants to use all of the points towards the current transaction. Following are the end point calls you would make in order.

/redeemPoints {bill_amount: 100}
/verifyTransaction {transaction_id: abc, otp: 123}
/creditPoints {bill_amount: 472}

Assuming the user is in the Bronze tier, following are the changes that are made.
Initital Balane: 10,000
Redeem: 10,000
Balance: 0
Credit: $472 X .03 X 100 = 1416 points (worth $14.16)

/verifyTransaction

The verifyTransaction call is required to complete the redeem transaction. The redeem transaction will be in the pending status and changed to approved only upon successful verification of the OTP by the end user.