Points Management API

The Points Management API is the core of the loyalty program system, allowing you to award points to customers, process redemptions, and track point transactions. This API works directly with loyalty cards to manage customer rewards.

All Shop API endpoints require API Key and Secret authentication. See Authentication Overview for details.

Base URL

https://staging-api.loyalty.lt/api/points

Core Concepts

Points Transactions

Every point operation creates a transaction record with a unique ID, timestamp, and reason. This provides a complete audit trail of all point activities.

Point Types

Award: Add points to a customer’s balance
Redeem: Subtract points from balance (for rewards)
Expire: Remove expired points automatically
Adjust: Manual corrections (positive or negative)

Transaction References

Link point transactions to external systems using reference IDs (order numbers, invoice IDs, etc.) for better tracking and reconciliation.

Point Expiration

Points can have expiration dates. Expired points are automatically removed from customer balances and tracked separately.

Endpoints Overview

Award Points

POST /points/awardAdd points to a customer’s loyalty card

Redeem Points

POST /points/redeemSubtract points from a customer’s balance

Points History

GET /points/history/{card_id}Get detailed transaction history for a card

Points Balance

GET /points/balance/{card_id}Get current points balance and details

Bulk Operations

POST /points/bulkProcess multiple point transactions at once

Expire Points

POST /points/expireManually expire points by date or amount

Award Points

Award points to a customer’s loyalty card. This is typically done after a purchase, completed action, or as a bonus reward.

curl -X POST 'https://staging-api.loyalty.lt/api/points/award' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "card_id": "card_123456789",
    "points": 100,
    "reason": "Purchase reward",
    "reference": "order_12345",
    "metadata": {
      "order_total": 50.00,
      "currency": "USD",
      "store_location": "Main Street"
    }
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_987654321",
    "card_id": "card_123456789",
    "type": "award",
    "points": 100,
    "reason": "Purchase reward",
    "reference": "order_12345",
    "previous_balance": 150,
    "new_balance": 250,
    "created_at": "2024-12-27T15:45:00Z",
    "expires_at": "2025-12-27T15:45:00Z",
    "staff_member": null,
    "metadata": {
      "order_total": 50.00,
      "currency": "USD",
      "store_location": "Main Street"
    }
  }
}

Request Parameters

card_id

string

required

The loyalty card ID to award points to

points

integer

required

Number of points to award (must be positive)

reason

string

required

Description of why points were awarded (shown to customer)

reference

string

External reference ID (order number, invoice ID, etc.)

expires_at

string

Point expiration date in ISO 8601 format. If not provided, uses default expiration policy.

staff_member

string

ID or name of staff member who awarded the points

metadata

object

Additional data to store with the transaction (max 1KB)

Redeem Points

Redeem points from a customer’s loyalty card balance. This reduces their available points in exchange for rewards, discounts, or other benefits.

curl -X POST 'https://staging-api.loyalty.lt/api/points/redeem' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "card_id": "card_123456789",
    "points": 50,
    "reason": "Discount redemption",
    "reference": "discount_789",
    "metadata": {
      "discount_amount": 10.00,
      "currency": "USD",
      "discount_type": "percentage"
    }
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_987654322",
    "card_id": "card_123456789",
    "type": "redeem",
    "points": -50,
    "reason": "Discount redemption",
    "reference": "discount_789",
    "previous_balance": 250,
    "new_balance": 200,
    "created_at": "2024-12-27T16:00:00Z",
    "staff_member": "staff_001",
    "metadata": {
      "discount_amount": 10.00,
      "currency": "USD",
      "discount_type": "percentage"
    }
  }
}

Request Parameters

card_id

string

required

The loyalty card ID to redeem points from

points

integer

required

Number of points to redeem (must be positive, will be subtracted from balance)

reason

string

required

Description of what the points were redeemed for

reference

string

External reference ID for the redemption

staff_member

string

ID or name of staff member who processed the redemption

metadata

object

Additional data about the redemption (discount amount, item details, etc.)

Get Points Balance

Retrieve the current points balance and related information for a loyalty card.

curl -X GET 'https://staging-api.loyalty.lt/api/points/balance/card_123456789' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

{
  "success": true,
  "data": {
    "card_id": "card_123456789",
    "current_balance": 200,
    "lifetime_earned": 500,
    "lifetime_redeemed": 300,
    "points_expiring_soon": [
      {
        "points": 25,
        "expires_at": "2024-01-15T00:00:00Z",
        "days_until_expiry": 19
      }
    ],
    "last_activity": {
      "transaction_id": "txn_987654322",
      "type": "redeem",
      "points": -50,
      "created_at": "2024-12-27T16:00:00Z"
    },
    "tier_info": {
      "current_tier": "silver",
      "points_to_next_tier": 300,
      "next_tier": "gold"
    }
  }
}

Response Fields

current_balance

integer

Available points that can be redeemed

lifetime_earned

integer

Total points ever earned on this card

lifetime_redeemed

integer

Total points ever redeemed from this card

points_expiring_soon

array

Points that will expire within the next 30 days

tier_info

object

Customer tier status and progression information

Points Transaction History

Get detailed transaction history for a loyalty card with filtering and pagination options.

curl -X GET 'https://staging-api.loyalty.lt/api/points/history/card_123456789?type=all&from_date=2024-01-01&page=1&limit=20' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_987654322",
        "type": "redeem",
        "points": -50,
        "reason": "Discount redemption",
        "reference": "discount_789",
        "balance_before": 250,
        "balance_after": 200,
        "created_at": "2024-12-27T16:00:00Z",
        "expires_at": null,
        "staff_member": "staff_001",
        "metadata": {
          "discount_amount": 10.00,
          "currency": "USD"
        }
      },
      {
        "id": "txn_987654321",
        "type": "award",
        "points": 100,
        "reason": "Purchase reward",
        "reference": "order_12345",
        "balance_before": 150,
        "balance_after": 250,
        "created_at": "2024-12-27T15:45:00Z",
        "expires_at": "2025-12-27T15:45:00Z",
        "staff_member": null,
        "metadata": {
          "order_total": 50.00,
          "currency": "USD"
        }
      }
    ],
    "summary": {
      "total_transactions": 25,
      "points_awarded": 500,
      "points_redeemed": 300,
      "points_expired": 0,
      "current_balance": 200
    },
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 25,
      "total_pages": 2,
      "has_next": true,
      "has_prev": false
    }
  }
}

Query Parameters

type

string

default:"all"

Filter by transaction type: all, award, redeem, expire, adjust

from_date

string

Start date for transaction history (ISO 8601 format)

to_date

string

End date for transaction history (ISO 8601 format)

reference

string

Filter by external reference ID

staff_member

string

Filter by staff member who processed the transaction

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of transactions per page (max 100)

Bulk Point Operations

Process multiple point transactions in a single request for efficiency. Useful for batch imports or bulk operations.

curl -X POST 'https://staging-api.loyalty.lt/api/points/bulk' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "transactions": [
      {
        "card_id": "card_123456789",
        "type": "award",
        "points": 50,
        "reason": "Birthday bonus",
        "reference": "birthday_2024"
      },
      {
        "card_id": "card_987654321",
        "type": "award",
        "points": 100,
        "reason": "Referral bonus",
        "reference": "referral_456"
      },
      {
        "card_id": "card_555666777",
        "type": "redeem",
        "points": 25,
        "reason": "Loyalty reward",
        "reference": "reward_789"
      }
    ]
  }'

{
  "success": true,
  "data": {
    "processed": 3,
    "successful": 2,
    "failed": 1,
    "results": [
      {
        "card_id": "card_123456789",
        "status": "success",
        "transaction_id": "txn_111222333",
        "new_balance": 275
      },
      {
        "card_id": "card_987654321",
        "status": "success",
        "transaction_id": "txn_444555666",
        "new_balance": 350
      },
      {
        "card_id": "card_555666777",
        "status": "failed",
        "error": {
          "code": "INSUFFICIENT_POINTS",
          "message": "Not enough points for redemption"
        }
      }
    ],
    "processing_time": "0.245s"
  }
}

Bulk Transaction Object

card_id

string

required

The loyalty card ID for this transaction

type

string

required

Transaction type: award, redeem, or adjust

points

integer

required

Number of points (positive for award, positive for redeem amount)

reason

string

required

Description of the transaction

reference

string

External reference ID

metadata

object

Additional transaction data

Point Expiration

Manually expire points or check which points are due for expiration.

Expire Points
Check Expiring Points

curl -X POST 'https://staging-api.loyalty.lt/api/points/expire' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "card_id": "card_123456789",
    "points": 25,
    "reason": "Points expired after 12 months",
    "expires_before": "2024-01-01T00:00:00Z"
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_expire_123",
    "card_id": "card_123456789",
    "points_expired": 25,
    "previous_balance": 200,
    "new_balance": 175,
    "reason": "Points expired after 12 months",
    "expired_at": "2024-12-27T16:30:00Z"
  }
}

Points Adjustment

Make manual adjustments to point balances for corrections, compensations, or administrative purposes.

curl -X POST 'https://staging-api.loyalty.lt/api/points/adjust' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "card_id": "card_123456789",
    "points": -10,
    "reason": "Correction for duplicate transaction",
    "reference": "adjustment_001",
    "staff_member": "admin_user",
    "metadata": {
      "original_transaction": "txn_987654321",
      "correction_type": "duplicate_removal"
    }
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_adjust_456",
    "card_id": "card_123456789",
    "type": "adjust",
    "points": -10,
    "reason": "Correction for duplicate transaction",
    "reference": "adjustment_001",
    "previous_balance": 175,
    "new_balance": 165,
    "created_at": "2024-12-27T16:45:00Z",
    "staff_member": "admin_user",
    "metadata": {
      "original_transaction": "txn_987654321",
      "correction_type": "duplicate_removal"
    }
  }
}

Error Handling

Insufficient Points

Status Code: 400

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Not enough points for redemption",
    "current_balance": 25,
    "requested_points": 50
  }
}

Card Blocked

Status Code: 403

{
  "success": false,
  "error": {
    "code": "CARD_BLOCKED",
    "message": "Cannot process points for blocked card",
    "card_id": "card_123456789"
  }
}

Invalid Points Amount

Status Code: 400

{
  "success": false,
  "error": {
    "code": "INVALID_POINTS",
    "message": "Points amount must be positive",
    "provided_value": -5
  }
}

Transaction Limit Exceeded

Status Code: 429

{
  "success": false,
  "error": {
    "code": "TRANSACTION_LIMIT_EXCEEDED",
    "message": "Too many point transactions in short period",
    "retry_after": 60
  }
}

Best Practices

Transaction References

Always use external reference IDs
Link to order numbers, invoice IDs
Enable easy reconciliation
Support customer service inquiries

Reason Descriptions

Use customer-friendly language
Be specific about the action
Avoid technical jargon
Support multiple languages if needed

Metadata Usage

Store relevant transaction context
Include monetary amounts and currency
Track staff members for auditing
Add custom business data

Error Handling

Check balances before redemption
Validate card status first
Implement retry logic for failures
Log all transactions for auditing

Integration Patterns

E-commerce Purchase Flow

Scenario: Award points after successful order completion

Customer completes checkout
Payment is processed successfully
Calculate points based on order total
Award points with order reference
Send confirmation email with points earned
Update customer’s loyalty dashboard

Point-of-Sale Redemption

Scenario: Customer redeems points for discount at checkout

Scan customer loyalty card
Check current points balance
Customer selects reward to redeem
Validate sufficient points available
Process point redemption
Apply discount to transaction
Print receipt with new balance

Bulk Point Award Campaign

Scenario: Award bonus points to all customers

Export list of active loyalty cards
Prepare bulk transaction data
Submit bulk award request
Process results and handle failures
Send notification emails to customers
Generate campaign performance report

Point Calculation Examples

Purchase-based Points
Tier-based Multipliers
Redemption Values

// Award 1 point per $1 spent
const orderTotal = 25.50;
const pointsToAward = Math.floor(orderTotal);

await awardPoints({
  card_id: 'card_123',
  points: pointsToAward, // 25 points
  reason: `Purchase reward for $${orderTotal}`,
  reference: order.id,
  metadata: {
    order_total: orderTotal,
    currency: 'USD',
    points_rate: '1 point per $1'
  }
});

Analytics and Reporting

Use the transaction history and balance APIs to generate insights about your loyalty program performance.

Key Metrics to Track

Point Velocity

Average points earned per customer
Time between earning and redemption
Seasonal earning patterns
Popular redemption categories

Program Health

Point liability (unredeemed points)
Expiration rates and amounts
Customer engagement levels
Transaction frequency trends

Customer Behavior

Earning vs. redemption ratios
Tier progression rates
Preferred redemption amounts
Inactive customer identification

Financial Impact

Point redemption costs
Customer lifetime value increase
Program ROI calculation
Revenue attribution to loyalty

Next Steps

Offers API

Create promotional offers that customers can redeem with points.

Games API

Add gamification features to make earning points more engaging.

Loyalty Cards API

Learn how to create and manage customer loyalty cards.

SDK Integration

Use our JavaScript SDK for easier points management integration.

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

​Points Management API

​Base URL

​Core Concepts

​Endpoints Overview

Award Points

Redeem Points

Points History

Points Balance

Bulk Operations

Expire Points

​Award Points

​Request Parameters

​Redeem Points

​Request Parameters

​Get Points Balance

​Response Fields

​Points Transaction History

​Query Parameters

​Bulk Point Operations

​Bulk Transaction Object

​Point Expiration

​Points Adjustment

​Error Handling

​Best Practices

Transaction References

Reason Descriptions

Metadata Usage

Error Handling

​Integration Patterns

​Point Calculation Examples

​Analytics and Reporting

​Key Metrics to Track

Point Velocity

Program Health

Customer Behavior

Financial Impact

​Next Steps

Offers API

Games API

Loyalty Cards API

SDK Integration

Points Management API

Base URL

Core Concepts

Endpoints Overview

Award Points

Request Parameters

Redeem Points

Request Parameters

Get Points Balance

Response Fields

Points Transaction History

Query Parameters

Bulk Point Operations

Bulk Transaction Object

Point Expiration

Points Adjustment

Error Handling

Best Practices

Integration Patterns

Point Calculation Examples

Analytics and Reporting

Key Metrics to Track

Next Steps