Skip to content
👥 Storefront APIs
/
/
Get customer referral his...

Storefront APIs

Download OpenAPI description
storefront-api-swagger.json
storefront-api-swagger.yaml
Languages
Servers
https://loyalty-admin.appstle.com

Storefront APIs

Customer-facing loyalty program APIs for storefront operations. These endpoints allow customers to manage their loyalty account, earn and redeem points, submit reviews, handle referrals, and track their rewards. All endpoints require customer authentication via JWT token.

Operations

Get logged-in customer ID

Request

Retrieves the customer ID of the currently authenticated user. This endpoint is useful for obtaining the customer ID after authentication to use in other API calls.

curl -i -X GET \
  https://loyalty-admin.appstle.com/loyalty/cp/api/logged-in-customer

Responses

Customer ID retrieved successfully

Bodyapplication/json
integer(int64)
Response
application/json
12345

Get customer referral history

Request

Retrieves paginated list of referrals made by the authenticated customer. Each entry includes the referred email, referral status (PENDING, COMPLETED, EXPIRED), associated points earned, and timestamps. Useful for displaying referral tracking dashboards.

Query
pageableobject(Pageable)required

Pagination parameters (page number, size, sort)

pageable.​pageinteger(int32)>= 0
pageable.​sizeinteger(int32)>= 1
pageable.​sortArray of strings
curl -i -X GET \
  'https://loyalty-admin.appstle.com/loyalty/cp/api/customer-referrals?page=0&size=1&sort=string'

Responses

Customer referrals retrieved successfully with pagination headers (X-Total-Count, Link)

Bodyapplication/json
idinteger(int64)
shopstringrequired
customerIdinteger(int64)required
referredEmailIdstringrequired
descriptionstring
referralRuleIdinteger(int64)
claimAtstring(date-time)
statusstringrequired
Enum"PENDING""CLAIMED""RECURRING"
createAtstring(date-time)required
referralRewardedboolean
referredRewardedboolean
referralNotestring
referredNotestring
pixelDatastring
Response
application/json
[
  {
    "id": 12345,
    "shop": "example-store.myshopify.com",
    "customerId": 67890,
    "referredEmailId": "friend@example.com",
    "description": "Referred friend via email",
    "referralRuleId": 1,
    "status": "PENDING",
    "createAt": "2025-01-15T10:30:00Z"
  }
]

Get customer loyalty information

Request

Retrieves comprehensive loyalty information for the currently authenticated customer.

Primary use case: This is the main endpoint for displaying a customer's loyalty dashboard. Call this endpoint when a customer views their loyalty page to show all their points, rewards, and program status.

What you'll get:

  • Current point balances (available, pending, total credited)
  • Store credit balance (if applicable)
  • VIP tier information and expiration
  • List of rewards/discount codes
  • Social media engagement tracking
  • Referral statistics and link
  • Account creation date
  • Customer status in loyalty program

Authentication: Requires JWT token for the customer. The token identifies which customer's data to retrieve. Customer must be authenticated via Shopify customer login.

Filtering rewards by status: Use the optional 'status' query parameter to filter rewards:

  • UNUSED: Show only unused discount codes
  • USED: Show only used/redeemed codes
  • EXPIRED: Show only expired codes
  • Multiple: "UNUSED,USED" for multiple statuses
  • Omit parameter to get all rewards regardless of status

Point balance fields explained:

  • availablePoints: Points customer can redeem RIGHT NOW
  • pendingPoints: Points awaiting approval (e.g., from pending orders)
  • creditedPoints: Total points earned all-time (including spent points)
  • Relationship: creditedPoints = availablePoints + pendingPoints + spentPoints

VIP tier information:

  • currentVipTier: Name of customer's current tier (null if not in a tier)
  • vipTierExpiredAt: When tier expires (null if permanent or not in tier)
  • achievableTierId: Next tier customer can reach

Social media tracking (boolean flags):

  • rewardedForFacebook: Claimed Facebook like/follow points
  • rewardedForInstagram: Claimed Instagram follow points
  • rewardedForTwitter: Claimed Twitter follow points
  • rewardedForPinterest: Claimed Pinterest follow points
  • rewardedForYoutube: Claimed YouTube subscribe points
  • rewardedForTiktok: Claimed TikTok follow points
  • rewardedForNewsLetter: Claimed newsletter signup points
  • rewardedForSms: Claimed SMS subscription points
  • rewardedForCreatingAccount: Claimed account creation points
  • rewardedForSharingOnFacebook: Claimed Facebook share points
  • rewardedForSharingOnX: Claimed X (Twitter) share points

Referral information:

  • referredCompleted: Number of successful referrals
  • referralLink: Unique URL for customer to share

Customer status values:

  • ACTIVE: Actively enrolled in loyalty program
  • EXCLUDED: Excluded by admin
  • EXCLUDED_BY_CUSTOMER: Customer opted out

Common integration patterns:

  1. Load loyalty dashboard: Call on page load
  2. After redemption: Call to get updated points and new reward
  3. After earning points: Call to show updated balance
  4. Real-time updates: Poll this endpoint or use webhooks

Performance tips:

  • Cache response for 30-60 seconds on frontend
  • Don't call on every page view, only on loyalty pages
  • Use status parameter to reduce response size if needed
Query
statusstring

Filter rewards by status (comma-separated values). Allowed values: UNUSED, USED, EXPIRED

Example: status=UNUSED,USED
curl -i -X GET \
  'https://loyalty-admin.appstle.com/loyalty/cp/api/customer-loyalty?status=UNUSED%2CUSED'

Responses

Customer loyalty information retrieved successfully

Bodyapplication/json
availablePointsnumber(double)
pendingPointsnumber(double)
creditedPointsnumber(double)
spentAmountnumber(double)
storeCreditBalancenumber(double)
achievableTierIdinteger(int64)
currentVipTierstring
vipTierExpiredAtstring(date-time)
createAtstring(date-time)
rewardedForFacebookboolean
rewardedForPinterestboolean
rewardedForTwitterboolean
rewardedForInstagramboolean
rewardedForYoutubeboolean
rewardedForTiktokboolean
rewardedForNewsLetterboolean
rewardedForSmsboolean
referredCompletedinteger(int64)
referralLinkstring
customerStatusstring
Enum"ACTIVE""INACTIVE""EXCLUDED""EXCLUDED_BY_CUSTOMER"
dobstring(date)
rewardsArray of objects(CustomerReward)
rewardedForCreatingAccountboolean
rewardedForSharingOnFacebookboolean
rewardedForSharingOnXboolean
Response
application/json
{
  "availablePoints": 150.5,
  "pendingPoints": 25,
  "creditedPoints": 175.5,
  "spentAmount": 299.99,
  "storeCreditBalance": 15,
  "currentVipTier": "Gold",
  "vipTierExpiredAt": "2025-12-31T23:59:59Z",
  "referredCompleted": 3,
  "referralLink": "https://store.com/referral/abc123",
  "customerStatus": "ACTIVE",
  "dob": "1990-05-15",
  "rewardedForFacebook": true,
  "rewardedForInstagram": false,
  "rewards": []
}