# 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. ## Update customer loyalty status - [POST /loyalty/cp/api/update-customer-status](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/updatecustomerstatus.md): Updates the loyalty program status for the authenticated customer. Allows customers to opt-in, opt-out, or exclude themselves from the loyalty program. Status changes are logged in the activity log with appropriate event types (CUSTOMER_EXCLUDED, CUSTOMER_INCLUDED). When a customer is excluded, they stop earning points but retain existing points and rewards. ## Update customer birth date - [POST /loyalty/cp/api/update-customer-birth-date](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/addcustomerbirthdate.md): Updates the birth date for the authenticated customer and potentially awards birthday-related loyalty points. Once set, the customer may receive birthday rewards annually. The birth date is validated and stored in the customer's loyalty profile. ## Sync customer metafield data - [POST /loyalty/cp/api/update-customer](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/updatecustomermetafield.md): Synchronizes the authenticated customer's metafield data with Shopify. This endpoint triggers an immediate sync of customer loyalty information (points, tier, etc.) to Shopify metafields. Useful when customer data needs to be refreshed in Shopify for theme display or other integrations. ## Submit product review - [POST /loyalty/cp/api/submit-review](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/submitreview.md): Submits a product review and potentially awards loyalty points. Two ways to submit reviews: 1. Order-linked review (recommended): - Include uniqueId in request (unique identifier for purchased product) - Product details auto-filled from order - Verifies customer actually purchased the product - More trustworthy for other customers 2. General review: - Omit uniqueId - Manually provide productId, productTitle, productImage - Customer can review any product - May not qualify for "verified purchase" points Required fields: - rating: 1-5 stars (integer) - title: Review headline (string) - body: Review content (string) - Either uniqueId OR (productId + productTitle) Optional fields: - productImage: URL to product image - reviewerName: Override customer name (defaults to account name) - images: Array of review image URLs - carouselStatus: Feature in carousel widget (boolean) - pinnedStatus: Pin to top of reviews (boolean) Point earning: - Points awarded based on "Product Review" earn rule - Points may be pending approval or immediate - Only first review per product typically earns points - Some merchants require review approval before points - Points processed asynchronously after submission Review moderation: - Reviews are published immediately by default - Can be configured to require admin approval - Check your loyalty settings for moderation rules - publishedStatus field controls visibility Image support: - Customers can attach images to reviews - Images must be publicly accessible URLs - Recommended to upload to your CDN first - Multiple images supported (array) Review display features: - carouselStatus=true: Shows in rotating carousel widget - pinnedStatus=true: Appears at top of product reviews - Both useful for highlighting exceptional reviews Authentication: Requires customer JWT token. The authenticated customer is the review author. Validation rules: - Rating must be 1, 2, 3, 4, or 5 - Title and body cannot be empty - Product must exist in catalog - If uniqueId provided, must be from customer's orders - Customer cannot review same product multiple times (configurable) Processing flow: 1. Validate review data 2. Create review record in database 3. Publish review (or queue for approval) 4. Trigger async process for point calculation 5. Award points if eligible 6. Send confirmation email (if configured) 7. Update product review statistics Response: Returns success message immediately. Points may take a few seconds to appear in account due to async processing. Best practices: 1. Use uniqueId when available for verified purchases 2. Encourage customers with point incentives 3. Display point reward amount before review form 4. Validate form data client-side before submission 5. Show success message with expected point amount 6. Explain points may take a moment to appear 7. Provide preview of how review will look Example review submission flow: 1. Customer views "Write a Review" page for product 2. Form shows: "Earn 50 points for reviewing this product!" 3. Customer fills out rating, title, body 4. Optionally uploads images 5. Clicks "Submit Review" 6. Call this endpoint 7. Show success: "Thank you! Your review has been submitted and 50 points will be added to your account shortly." 8. Redirect to product page or review confirmation page Error handling: - 400: Invalid data (missing fields, invalid rating, etc.) - 401: Not authenticated - 500: Server error (retry or contact support) ## Send customer referral email - [POST /loyalty/cp/api/send-customer-referral-url](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/sendcustomerreferralurl.md): Sends a referral invitation email to a friend on behalf of the authenticated customer. How referrals work: 1. Customer sends referral email to friend 2. Friend receives email with unique referral link 3. Friend clicks link and creates account/makes purchase 4. Both customer (referrer) and friend (referee) may receive rewards 5. Rewards based on referral rule configuration Request body: - email: Friend's email address (required, must be valid) - Can include additional fields like name, message (check your configuration) Email content: - Contains customer's unique referral link - Describes referral rewards (e.g., "You get $10 off, they get $10 off") - Uses your configured email template - Branded with your store logo and colors - Includes call-to-action button Rate limiting: - Default limit: 500 emails per shop per day - Prevents spam and abuse - 429 error if limit exceeded - Limit resets daily - Contact support to adjust limits if needed Activity logging: - Each send is logged for analytics - Track referral email performance - Monitor for fraudulent activity - View in admin dashboard Referral tracking: - Unique referral link embedded in email - Tracks when friend clicks link - Attributes purchase to referrer - Shows in customer's referral history Authentication: Requires customer JWT token. The authenticated customer is the referrer. Validation: - Email address format validation - Duplicate email checking (optional) - Customer must be enrolled in loyalty program - Referral program must be active - Customer not excluded from program Best practices: 1. Allow customers to preview email before sending 2. Show referral incentives clearly 3. Provide email template customization 4. Track success rate and optimize messaging 5. Consider social sharing alternatives 6. Display referral link prominently for manual sharing 7. Limit sends per customer to prevent spam Example UI flow: 1. Customer enters friend's email 2. Optional: Add personal message 3. Preview email content 4. Click "Send Invitation" 5. Call this endpoint 6. Show success message 7. Update referral count display 8. Add to "Sent Invitations" list Error scenarios: - Invalid email format: 400 error - Rate limit exceeded: 429 error (show retry time) - Customer not enrolled: 400 error - Referral program inactive: 400 error - Email service failure: 500 error (retry) Success response: Returns 200 with no body. Email sent successfully. Alternative sharing methods: Instead of email, customers can also: - Copy referral link directly (GET referral URL first) - Share on social media - Use QR code - Share via SMS (if configured) ## Redeem customer loyalty points - [POST /loyalty/cp/api/redeem-points](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/redeempoints.md): Allows the authenticated customer to redeem their loyalty points for rewards. Redemption flow: 1. Customer selects a reward from available options 2. Frontend calls this endpoint with redeemRuleId 3. System validates customer has sufficient points 4. Points are deducted from available balance 5. Discount code is created in Shopify 6. Reward record is created with status "UNUSED" 7. Transaction is logged 8. Updated loyalty info is returned 9. Customer receives discount code to use at checkout Request body fields: - redeemRuleId: ID of reward to redeem (required) Get available options from GET /loyalty/cp/api/customer-loyalty - points: Override default points (optional) If not provided, uses the redemption rule's default point value - variantId: Required for product-specific rewards (optional) Shopify variant ID for "free product" type rewards Authentication: Requires customer JWT token. The authenticated customer is the one redeeming points. Cannot redeem points on behalf of another customer. Validation checks: - Customer is authenticated - Customer has sufficient availablePoints - Redemption rule exists and is active - For product rewards, variantId is provided - Customer is enrolled in loyalty program - Customer status is ACTIVE (not excluded) What happens to points: - Deducted from availablePoints immediately - Added to lifetime spending total - Transaction created with type "REDEEMED" - Cannot be undone (points deduction is final) Discount code generation: - For discounts: Creates Shopify discount code - Code is unique per customer - Has expiry date if configured - Minimum purchase amount if configured - Product/collection restrictions if configured Store credit rewards: - Adds value to storeCreditBalance instead of creating discount code - Can be used as payment method at checkout - Managed separately from Shopify discount codes Error scenarios: - Insufficient points: availablePoints r.status === 'UNUSED'); // Display to customer showDiscountCode(newReward.discountCode, newReward.expiryDate); ``` Common UI flow: 1. Display available redemption options with point costs 2. Customer clicks "Redeem" 3. Show confirmation dialog with point cost 4. Call this endpoint 5. On success: Show discount code in modal/banner 6. Update points display with new balance 7. Add code to "My Rewards" list ## Enroll customer in loyalty program - [POST /loyalty/cp/api/enroll-customer](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/enrollcustomer.md): Enrolls the authenticated customer in the loyalty program and optionally assigns them to a specific VIP tier. This endpoint activates all loyalty features for the customer, allowing them to earn and redeem points. If a VIP tier is specified, the customer is automatically placed in that tier upon enrollment. Creates necessary customer records and triggers any welcome rewards configured in the system. ## Enable loyalty program for customer - [POST /loyalty/cp/api/enable-loyalty-program](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/enrollcustomer_1.md): Enables the loyalty program for the authenticated customer, allowing them to earn and redeem points. This is a simplified version of the enroll-customer endpoint that doesn't require any request body. Useful for quick customer opt-in flows without tier assignment. ## Track customer store visit - [POST /loyalty/cp/api/customer-visit-store](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/customervisitstore.md): Records a customer store visit and potentially awards loyalty points based on the shop's visit reward rules. This endpoint is typically called when a customer visits the storefront or specific pages. Includes rate limiting protection to prevent abuse - customers can only earn visit points up to a configured limit per day/period. The endpoint enforces a request limit (default 500) to prevent excessive API calls. ## Claim social media reward points - [POST /loyalty/cp/api/claim-social-media-points](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/claimsocialmediapoints.md): Allows a customer to claim loyalty points for social media engagement (Facebook like, Instagram follow, etc.) based on the specified earn rule. Each social media action can typically only be claimed once per customer. The system tracks which social media rewards have been claimed to prevent duplicate claims. ## Generate customer referral URL - [POST /loyalty/cp/api/add-customer-referral-url](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/addcustomerreferalurl.md): Creates and stores a short referral URL for the authenticated customer to share with potential referrals. The referral link is typically generated once and then can be shared via email, social media, or other channels. When new customers use this link, both the referrer and referee may receive rewards. ## Accept referral offer (GET) - [GET /loyalty/cp/api/referral-rules/accept-offer](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/acceptreferraloffer.md): Accepts a referral offer using the referral token and email address via query parameters. This is a convenience endpoint that provides the same functionality as the POST version but via GET request. Useful for simple referral link implementations where query parameters are easier to construct. Creates a new customer referral record and may generate a welcome discount code for the referee. ## Accept referral offer (POST) - [POST /loyalty/cp/api/referral-rules/accept-offer](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/acceptreferralofferpost.md): Accepts a referral offer when a new customer uses a referral link. Referral flow overview: 1. Existing customer (referrer) shares referral link 2. New customer (referee) clicks link 3. Link contains unique token 4. New customer signs up or browses 5. Call this endpoint with token and email 6. System creates referral record 7. May generate welcome discount for referee 8. Referrer gets points when referee makes purchase Request body: - token: Unique referral token from URL (required) - email: New customer's email address (required) What this endpoint does: 1. Validates referral token is valid 2. Checks referral program is active 3. Verifies referee hasn't used a referral before 4. Creates referral record linking referee to referrer 5. Generates welcome discount code (if configured) 6. May award immediate points to referee 7. Tracks referral for future reward distribution 8. Returns discount code for referee to use Referral rewards configuration: Different merchants configure different rewards: - Referee discount: Welcome discount for new customer - Referrer points: Points when referee makes purchase - Both rewards: Both parties get something - Tiered rewards: More for higher-value purchases Token validation: - Token must exist in system - Token must belong to active customer - Customer must have referral program enabled - Token has no expiration (typically) - Each token is unique per customer Duplicate prevention: - Email can only accept one referral - Cannot accept own referral - Cannot accept multiple referrals - First referral link used is the one that counts Response includes: - id: Referral record ID - message: Success or error message - discountCode: Welcome discount for referee (if applicable) - status: SUCCESS or ERROR Integration points: Option 1: Signup page integration javascript // During signup process const urlParams = new URLSearchParams(window.location.search); const referralToken = urlParams.get('token'); if (referralToken) { // After customer enters email await acceptReferral(referralToken, customerEmail); // Show welcome discount to customer } Option 2: Landing page integration javascript // On referral landing page const token = getReferralToken(); document.getElementById('claimButton').onclick = async () => { const email = document.getElementById('email').value; const response = await acceptReferral(token, email); showDiscountCode(response.discountCode); }; Referral tracking states: - PENDING: Referral accepted, waiting for first purchase - COMPLETED: Referee made qualifying purchase, rewards distributed - EXPIRED: Referral expired before qualifying purchase Best practices: 1. Call this endpoint early in customer journey 2. Store referral token in cookie/session if email not available yet 3. Show welcome discount prominently after acceptance 4. Explain referral benefits clearly 5. Handle already-accepted gracefully 6. Track conversion rate of referrals 7. A/B test referral incentives Common error scenarios: - Invalid token: Token doesn't exist or is malformed - Referral program inactive: Store disabled referrals - Already accepted: This email already used a referral - Self-referral: Customer trying to refer themselves - Token from excluded customer: Referrer is excluded from program When rewards are distributed: - Referee: Welcome discount immediately on acceptance - Referrer: Points awarded when referee makes first purchase - Both: May get additional rewards for repeat purchases ## Get customer point transaction history - [GET /loyalty/cp/api/transaction-by-shop](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/getallpointtransactionsbycustomer.md): Retrieves paginated list of point transactions for the authenticated customer, ordered by ID descending (most recent first). Each transaction includes details about points earned or spent, transaction type, status (PENDING, APPROVED, REJECTED), associated order information, and timestamps. Useful for displaying transaction history to customers. ## Get logged-in customer ID - [GET /loyalty/cp/api/logged-in-customer](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/getloggedincustomer.md): 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. ## Get customer referral history - [GET /loyalty/cp/api/customer-referrals](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/getallcustomerreferrals.md): 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. ## Get customer loyalty information - [GET /loyalty/cp/api/customer-loyalty](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/getcustomerloyalty.md): 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 ## Get product reviews by product ID - [GET /loyalty/cp/api/product-review-details/{productId}](https://developers.loyalty.appstle.com/storefront-api-swagger/storefront-apis/getallproductreviewsbyproductid.md): Retrieves paginated list of published product reviews for a specific product, with optional rating filtering. Only returns published and non-archived reviews to ensure quality content is displayed. Supports filtering by rating (1-5 stars) to allow customers to view reviews by satisfaction level. Reviews are returned with full details including reviewer name, rating, title, body, images, and timestamps.