Loyalty Cards API

The Loyalty Cards API allows you to create, manage, and track customer loyalty cards. This is the foundation of the loyalty program system, providing basic card operations for shops and stores.

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

Base URL

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

Core Concepts

Loyalty Cards

Card Numbers

Customer Linking

Status Management

Endpoints Overview

Create Card

POST /loyalty-cardsCreate a new loyalty card for a customer

Get Card

GET /loyalty-cards/{id}Retrieve card details and current balance

List Cards

GET /loyalty-cardsList all loyalty cards with filtering options

Update Card

PUT /loyalty-cards/{id}Update card information and settings

Block/Unblock

POST /loyalty-cards/{id}/blockBlock or unblock a loyalty card

Card History

GET /loyalty-cards/{id}/historyGet card transaction history

Create Loyalty Card

Create a new loyalty card for a customer. This is typically done when a customer first joins your loyalty program.

curl -X POST 'https://staging-api.loyalty.lt/api/loyalty-cards' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "initial_points": 100,
    "card_design": "default",
    "auto_activate": true
  }'

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "card_number": "LC001234567890",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "points_balance": 100,
    "status": "active",
    "card_design": "default",
    "created_at": "2024-12-27T10:30:00Z",
    "last_activity": "2024-12-27T10:30:00Z",
    "qr_code_url": "https://staging-api.loyalty.lt/qr/card_123456789",
    "metadata": {}
  }
}

Request Parameters

customer_email

string

required

Customer’s email address. Used for card identification and communication.

customer_name

string

required

Customer’s full name as it should appear on the card.

customer_phone

string

Customer’s phone number in international format (e.g., +1234567890).

initial_points

integer

default:"0"

Initial points to award to the card upon creation.

card_design

string

default:"default"

Card design template: default, premium, seasonal, or custom design ID.

auto_activate

boolean

default:"true"

Whether to automatically activate the card upon creation.

metadata

object

Additional custom data to store with the card (max 1KB).

Get Loyalty Card

Retrieve detailed information about a specific loyalty card, including current points balance and recent activity.

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

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "card_number": "LC001234567890",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "points_balance": 250,
    "lifetime_points": 350,
    "points_redeemed": 100,
    "status": "active",
    "card_design": "default",
    "tier": "bronze",
    "created_at": "2024-12-27T10:30:00Z",
    "last_activity": "2024-12-27T15:45:00Z",
    "qr_code_url": "https://staging-api.loyalty.lt/qr/card_123456789",
    "recent_transactions": [
      {
        "id": "txn_987654321",
        "type": "award",
        "points": 50,
        "reason": "Purchase reward",
        "created_at": "2024-12-27T15:45:00Z"
      }
    ],
    "metadata": {
      "signup_source": "website",
      "referral_code": "REF123"
    }
  }
}

Response Fields

string

Unique card identifier

card_number

string

Human-readable card number

points_balance

integer

Current available points balance

lifetime_points

integer

Total points ever earned on this card

points_redeemed

integer

Total points redeemed from this card

tier

string

Customer tier: bronze, silver, gold, platinum

recent_transactions

array

Last 5 point transactions (award/redeem)

List Loyalty Cards

Retrieve a paginated list of loyalty cards with optional filtering and sorting.

curl -X GET 'https://staging-api.loyalty.lt/api/loyalty-cards?status=active&page=1&limit=20&sort=created_at:desc' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

{
  "success": true,
  "data": {
    "cards": [
      {
        "id": "card_123456789",
        "card_number": "LC001234567890",
        "customer_email": "customer@example.com",
        "customer_name": "John Doe",
        "points_balance": 250,
        "status": "active",
        "created_at": "2024-12-27T10:30:00Z",
        "last_activity": "2024-12-27T15:45:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}

Query Parameters

status

string

Filter by card status: active, inactive, blocked, expired

customer_email

string

Filter by customer email (exact match)

tier

string

Filter by customer tier: bronze, silver, gold, platinum

created_after

string

Filter cards created after this date (ISO 8601 format)

created_before

string

Filter cards created before this date (ISO 8601 format)

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of items per page (max 100)

sort

string

default:"created_at:desc"

Sort order: created_at:desc, created_at:asc, points_balance:desc, points_balance:asc, last_activity:desc

Update Loyalty Card

Update card information such as customer details, status, or metadata.

curl -X PUT 'https://staging-api.loyalty.lt/api/loyalty-cards/card_123456789' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "customer_name": "John Smith",
    "customer_phone": "+1234567891",
    "card_design": "premium",
    "metadata": {
      "preferred_contact": "email",
      "birthday": "1990-01-15"
    }
  }'

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "card_number": "LC001234567890",
    "customer_email": "customer@example.com",
    "customer_name": "John Smith",
    "customer_phone": "+1234567891",
    "points_balance": 250,
    "status": "active",
    "card_design": "premium",
    "updated_at": "2024-12-27T16:00:00Z",
    "metadata": {
      "preferred_contact": "email",
      "birthday": "1990-01-15"
    }
  }
}

Updatable Fields

customer_name

string

Update customer’s display name

customer_phone

string

Update customer’s phone number

card_design

string

Change card design template

metadata

object

Update custom metadata (replaces existing metadata)

Customer email cannot be updated once set. Card status should be changed using the block/unblock endpoints.

Block/Unblock Card

Block or unblock a loyalty card. Blocked cards cannot earn or redeem points.

curl -X POST 'https://staging-api.loyalty.lt/api/loyalty-cards/card_123456789/block' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "reason": "Suspicious activity detected",
    "internal_note": "Customer reported unauthorized transactions"
  }'

{
  "success": true,
  "data": {
    "id": "card_123456789",
    "status": "blocked",
    "reason": "Suspicious activity detected",
    "blocked_at": "2024-12-27T16:15:00Z",
    "can_earn_points": false,
    "can_redeem_points": false
  }
}

Request Parameters

reason

string

required

Reason for blocking/unblocking the card (shown to customer)

internal_note

string

Internal note for staff reference (not shown to customer)

Card Transaction History

Retrieve detailed transaction history for a loyalty card, including points awarded, redeemed, and expired.

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

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_987654321",
        "type": "award",
        "points": 50,
        "reason": "Purchase reward",
        "reference": "order_123456",
        "created_at": "2024-12-27T15:45:00Z",
        "staff_member": null,
        "metadata": {
          "order_total": 25.00,
          "currency": "USD"
        }
      },
      {
        "id": "txn_987654320",
        "type": "redeem",
        "points": -25,
        "reason": "Discount redemption",
        "reference": "discount_789",
        "created_at": "2024-12-27T14:30:00Z",
        "staff_member": "staff_001",
        "metadata": {
          "discount_amount": 5.00,
          "currency": "USD"
        }
      }
    ],
    "summary": {
      "total_awarded": 350,
      "total_redeemed": 100,
      "current_balance": 250,
      "transaction_count": 25
    },
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 25,
      "total_pages": 1,
      "has_next": false,
      "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)

page

integer

default:"1"

Page number for pagination

limit

integer

default:"50"

Number of transactions per page (max 100)

Error Handling

Card Not Found

Invalid Customer Email

Duplicate Customer

Status Code: 409

{
  "success": false,
  "error": {
    "code": "DUPLICATE_CUSTOMER",
    "message": "A loyalty card already exists for this customer",
    "existing_card_id": "card_987654321"
  }
}

Card Blocked

Best Practices

Customer Identification

Use email as primary identifier
Store phone numbers for backup identification
Implement duplicate detection logic
Validate customer data before card creation

Card Management

Set appropriate initial points for new signups
Use meaningful card designs for branding
Implement card blocking for security
Regularly audit inactive cards

Data Management

Use metadata for custom tracking
Implement proper pagination for large lists
Filter by relevant criteria for performance
Cache frequently accessed card data

Security

Validate all input parameters
Implement rate limiting for card creation
Log all card status changes
Monitor for suspicious patterns

Integration Examples

E-commerce Integration

Point-of-Sale Integration

Mobile App Integration

Next Steps

Points Management

Learn how to award and redeem points on loyalty cards.

Offers API

Create and manage promotional offers for loyalty card holders.

Games API

Add gamification features to your loyalty program.

SDK Integration

Use our SDKs for easier integration with built-in utilities.

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

​Loyalty Cards API

​Base URL

​Core Concepts

​Endpoints Overview

Create Card

Get Card

List Cards

Update Card

Block/Unblock

Card History

​Create Loyalty Card

​Request Parameters

​Get Loyalty Card

​Response Fields

​List Loyalty Cards

​Query Parameters

​Update Loyalty Card

​Updatable Fields

​Block/Unblock Card

​Request Parameters

​Card Transaction History

​Query Parameters

​Error Handling

​Best Practices

Customer Identification

Card Management

Data Management

Security

​Integration Examples

​Next Steps

Points Management

Offers API

Games API

SDK Integration

Loyalty Cards API

Base URL

Core Concepts

Endpoints Overview

Create Loyalty Card

Request Parameters

Get Loyalty Card

Response Fields

List Loyalty Cards

Query Parameters

Update Loyalty Card

Updatable Fields

Block/Unblock Card

Request Parameters

Card Transaction History

Query Parameters

Error Handling

Best Practices

Integration Examples

Next Steps