Skip to content
👥 Storefront APIs
/
/
Sync customer metafield d...

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

Update customer birth date

Request

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.

Bodyapplication/jsonrequired
customerIdinteger(int64)

Unique identifier of the customer

Example: 0
dobstring(date)

Customer date of birth

Example: "2026-01-12"
statusstring

Customer loyalty status

Enum"ACTIVE""INACTIVE""EXCLUDED""EXCLUDED_BY_CUSTOMER""ACTIVE""INACTIVE""EXCLUDED""EXCLUDED_BY_CUSTOMER"
Example: "ACTIVE"
curl -i -X POST \
  https://loyalty-admin.appstle.com/loyalty/cp/api/update-customer-birth-date \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": 0,
    "dob": "2026-01-12",
    "status": "ACTIVE"
  }'

Responses

Customer birth date updated successfully

Bodyapplication/json
idinteger(int64)
shopstringrequired
customerIdinteger(int64)required
firstNamestring
lastNamestring
emailstring
statusstring
Enum"ACTIVE""INACTIVE""EXCLUDED""EXCLUDED_BY_CUSTOMER"
createAtstring(date-time)required
dobstring(date)
enableEmailboolean
tokenstring
redeemLimitinteger(int64)
redeemLimitOnceinteger(int64)
vipTierstring
vipTierIdinteger(int64)
vipTierSummarystring
availablePointsnumber(double)required
pendingPointsnumber(double)required
displayNamestring
vipTierExpiredAtstring(date-time)
spentAmountnumber(double)
lastActivitystring(date-time)
ordersCountinteger(int32)
lastMonthlyReminderSentDatestring(date-time)
redeemedPointsnumber(double)
lastRewardExpiryReminderSentDatestring(date-time)
vipAssignTypestring
Enum"MANUAL""AUTO_RENEWAL""RENEWAL_ON_HIGHER_TIER"
phonestring
loyaltyProgramEnabledboolean
emailSettingstring
skipReviewboolean
updatedSettingsstring
storeCreditAccountIdstring
emailBouncedOrFailedboolean
availableStoreCreditsnumber(double)
isDeletedFromShopifyboolean
enableEmailMarketingboolean
enableSmsMarketingboolean
tagsstring
vipTierAmountnumber(double)
Response
application/json
{
  "id": 0,
  "shop": "string",
  "customerId": 0,
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "status": "ACTIVE",
  "createAt": "2019-08-24T14:15:22Z",
  "dob": "2019-08-24",
  "enableEmail": true,
  "token": "string",
  "redeemLimit": 0,
  "redeemLimitOnce": 0,
  "vipTier": "string",
  "vipTierId": 0,
  "vipTierSummary": "string",
  "availablePoints": 0.1,
  "pendingPoints": 0.1,
  "displayName": "string",
  "vipTierExpiredAt": "2019-08-24T14:15:22Z",
  "spentAmount": 0.1,
  "lastActivity": "2019-08-24T14:15:22Z",
  "ordersCount": 0,
  "lastMonthlyReminderSentDate": "2019-08-24T14:15:22Z",
  "redeemedPoints": 0.1,
  "lastRewardExpiryReminderSentDate": "2019-08-24T14:15:22Z",
  "vipAssignType": "MANUAL",
  "phone": "string",
  "loyaltyProgramEnabled": true,
  "emailSetting": "string",
  "skipReview": true,
  "updatedSettings": "string",
  "storeCreditAccountId": "string",
  "emailBouncedOrFailed": true,
  "availableStoreCredits": 0.1,
  "isDeletedFromShopify": true,
  "enableEmailMarketing": true,
  "enableSmsMarketing": true,
  "tags": "string",
  "vipTierAmount": 0.1
}

Sync customer metafield data

Request

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.

curl -i -X POST \
  https://loyalty-admin.appstle.com/loyalty/cp/api/update-customer

Responses

Customer data synchronized successfully

Submit product review

Request

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)
Bodyapplication/jsonrequired
idinteger(int64)
shopstringrequired
titlestring
bodystring
ratinginteger(int32)
publishedStatusboolean
reviewerNamestring
reviewerEmailstring
productIdinteger(int64)
pinnedboolean
archivedboolean
createAtstring(date-time)required
replayBodystring
replayDatestring(date-time)
productTitlestring
productHandlestring
productImagestring
originalReviewTitlestring
originalReviewBodystring
uniqueIdstring(uuid)
customerIdinteger(int64)
reviewEditReasonstring
carouselboolean
reviewSourcestring
Enum"WEB_PAGE""API""IMPORT"
curl -i -X POST \
  https://loyalty-admin.appstle.com/loyalty/cp/api/submit-review \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0,
    "shop": "string",
    "title": "string",
    "body": "string",
    "rating": 0,
    "publishedStatus": true,
    "reviewerName": "string",
    "reviewerEmail": "string",
    "productId": 0,
    "pinned": true,
    "archived": true,
    "createAt": "2019-08-24T14:15:22Z",
    "replayBody": "string",
    "replayDate": "2019-08-24T14:15:22Z",
    "productTitle": "string",
    "productHandle": "string",
    "productImage": "string",
    "originalReviewTitle": "string",
    "originalReviewBody": "string",
    "uniqueId": "a1e12d74-d756-40d1-9bb3-519def353f44",
    "customerId": 0,
    "reviewEditReason": "string",
    "carousel": true,
    "reviewSource": "WEB_PAGE"
  }'

Responses

Review submitted successfully. Points will be awarded asynchronously if eligible.

Bodyapplication/json
string
Response
application/json
"Review successfully submitted; it will reflect shortly."