Storefront APIs

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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)

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)

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 < required points
• Invalid rule: redeemRuleId doesn't exist or is inactive
• Missing variantId: Required for product rewards
• Customer not enrolled: Must enroll first
• Customer excluded: EXCLUDED or EXCLUDED_BY_CUSTOMER status
• System error: Shopify API failure, discount code creation failure

Best practices:

1. Check availablePoints before showing redemption options
2. Display point cost clearly to customer
3. Show expected reward (discount %, amount, etc.)
4. Handle errors gracefully with clear messages
5. After success, show discount code prominently
6. Provide copy-to-clipboard functionality for code
7. Explain when/how to use the discount code

Example response handling:

// After successful redemption
const response = await redeemPoints(ruleId);
// Find the newly created reward
const newReward = response.rewards.find(r => 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