Skip to main content

Loyalty API

Complete API reference for loyalty points, rewards, and tier management.

Base Endpoints​

/api/v1/customers/{customer_id}/points
/api/v1/rewards
/api/v1/tiers

Points Operations​

Award Points​

Award points to a customer.

POST /api/v1/customers/{customer_id}/points/award

Request Body​

{
  "points": 100,
  "reason": "Purchase bonus",
  "transaction_id": "txn_12345",
  "metadata": {
    "store": "Store A",
    "category": "fashion"
  }
}

Example Response​

{
  "data": {
    "id": "ptx_12345",
    "customer_id": "cus_12345",
    "points": 100,
    "type": "earned",
    "reason": "Purchase bonus",
    "balance_after": 5100,
    "created_at": "2024-01-20T15:00:00Z"
  }
}

Redeem Points​

Redeem points for a reward.

POST /api/v1/customers/{customer_id}/points/redeem

Request Body​

{
  "reward_id": "rew_12345",
  "quantity": 1
}

Get Points History​

Get customer points transaction history.

GET /api/v1/customers/{customer_id}/points/history

Query Parameters​

ParameterTypeDescription
typestringFilter by type (earned, redeemed, expired)
date_fromstringFilter from date
date_tostringFilter to date
pageintegerPage number
limitintegerItems per page

Example Response​

{
  "data": [
    {
      "id": "ptx_123",
      "points": 100,
      "type": "earned",
      "reason": "Purchase bonus",
      "balance_after": 5100,
      "created_at": "2024-01-20T15:00:00Z"
    },
    {
      "id": "ptx_456",
      "points": -50,
      "type": "redeemed",
      "reason": "Reward redemption",
      "balance_after": 5050,
      "created_at": "2024-01-19T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Get Points Balance​

Get current points balance for a customer.

GET /api/v1/customers/{customer_id}/points/balance

Example Response​

{
  "data": {
    "customer_id": "cus_12345",
    "balance": 5000,
    "lifetime_earned": 15000,
    "lifetime_redeemed": 10000,
    "pending_expiration": {
      "points": 200,
      "expires_at": "2024-02-01T00:00:00Z"
    }
  }
}

Rewards API​

List Rewards​

Get available rewards.

GET /api/v1/rewards

Query Parameters​

ParameterTypeDescription
categorystringFilter by category
tierstringFilter by required tier
points_minintegerMinimum points required
points_maxintegerMaximum points required
availablebooleanOnly available rewards

Example Response​

{
  "data": [
    {
      "id": "rew_123",
      "name": "10% Discount Voucher",
      "description": "Get 10% off your next purchase",
      "category": "voucher",
      "points_required": 500,
      "tier_required": "bronze",
      "image": "https://...",
      "available": true,
      "stock": 1000
    }
  ]
}

Get Reward​

Get reward details.

GET /api/v1/rewards/{reward_id}

Claim Reward​

Claim a reward for a customer.

POST /api/v1/customers/{customer_id}/rewards/claim

Request Body​

{
  "reward_id": "rew_12345",
  "quantity": 1
}

Example Response​

{
  "data": {
    "id": "clm_123",
    "customer_id": "cus_12345",
    "reward_id": "rew_12345",
    "voucher_code": "VOUCHER-ABC123",
    "qr_code": "https://...",
    "status": "available",
    "expires_at": "2024-02-20T23:59:59Z",
    "created_at": "2024-01-20T15:00:00Z"
  }
}

Get Customer Rewards​

Get all rewards claimed by a customer.

GET /api/v1/customers/{customer_id}/rewards

Query Parameters​

ParameterTypeDescription
statusstringFilter by status (available, used, expired)

Tier Management​

List Tiers​

Get all membership tiers.

GET /api/v1/tiers

Example Response​

{
  "data": [
    {
      "id": "tier_bronze",
      "name": "Bronze",
      "level": 1,
      "points_threshold": 0,
      "benefits": [
        "Basic rewards access",
        "Birthday bonus"
      ]
    },
    {
      "id": "tier_gold",
      "name": "Gold",
      "level": 3,
      "points_threshold": 5000,
      "benefits": [
        "Exclusive rewards",
        "2X points multiplier",
        "Priority support"
      ]
    }
  ]
}

Get Tier​

Get tier details.

GET /api/v1/tiers/{tier_id}

Update Customer Tier​

Manually update customer tier.

PATCH /api/v1/customers/{customer_id}/tier

Request Body​

{
  "tier_id": "tier_gold",
  "reason": "Manual upgrade"
}

Batch Operations​

Batch Award Points​

Award points to multiple customers.

POST /api/v1/points/batch-award

Request Body​

{
  "awards": [
    {
      "customer_id": "cus_123",
      "points": 100,
      "reason": "Campaign bonus"
    },
    {
      "customer_id": "cus_456",
      "points": 150,
      "reason": "Campaign bonus"
    }
  ]
}

Example Response​

{
  "data": {
    "processed": 2,
    "failed": 0,
    "results": [
      {
        "customer_id": "cus_123",
        "success": true,
        "transaction_id": "ptx_789"
      },
      {
        "customer_id": "cus_456",
        "success": true,
        "transaction_id": "ptx_790"
      }
    ]
  }
}