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)