# Rewards

Customer rewards and redemptions

## Get customer rewards

> Retrieve customer rewards with optional filtering and pagination.\
> \
> \*\*Customer Identifier Required\*\*: Must provide either \`customerId\` or \`shopifyCustomerId\` parameter.<br>

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Rewards","description":"Customer rewards and redemptions"}],"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":{"PaginatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"},"description":"Array of items for current page"},"meta":{"type":"object","properties":{"pagination":{"type":"object","required":["hasNext","hasPre"],"properties":{"hasNext":{"type":"boolean","description":"True if more results exist after current page"},"hasPre":{"type":"boolean","description":"True if results exist before current page"},"total":{"type":"integer","description":"Total count of all matching results (when available)"},"totalPage":{"type":"integer","description":"Total number of pages calculated as ceil(total/limit) (when available)"}}}},"description":"Pagination metadata container"}}}]},"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"}}},"Reward":{"type":"object","properties":{"id":{"type":"string","description":"Reward ID"},"customerId":{"type":"string","description":"Internal customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"couponCode":{"type":"string","description":"Generated coupon/discount code"},"programTitle":{"type":"string","description":"Program title"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"programDescription":{"type":"string","description":"Program description"},"orderReqAmount":{"type":"string","description":"Minimum order amount required"},"expiredAt":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration date"},"discountStatus":{"type":"string","enum":["active","used","expired"],"description":"Current discount status"},"program":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Program ID"},"title":{"type":"string","description":"Program title"}}},"createdAt":{"type":"string","format":"date-time","description":"Reward creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"details":{"type":"object"}}},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/rewards":{"get":{"tags":["Rewards"],"summary":"Get customer rewards","description":"Retrieve customer rewards with optional filtering and pagination.\n\n**Customer Identifier Required**: Must provide either `customerId` or `shopifyCustomerId` parameter.\n","parameters":[{"name":"customerId","in":"query","schema":{"type":"string"},"description":"Joy internal customer ID"},{"name":"shopifyCustomerId","in":"query","schema":{"type":"string"},"description":"Shopify customer ID"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","used","expired"]},"description":"Filter by reward status"},{"name":"typeReward","in":"query","schema":{"type":"string"},"description":"Filter by reward type"},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (before) - Firestore document ID of reward to paginate before"},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (after) - Firestore document ID of reward to paginate after"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":1000},"description":"Number of rewards per page"},{"name":"created_at_min","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter rewards created after this date"},{"name":"created_at_max","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter rewards created before this date"},{"name":"order","in":"query","schema":{"type":"string","enum":["createdAt_desc","createdAt_asc","updatedAt_desc","updatedAt_asc"],"default":"createdAt_desc"},"description":"Sort order for results"},{"name":"hasCount","in":"query","schema":{"type":"boolean","default":false},"description":"Include total count in response (may increase response time)"}],"responses":{"200":{"description":"List of customer rewards","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reward"}}}}]}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /rest\_api/v2/rewards/{rewardId}

> Get reward by ID

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Rewards","description":"Customer rewards and redemptions"}],"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"}}},"Reward":{"type":"object","properties":{"id":{"type":"string","description":"Reward ID"},"customerId":{"type":"string","description":"Internal customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"couponCode":{"type":"string","description":"Generated coupon/discount code"},"programTitle":{"type":"string","description":"Program title"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"programDescription":{"type":"string","description":"Program description"},"orderReqAmount":{"type":"string","description":"Minimum order amount required"},"expiredAt":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration date"},"discountStatus":{"type":"string","enum":["active","used","expired"],"description":"Current discount status"},"program":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Program ID"},"title":{"type":"string","description":"Program title"}}},"createdAt":{"type":"string","format":"date-time","description":"Reward creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/rest_api/v2/rewards/{rewardId}":{"get":{"tags":["Rewards"],"summary":"Get reward by ID","parameters":[{"name":"rewardId","in":"path","required":true,"schema":{"type":"string"},"description":"Reward ID"}],"responses":{"200":{"description":"Reward details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reward"}}}]}}}}}}}}}
```

## Refund coupon code

> Process coupon refund and return points to customer

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Rewards","description":"Customer rewards and redemptions"}],"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"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"details":{"type":"object"}}},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/rest_api/v2/rewards/coupons/refund":{"post":{"tags":["Rewards"],"summary":"Refund coupon code","description":"Process coupon refund and return points to customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"discountCode":{"type":"string","description":"The coupon/discount code to refund"},"shopifyCustomerId":{"type":"string","description":"Shopify customer ID who owns the coupon"},"reason":{"type":"string","description":"Optional reason for the refund"}},"required":["discountCode","shopifyCustomerId"]}}}},"responses":{"200":{"description":"Coupon refunded successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}]}}}},"400":{"description":"Invalid request or coupon not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```