Building a Loyalty Points System with Blnk • Blnk Developer Documentation

In this tutorial, we will build a simple loyalty points system using the Blnk Ledger. Here’s what we’ll do:

Create and manage multi-asset wallets in your ledger.
Manage a pool of issued loyalty points.
Award points to customers when they make purchases.
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.

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.
Explore the map yourself here
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.

@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:

Create the main and points balances for the customer.
Initiate a purchase transaction and award points to the customer.
Redeem the points in a second purchase transaction.

Prerequisites

Before starting, ensure you have:

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

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"
    }
  }'

async function createLedgers() {
  
  
  // Create a ledger for customer main wallets (USD)
  const mainLedger = await blnk.Ledgers.create({
    name: "Customer Main Wallets",
    meta_data: {
      description: "Ledger for customer USD wallets"
    }
  });
  
  // Create a ledger for customer points wallets
  const pointsLedger = await blnk.Ledgers.create({
    name: "Customer Points Wallets",
    meta_data: {
      description: "Ledger for customer loyalty points"
    }
  });
  
  console.log("Created main wallet ledger:", mainLedger.data.ledger_id);
  console.log("Created points wallet ledger:", pointsLedger.data.ledger_id);
  
  return {
    mainLedgerId: mainLedger.data.ledger_id,
    pointsLedgerId: pointsLedger.data.ledger_id
  };
}

func createLedgers() (mainLedgerID, pointsLedgerID string, err error) {
    client := getClient()

    mainLedger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
        Name: "Customer Main Wallets",
        MetaData: map[string]interface{}{
            "description": "Ledger for customer USD wallets",
        },
    })
    if err != nil {
        return "", "", err
    }

    pointsLedger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
        Name: "Customer Points Wallets",
        MetaData: map[string]interface{}{
            "description": "Ledger for customer loyalty points",
        },
    })
    if err != nil {
        return "", "", err
    }

    fmt.Println("Created main wallet ledger:", mainLedger.LedgerID)
    fmt.Println("Created points wallet ledger:", pointsLedger.LedgerID)
    return mainLedger.LedgerID, pointsLedger.LedgerID, nil
}

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"
    }
  }'

async function createCustomerWallets(mainLedgerId, pointsLedgerId, identityId) {
  
  
  // Create main wallet (USD)
  const mainWallet = await blnk.LedgerBalances.create({
    ledger_id: mainLedgerId,
    identity_id: identityId,
    currency: "USD",
    meta_data: {
      wallet_type: "main",
      status: "active"
    }
  });
  
  // Create points wallet
  const pointsWallet = await blnk.LedgerBalances.create({
    ledger_id: pointsLedgerId,
    identity_id: identityId,
    currency: "POINTS",
    meta_data: {
      wallet_type: "points",
      status: "active"
    }
  });
  
  console.log("Created main wallet:", mainWallet.data.balance_id);
  console.log("Created points wallet:", pointsWallet.data.balance_id);
  
  return {
    mainWalletId: mainWallet.data.balance_id,
    pointsWalletId: pointsWallet.data.balance_id
  };
}

func createCustomerWallets(mainLedgerID, pointsLedgerID, identityID string) (mainWalletID, pointsWalletID string, err error) {
    client := getClient()

    mainWallet, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
        LedgerID:   mainLedgerID,
        IdentityID: identityID,
        Currency:   "USD",
        MetaData: map[string]interface{}{
            "wallet_type": "main",
            "status":      "active",
        },
    })
    if err != nil {
        return "", "", err
    }

    pointsWallet, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
        LedgerID:   pointsLedgerID,
        IdentityID: identityID,
        Currency:   "POINTS",
        MetaData: map[string]interface{}{
            "wallet_type": "points",
            "status":      "active",
        },
    })
    if err != nil {
        return "", "", err
    }

    fmt.Println("Created main wallet:", mainWallet.BalanceID)
    fmt.Println("Created points wallet:", pointsWallet.BalanceID)
    return mainWallet.BalanceID, pointsWallet.BalanceID, nil
}

Awarding points after a purchase

When a customer makes a purchase, we need to:

Process the payment from the customer’s main wallet to the revenue account.
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
    }
  }'

async function processPurchaseAndAwardPoints(mainWalletId, pointsWalletId, purchaseAmount, pointsToAward) {
  
  
  // Generate a unique reference for this purchase
  const purchaseReference = `purchase-${Date.now()}`;
  
  // Step 1: Process the purchase payment
  const purchase = await blnk.Transactions.create({
    precise_amount: purchaseAmount * 100,
    precision: 100,
    reference: purchaseReference,
    currency: "USD",
    source: mainWalletId,
    destination: "@RevenueUSD",
    description: "Product purchase",
    meta_data: {
      transaction_type: "purchase"
    }
  });
  
  // Step 2: Award loyalty points
  const pointsAward = await blnk.Transactions.create({
    precise_amount: pointsToAward,
    precision: 1,  // Points typically don't have decimal places
    reference: `points-${purchaseReference}`,
    currency: "POINTS",
    source: "@PointsPool",
    destination: pointsWalletId,
    description: "Loyalty points award",
    allow_overdraft: true,  // Points pool can have negative balance
    meta_data: {
      purchase_reference: purchaseReference,
      purchase_amount: purchaseAmount
    }
  });
  
  console.log("Purchase processed:", purchase.data.transaction_id);
  console.log("Points awarded:", pointsAward.data.transaction_id);
  
  return {
    purchaseId: purchase.data.transaction_id,
    pointsAwardId: pointsAward.data.transaction_id
  };
}

func processPurchaseAndAwardPoints(mainWalletID, pointsWalletID string, purchaseAmount, pointsToAward float64) (purchaseID, pointsAwardID string, err error) {
    client := getClient()
    purchaseReference := fmt.Sprintf("purchase-%d", time.Now().Unix())

    purchase, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: purchaseAmount * 100,
            Precision:   100,
            Reference:   purchaseReference,
            Currency:    "USD",
            Source:      mainWalletID,
            Destination: "@RevenueUSD",
            Description: "Product purchase",
            MetaData: map[string]interface{}{
                "transaction_type": "purchase",
            },
        },
    })
    if err != nil {
        return "", "", err
    }

    pointsAward, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: pointsToAward,
            Precision:   1,
            Reference:   "points-" + purchaseReference,
            Currency:    "POINTS",
            Source:      "@PointsPool",
            Destination: pointsWalletID,
            Description: "Loyalty points award",
            MetaData: map[string]interface{}{
                "purchase_reference": purchaseReference,
                "purchase_amount":    purchaseAmount,
            },
        },
        AllowOverdraft: true,
    })
    if err != nil {
        return "", "", err
    }

    fmt.Println("Purchase processed:", purchase.TransactionID)
    fmt.Println("Points awarded:", pointsAward.TransactionID)
    return purchase.TransactionID, pointsAward.TransactionID, nil
}

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:

They choose to use 200 points from their Points Wallet.
Those 200 points convert to $20 (at the 10 points = $1 rate)
Their final cost to pay from their Main Wallet would be $80 instead of $100.

Behind the scenes, here’s what we’ll do:

Take points from the Customer Points Wallet to @PointsPool.
Convert the points to its equivalent dollar value, apply it as discount, and calculate the final cost for the customer.
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
    }
  }'

async function redeemPointsForDiscount(mainWalletId, pointsWalletId, purchaseAmount, pointsToRedeem) {
  

  // Calculate points conversion to dollar: 10 points = 1 dollar
  const convertedAmount = pointsToRedeem / 10;
  
  // Generate a unique reference for this redemption
  const redemptionReference = `redemption-${Date.now()}`;
  
  // Step 1: Redeem points
  const pointsRedemption = await blnk.Transactions.create({
    precise_amount: pointsToRedeem,
    precision: 1,
    reference: redemptionReference,
    currency: "POINTS",
    source: pointsWalletId,
    destination: "@PointsPool",
    description: "Points redemption for discount",
    meta_data: {
      transaction_type: "redemption",
      convert_to_usd: convertedAmount
    }
  });
  
  // Step 2: Process the discounted purchase
  const discountedAmount = purchaseAmount - convertedAmount;
  
  const discountedPurchase = await blnk.Transactions.create({
    precise_amount: discountedAmount * 100,
    precision: 100,
    reference: `purchase-${redemptionReference}`,
    currency: "USD",
    source: mainWalletId,
    destination: "@RevenueUSD",
    description: "Discounted purchase with points",
    meta_data: {
      redemption_reference: redemptionReference,
      original_amount: purchaseAmount,
      points_redeemed: pointsToRedeem
    }
  });
  
  console.log("Points redeemed:", pointsRedemption.data.transaction_id);
  console.log("Discounted purchase processed:", discountedPurchase.data.transaction_id);
  
  return {
    redemptionId: pointsRedemption.data.transaction_id,
    purchaseId: discountedPurchase.data.transaction_id
  };
}

func redeemPointsForDiscount(mainWalletID, pointsWalletID string, purchaseAmount, pointsToRedeem float64) (redemptionID, purchaseID string, err error) {
    client := getClient()
    convertedAmount := pointsToRedeem / 10
    redemptionReference := fmt.Sprintf("redemption-%d", time.Now().Unix())

    pointsRedemption, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: pointsToRedeem,
            Precision:   1,
            Reference:   redemptionReference,
            Currency:    "POINTS",
            Source:      pointsWalletID,
            Destination: "@PointsPool",
            Description: "Points redemption for discount",
            MetaData: map[string]interface{}{
                "transaction_type": "redemption",
                "convert_to_usd":   convertedAmount,
            },
        },
    })
    if err != nil {
        return "", "", err
    }

    discountedAmount := purchaseAmount - convertedAmount
    discountedPurchase, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: discountedAmount * 100,
            Precision:   100,
            Reference:   "purchase-" + redemptionReference,
            Currency:    "USD",
            Source:      mainWalletID,
            Destination: "@RevenueUSD",
            Description: "Discounted purchase with points",
            MetaData: map[string]interface{}{
                "redemption_reference": redemptionReference,
                "original_amount":      purchaseAmount,
                "points_redeemed":      pointsToRedeem,
            },
        },
    })
    if err != nil {
        return "", "", err
    }

    fmt.Println("Points redeemed:", pointsRedemption.TransactionID)
    fmt.Println("Discounted purchase processed:", discountedPurchase.TransactionID)
    return pointsRedemption.TransactionID, discountedPurchase.TransactionID, nil
}

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.

​Designing your map

​Set up your implementation

​Prerequisites

​Create your ledgers

​Create balances for customer funds and loyalty points

​Awarding points after a purchase

​Redeeming points during a purchase

​Conclusion

Designing your map

Set up your implementation

Prerequisites

Create your ledgers

Create balances for customer funds and loyalty points

Awarding points after a purchase

Redeeming points during a purchase

Conclusion