POST
/
{locale}
/
shop
/
points
/
award
curl -X POST "https://staging-api.loyalty.lt/en/shop/points/award" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": 123,
    "points": 50,
    "transaction_type": "purchase",
    "purchase_amount": 25.99,
    "description": "Coffee shop purchase",
    "metadata": {
      "shop_id": 45,
      "order_id": "ORD-2024-001",
      "campaign_id": null
    }
  }'

{
  "success": true,
  "message": "Points awarded successfully",
  "data": {
    "transaction": {
      "id": 12345,
      "points_awarded": 50,
      "transaction_type": "purchase",
      "description": "Coffee shop purchase",
      "created_at": "2024-01-15T14:30:00Z"
    },
    "balance": {
      "current_points": 1300,
      "previous_points": 1250,
      "tier": "Gold",
      "tier_upgraded": false,
      "next_tier_points": 200
    }
  }
}

​
Award Points

Award loyalty points to a user’s loyalty card for purchases, activities, or promotional campaigns. This endpoint calculates points based on configurable rules and updates the user’s balance instantly.
Points are awarded in real-time and immediately available for redemption. The system automatically calculates tier progress and triggers tier upgrades when applicable.

​
Path Parameters

​
locale
string
required
Language code for localized content (e.g., “en”, “lt”)

​
Request Body

​
card_id
integer
required
Unique identifier of the loyalty card to award points to
​
points
integer
required
Number of points to award (must be positive)
​
transaction_type
string
required
Type of transaction that generated the points
  • purchase - Purchase-based points
  • bonus - Promotional bonus points
  • referral - Referral reward points
  • activity - Activity-based points (check-ins, reviews, etc.)
  • manual - Manual adjustment by staff
​
purchase_amount
number
Original purchase amount in euros (required for purchase transactions)
​
description
string
Optional description of the transaction (max 255 characters)
​
metadata
object
Additional transaction data for tracking and analytics

​
Response

​
success
boolean
Indicates if points were successfully awarded
​
message
string
Human-readable message about the operation
​
data
object
curl -X POST "https://staging-api.loyalty.lt/en/shop/points/award" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": 123,
    "points": 50,
    "transaction_type": "purchase",
    "purchase_amount": 25.99,
    "description": "Coffee shop purchase",
    "metadata": {
      "shop_id": 45,
      "order_id": "ORD-2024-001",
      "campaign_id": null
    }
  }'

{
  "success": true,
  "message": "Points awarded successfully",
  "data": {
    "transaction": {
      "id": 12345,
      "points_awarded": 50,
      "transaction_type": "purchase",
      "description": "Coffee shop purchase",
      "created_at": "2024-01-15T14:30:00Z"
    },
    "balance": {
      "current_points": 1300,
      "previous_points": 1250,
      "tier": "Gold",
      "tier_upgraded": false,
      "next_tier_points": 200
    }
  }
}

​
Points Calculation Rules

The system uses configurable rules to calculate points based on transaction type:

​
Business Logic

1

Validation

System validates card ownership, status, and point limits
2

Points Calculation

Applies tier multipliers and promotional bonuses
3

Balance Update

Updates card balance and transaction history
4

Tier Check

Evaluates tier progression and triggers upgrades
5

Notifications

Sends real-time notifications for tier upgrades

Redeem Points

Use points for purchases or rewards

Points Balance

Check current points balance and tier status

Transaction History

View detailed points transaction history

Loyalty Cards

Manage user’s loyalty cards
Rate Limits: Points awarding is limited to 100 transactions per minute per user to prevent abuse. Large batch operations should use the bulk endpoints.