Skip to main content
GET
/
{locale}
/
shop
/
offers
curl -X GET "https://staging-api.loyalty.lt/en/shop/offers?category=discount&tier=gold&page=1&per_page=10" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json"

{
  "success": true,
  "message": "Offers retrieved successfully",
  "data": {
    "data": [
      {
        "id": 101,
        "title": "20% Off Your Next Purchase",
        "description": "Get 20% discount on your next purchase of €25 or more",
        "category": "discount",
        "offer_type": "percentage_discount",
        "value": 20,
        "points_required": 200,
        "minimum_tier": "silver",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": 1,
          "max_uses_total": 1000,
          "uses_remaining": 847,
          "user_uses_count": 0
        },
        "validity": {
          "starts_at": "2024-01-01T00:00:00Z",
          "expires_at": "2024-03-31T23:59:59Z",
          "days_remaining": 75,
          "is_active": true
        },
        "terms_conditions": "Valid on purchases of €25 or more. Cannot be combined with other offers.",
        "image_url": "https://api.loyalty.lt/storage/offers/discount-20.jpg",
        "is_featured": true,
        "is_claimable": true,
        "claim_reason": null
      },
      {
        "id": 102,
        "title": "Free Pastry with Coffee",
        "description": "Get a free pastry when you buy any large coffee",
        "category": "freebie",
        "offer_type": "free_product",
        "value": 3.50,
        "points_required": 150,
        "minimum_tier": "bronze",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": 3,
          "max_uses_total": 500,
          "uses_remaining": 312,
          "user_uses_count": 1
        },
        "validity": {
          "starts_at": "2024-01-15T00:00:00Z",
          "expires_at": "2024-02-15T23:59:59Z",
          "days_remaining": 31,
          "is_active": true
        },
        "terms_conditions": "Valid with purchase of large coffee. One free pastry per visit.",
        "image_url": "https://api.loyalty.lt/storage/offers/free-pastry.jpg",
        "is_featured": false,
        "is_claimable": true,
        "claim_reason": null
      },
      {
        "id": 103,
        "title": "Platinum VIP Access",
        "description": "Exclusive access to premium coffee blends and private tasting events",
        "category": "exclusive",
        "offer_type": "vip_access",
        "value": 0,
        "points_required": 0,
        "minimum_tier": "platinum",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": null,
          "max_uses_total": null,
          "uses_remaining": null,
          "user_uses_count": 0
        },
        "validity": {
          "starts_at": "2024-01-01T00:00:00Z",
          "expires_at": null,
          "days_remaining": null,
          "is_active": true
        },
        "terms_conditions": "Available exclusively for Platinum tier members.",
        "image_url": "https://api.loyalty.lt/storage/offers/vip-access.jpg",
        "is_featured": true,
        "is_claimable": false,
        "claim_reason": "Requires Platinum tier status"
      }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 23,
    "last_page": 2,
    "categories": [
      {
        "category": "discount",
        "count": 8,
        "display_name": "Discounts"
      },
      {
        "category": "freebie",
        "count": 12,
        "display_name": "Free Items"
      },
      {
        "category": "exclusive",
        "count": 3,
        "display_name": "Exclusive Offers"
      }
    ]
  }
}

​
List Available Offers

Retrieve a comprehensive list of available offers, promotions, and deals that users can claim or redeem with their loyalty points. This endpoint provides detailed offer information with filtering and pagination options.
Offers are returned based on user eligibility, tier status, and availability. Only active offers within their validity period are included.

​
Path Parameters

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

​
Query Parameters

​
page
integer
Page number for pagination (default: 1)
​
per_page
integer
Number of items per page (default: 15, max: 50)
​
category
string
Filter by offer category
  • discount - Percentage or fixed amount discounts
  • freebie - Free products or services
  • cashback - Cash back offers
  • exclusive - Tier-exclusive offers
  • seasonal - Limited-time seasonal offers
​
tier
string
Filter by minimum tier requirement
  • bronze - Available for Bronze tier and above
  • silver - Available for Silver tier and above
  • gold - Available for Gold tier and above
  • platinum - Platinum tier exclusive
​
points_min
integer
Minimum points required to claim offer
​
points_max
integer
Maximum points required to claim offer
​
shop_id
integer
Filter offers for a specific shop
​
featured
boolean
Show only featured offers (true/false)

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Human-readable message about the operation
​
data
object
curl -X GET "https://staging-api.loyalty.lt/en/shop/offers?category=discount&tier=gold&page=1&per_page=10" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json"

{
  "success": true,
  "message": "Offers retrieved successfully",
  "data": {
    "data": [
      {
        "id": 101,
        "title": "20% Off Your Next Purchase",
        "description": "Get 20% discount on your next purchase of €25 or more",
        "category": "discount",
        "offer_type": "percentage_discount",
        "value": 20,
        "points_required": 200,
        "minimum_tier": "silver",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": 1,
          "max_uses_total": 1000,
          "uses_remaining": 847,
          "user_uses_count": 0
        },
        "validity": {
          "starts_at": "2024-01-01T00:00:00Z",
          "expires_at": "2024-03-31T23:59:59Z",
          "days_remaining": 75,
          "is_active": true
        },
        "terms_conditions": "Valid on purchases of €25 or more. Cannot be combined with other offers.",
        "image_url": "https://api.loyalty.lt/storage/offers/discount-20.jpg",
        "is_featured": true,
        "is_claimable": true,
        "claim_reason": null
      },
      {
        "id": 102,
        "title": "Free Pastry with Coffee",
        "description": "Get a free pastry when you buy any large coffee",
        "category": "freebie",
        "offer_type": "free_product",
        "value": 3.50,
        "points_required": 150,
        "minimum_tier": "bronze",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": 3,
          "max_uses_total": 500,
          "uses_remaining": 312,
          "user_uses_count": 1
        },
        "validity": {
          "starts_at": "2024-01-15T00:00:00Z",
          "expires_at": "2024-02-15T23:59:59Z",
          "days_remaining": 31,
          "is_active": true
        },
        "terms_conditions": "Valid with purchase of large coffee. One free pastry per visit.",
        "image_url": "https://api.loyalty.lt/storage/offers/free-pastry.jpg",
        "is_featured": false,
        "is_claimable": true,
        "claim_reason": null
      },
      {
        "id": 103,
        "title": "Platinum VIP Access",
        "description": "Exclusive access to premium coffee blends and private tasting events",
        "category": "exclusive",
        "offer_type": "vip_access",
        "value": 0,
        "points_required": 0,
        "minimum_tier": "platinum",
        "shop": {
          "id": 45,
          "name": "Coffee Paradise",
          "logo_url": "https://api.loyalty.lt/storage/logos/coffee-paradise.png"
        },
        "usage_limits": {
          "max_uses_per_user": null,
          "max_uses_total": null,
          "uses_remaining": null,
          "user_uses_count": 0
        },
        "validity": {
          "starts_at": "2024-01-01T00:00:00Z",
          "expires_at": null,
          "days_remaining": null,
          "is_active": true
        },
        "terms_conditions": "Available exclusively for Platinum tier members.",
        "image_url": "https://api.loyalty.lt/storage/offers/vip-access.jpg",
        "is_featured": true,
        "is_claimable": false,
        "claim_reason": "Requires Platinum tier status"
      }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 23,
    "last_page": 2,
    "categories": [
      {
        "category": "discount",
        "count": 8,
        "display_name": "Discounts"
      },
      {
        "category": "freebie",
        "count": 12,
        "display_name": "Free Items"
      },
      {
        "category": "exclusive",
        "count": 3,
        "display_name": "Exclusive Offers"
      }
    ]
  }
}

​
Offer Categories

Different types of offers provide various benefits to loyalty program members:
  • Discounts
  • Free Items
  • Cashback
  • Exclusive
Percentage & Fixed Discounts
  • Percentage off total purchase (5%-50%)
  • Fixed amount discounts (€1-€20)
  • Category-specific discounts
  • Minimum purchase requirements
Common Points Range: 50-500 points

​
Claiming Eligibility

Several factors determine whether a user can claim an offer:
Minimum Tier Status
  • Bronze: Basic offers available
  • Silver: Enhanced offers + Bronze
  • Gold: Premium offers + Silver + Bronze
  • Platinum: All offers including exclusives
Sufficient Points
  • User must have required points available
  • Points are reserved during claim process
  • Failed claims release reserved points
Personal & Global Limits
  • Per-user maximum uses
  • Total offer availability
  • Cooldown periods between uses
  • One-time only offers
Time-Based Availability
  • Offer must be within validity dates
  • Some offers have time-of-day restrictions
  • Seasonal or event-based availability

​
Advanced Filtering

​
Smart Filtering Examples

// Get affordable offers for current points balance
const userBalance = 350;
const affordableOffers = await fetch(`/en/shop/offers?points_max=${userBalance}`);

// Find tier-appropriate offers
const userTier = 'gold';
const tierOffers = await fetch(`/en/shop/offers?tier=${userTier}`);

// Discover featured freebies
const featuredFreebies = await fetch('/en/shop/offers?category=freebie&featured=true');

​
Dynamic Category Discovery

// Get category distribution
const response = await fetch('/en/shop/offers');
const categories = response.data.categories;

// Display category options with counts
categories.forEach(cat => {
  console.log(`${cat.display_name}: ${cat.count} offers`);
});

​
User Experience Tips

Personalization: The is_claimable field and claim_reason provide clear feedback about offer eligibility, enabling personalized user experiences.
  • Badge System: Show tier requirements with colored badges
  • Countdown Timers: Display days_remaining for expiring offers
  • Progress Indicators: Show points needed vs. user balance
  • Category Filters: Use the categories array for filter options

​
Accessibility Considerations

  • Clear eligibility messaging in claim_reason
  • Visual indicators for claimable vs. non-claimable offers
  • Expiration warnings for time-sensitive offers

Claim Offer

Claim an available offer

Featured Offers

Get highlighted promotional offers

Points Balance

Check available points for claiming

User Profile

View tier status and eligibility
Real-time Updates: Offer availability and claimability status are calculated in real-time based on current user status, points balance, and usage history.