# Referrals

Referral system management

## Generate referral invitation

> Create a new referral invitation link for a customer

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Referrals","description":"Referral system management"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/referrals/invitations":{"post":{"tags":["Referrals"],"summary":"Generate referral invitation","description":"Create a new referral invitation link for a customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Invitation generated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"inviteLink":{"type":"string"},"referralCode":{"type":"string"}}}}}]}}}}}}}}}
```

## Get customer referrers

> Retrieve list of customers who referred this customer

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Referrals","description":"Referral system management"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"ListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items returned"}}}}}]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/referrals/customers/{customerId}/referrers":{"get":{"tags":["Referrals"],"summary":"Get customer referrers","description":"Retrieve list of customers who referred this customer","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"description":"Customer ID"}],"responses":{"200":{"description":"List of referrers","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}]}}}}}}}}}
```

## Get customer referral summary

> Retrieve comprehensive referral statistics for a customer

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Referrals","description":"Referral system management"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/referrals/customers/{customerId}/summary":{"get":{"tags":["Referrals"],"summary":"Get customer referral summary","description":"Retrieve comprehensive referral statistics for a customer","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"description":"Customer ID"}],"responses":{"200":{"description":"Referral summary","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"totalRedeemCoupon":{"type":"integer"},"totalPointEarnRefer":{"type":"integer"}}}}}]}}}}}}}}}
```

## Get referral analytics

> Retrieve referral program analytics and performance metrics

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Referrals","description":"Referral system management"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/referrals/analytics":{"get":{"tags":["Referrals"],"summary":"Get referral analytics","description":"Retrieve referral program analytics and performance metrics","parameters":[{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Referral analytics data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"countCouponCodeUsage":{"type":"integer"}}}}}]}}}}}}}}}
```