Skip to main content
In this tutorial, we will build a simple loyalty points system using the Blnk Ledger. Here’s what we’ll do:
  1. Create and manage multi-asset wallets in your ledger.
  2. Manage a pool of issued loyalty points.
  3. Award points to customers when they make purchases.
  4. Allow customers to redeem their points for discounts on future purchases.
For this tutorial, we’ll use the Blnk TypeScript SDK and Blnk Go SDK for the implementation. If you prefer, you can also refer to the API reference for details on the available endpoints.

​
Designing your map

Before writing code, it’s crucial to design a money movement map that outlines how money moves in your system. This serves as the blueprint for your implementation. For our loyalty points system, we have two workflows — awarding points and redeeming points.
  1. Awarding points: Points are awarded to customers who qualify for the loyalty program. A customer purchase triggers the process: funds from the Customer Main Wallet are used for the purchase, contributing to @RevenueUSD. Once the purchase is completed, points are awarded from the @PointsPool to the Customer Points Wallet.
    • @RevenueUSD: An internal balance representing the business’ revenue.
    • @PointsPool: An internal balance tracking the total points issued to customers.
    Awarding loyalty points map Explore the map yourself here
  2. Redeeming points: Customers can redeem points to receive discounts on purchases. When a customer applies points to a transaction, the discount is deducted from the original price. Once the purchase is completed, the redeemed points are transferred from the Customer Points Wallet to @PointsPool. Redeeming loyalty points map
@PointsPool records all issued points using the debit_balance parameter and tracks all redeemed points using the credit_balance parameter.

​
Set up your implementation

Based on our map, we’ll implement the following:
  1. Create the main and points balances for the customer.
  2. Initiate a purchase transaction and award points to the customer.
  3. Redeem the points in a second purchase transaction.

​
Prerequisites

Before starting, ensure you have:
  1. A running Blnk Core instance (e.g. at http://localhost:5001).
  2. An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
  3. Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.

​
Initialise your client

Initialize the Blnk client once at the start of your application: 
const { BlnkInit } = require('@blnkfinance/blnk-typescript');

let blnkInstance = null;

async function getBlnkInstance() {
  if (!blnkInstance) {
    blnkInstance = await BlnkInit('', { baseUrl: 'http://localhost:5001' });
  }
  return blnkInstance;
}

​
Create your ledgers

First, we need to create ledgers to organize our wallets: 
# Create main wallet ledger
curl -X POST "http://localhost:5001/ledgers" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Main Wallets",
    "meta_data": {
        "description": "Ledger for customer USD wallets"
    }
  }'

# Create points wallet ledger
curl -X POST "http://localhost:5001/ledgers" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Points Wallets",
    "meta_data": {
        "description": "Ledger for customer loyalty points"
    }
  }'

​
Create balances for customer funds and loyalty points

Blnk Finance supports tracking of different assets (e.g., USD and POINTS) in your ledger. Now, let’s create the main wallet and points wallet for the customer: 
# Create main wallet
curl -X POST "http://localhost:5001/balances" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "<main-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "USD",
    "meta_data": {
        "wallet_type": "main",
        "status": "active"
    }
  }'

# Create points wallet
curl -X POST "http://localhost:5001/balances" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "<points-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "POINTS",
    "meta_data": {
        "wallet_type": "points",
        "status": "active"
    }
  }'

​
Awarding points after a purchase

When a customer makes a purchase, we need to:
  1. Process the payment from the customer’s main wallet to the revenue account.
  2. Award loyalty points based on the purchase amount.
Ensure your customer main wallet is funded. Learn how: Wallet Funding →
Record the purchase payment and award loyalty points: 
# Process purchase
curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 10000,
    "precision": 100,
    "reference": "purchase-123456789",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "@RevenueUSD",
    "description": "Product purchase",
    "meta_data": {
        "transaction_type": "purchase"
    }
  }'

# Award points
curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 10,
    "precision": 1,
    "reference": "points-purchase-123456789",
    "currency": "POINTS",
    "source": "@PointsPool",
    "destination": "<customer-points-balance-id>",
    "description": "Loyalty points award",
    "allow_overdraft": true,
    "meta_data": {
        "purchase_reference": "purchase-123456789",
        "purchase_amount": 100
    }
  }'
As shown above, you can set custom precision for each currency, like 100 for USD or 1 for POINTS in our example.For ledger accuracy, ensure the source and destination currencies match when posting transactions.

​
Redeeming points during a purchase

When you make a purchase, you can use your loyalty points to get a discount. In our example, 10 points = 1 USD. For example, a customer has 500 points and wants to buy something that costs $100:
  1. They choose to use 200 points from their Points Wallet.
  2. Those 200 points convert to $20 (at the 10 points = $1 rate)
  3. Their final cost to pay from their Main Wallet would be $80 instead of $100.
Behind the scenes, here’s what we’ll do:
  1. Take points from the Customer Points Wallet to @PointsPool.
  2. Convert the points to its equivalent dollar value, apply it as discount, and calculate the final cost for the customer.
  3. Charge the Customer Main Wallet with the final discounted cost.
Redeem points and charge the discounted purchase amount: 
# Redeem points
curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 200,
    "precision": 1,
    "reference": "redemption-123456789",
    "currency": "POINTS",
    "source": "<customer-points-balance-id>",
    "destination": "@PointsPool",
    "description": "Points redemption for discount",
    "meta_data": {
        "transaction_type": "redemption",
        "convert_to_usd": 20
    }
  }'

# Process discounted purchase
curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 8000,
    "precision": 100,
    "reference": "purchase-redemption-123456789",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "@RevenueUSD",
    "description": "Discounted purchase with points",
    "meta_data": {
        "redemption_reference": "redemption-123456789",
        "original_amount": 100,
        "points_redeemed": 200
    }
  }'

​
Conclusion

You now have a basic loyalty points system built with the Blnk Ledger. This system enables you to award points to customers based on their purchases and allows them to redeem those points for discounts. The system is flexible and can be extended with additional features like:
  • Points expiry management
  • Tiered rewards based on customer spending levels
  • Special promotions with bonus points
  • Point transfers between customers
By leveraging Blnk’s transaction system, you can ensure all point movements are accurately tracked and reconciled, providing a reliable foundation for your loyalty program.