REST API v2
API references
Rewards

Rewards

Customer rewards and redemptions

Get customer rewards

GET/rest_api/v2/rewards

Retrieve customer rewards with optional filtering and pagination.

Customer Identifier Required: Must provide either customerId or shopifyCustomerId parameter.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
customerIdquery · stringOptional

Joy internal customer ID

shopifyCustomerIdquery · stringOptional

Shopify customer ID

statusquery · stringOptional

Filter by reward status

typeRewardquery · stringOptional

Filter by reward type

beforequery · stringOptional

Cursor for pagination (before) - Firestore document ID of reward to paginate before

afterquery · stringOptional

Cursor for pagination (after) - Firestore document ID of reward to paginate after

limitquery · integerOptional

Number of rewards per page

created_at_minquery · string · date-timeOptional

Filter rewards created after this date

created_at_maxquery · string · date-timeOptional

Filter rewards created before this date

orderquery · stringOptional

Sort order for results

hasCountquery · booleanOptional

Include total count in response (may increase response time)

Responses
200List of customer rewards
successbooleanOptional
Example: true
dataReward[]Required
Show properties
idstringOptional

Reward ID

Example: "OPfV7dXaPn1Ejbm9piPs"
customerIdstringOptional

Internal customer ID

Example: "o9AQeUCXYDjbeFm7vAKy"
emailstring · emailOptional

Customer email address

Example: "[email protected]"
couponCodestringOptional

Generated coupon/discount code

Example: "JOY-8PBFA801B2FH"
programTitlestringOptional

Program title

Example: "Points for discounts"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7603687882987
programDescriptionstringOptional

Program description

Example: "1 x 1% discount"
orderReqAmountstringOptional

Minimum order amount required

Example: "$1"
expiredAtstring · date-timeOptional

Reward expiration date

Example: null
discountStatusstringOptional

Current discount status

Example: "active"
programobjectOptional
Show properties
idstringOptional

Program ID

Example: "akwQ96WZJMIqrG26PNlC"
titlestringOptional

Program title

Example: "Points for discounts"
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-12T10:31:25.781Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-12T10:31:25.781Z"
metaobjectOptional

Pagination metadata container

Show properties
paginationobjectOptional
Show properties
hasNextbooleanRequired

True if more results exist after current page

hasPrebooleanRequired

True if results exist before current page

totalintegerOptional

Total count of all matching results (when available)

totalPageintegerOptional

Total number of pages calculated as ceil(total/limit) (when available)

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
404Customer not found
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/rewards
GET /rest_api/v2/rewards HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200List of customer rewards
{
  "success": true,
  "data": [
    {
      "id": "OPfV7dXaPn1Ejbm9piPs",
      "customerId": "o9AQeUCXYDjbeFm7vAKy",
      "email": "[email protected]",
      "couponCode": "JOY-8PBFA801B2FH",
      "programTitle": "Points for discounts",
      "shopifyCustomerId": 7603687882987,
      "programDescription": "1 x 1% discount",
      "orderReqAmount": "$1",
      "expiredAt": null,
      "discountStatus": "active",
      "program": {
        "id": "akwQ96WZJMIqrG26PNlC",
        "title": "Points for discounts"
      },
      "createdAt": "2025-06-12T10:31:25.781Z",
      "updatedAt": "2025-06-12T10:31:25.781Z"
    }
  ],
  "meta": {
    "pagination": {
      "hasNext": false,
      "hasPre": false,
      "total": 1,
      "totalPage": 1
    }
  },
  "timestamp": "2025-06-12T10:31:25.781Z"
}

Get reward by ID

GET/rest_api/v2/rewards/{rewardId}
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
rewardIdpath · stringRequired

Reward ID

Responses
200Reward details
successbooleanOptional
Example: true
dataRewardOptional
Show properties
idstringOptional

Reward ID

Example: "OPfV7dXaPn1Ejbm9piPs"
customerIdstringOptional

Internal customer ID

Example: "o9AQeUCXYDjbeFm7vAKy"
emailstring · emailOptional

Customer email address

Example: "[email protected]"
couponCodestringOptional

Generated coupon/discount code

Example: "JOY-8PBFA801B2FH"
programTitlestringOptional

Program title

Example: "Points for discounts"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7603687882987
programDescriptionstringOptional

Program description

Example: "1 x 1% discount"
orderReqAmountstringOptional

Minimum order amount required

Example: "$1"
expiredAtstring · date-timeOptional

Reward expiration date

Example: null
discountStatusstringOptional

Current discount status

Example: "active"
programobjectOptional
Show properties
idstringOptional

Program ID

Example: "akwQ96WZJMIqrG26PNlC"
titlestringOptional

Program title

Example: "Points for discounts"
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-12T10:31:25.781Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-12T10:31:25.781Z"
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/rewards/{rewardId}
GET /rest_api/v2/rewards/{rewardId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Reward details
{
  "success": true,
  "data": {
    "id": "OPfV7dXaPn1Ejbm9piPs",
    "customerId": "o9AQeUCXYDjbeFm7vAKy",
    "email": "[email protected]",
    "couponCode": "JOY-8PBFA801B2FH",
    "programTitle": "Points for discounts",
    "shopifyCustomerId": 7603687882987,
    "programDescription": "1 x 1% discount",
    "orderReqAmount": "$1",
    "expiredAt": null,
    "discountStatus": "active",
    "program": {
      "id": "akwQ96WZJMIqrG26PNlC",
      "title": "Points for discounts"
    },
    "createdAt": "2025-06-12T10:31:25.781Z",
    "updatedAt": "2025-06-12T10:31:25.781Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Refund coupon code

POST/rest_api/v2/rewards/coupons/refund

Process coupon refund and return points to customer

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request body
discountCodestringRequired

The coupon/discount code to refund

Example: "JOY-8PBFA801B2FH"
shopifyCustomerIdstringRequired

Shopify customer ID who owns the coupon

Example: "7603687882987"
reasonstringOptional

Optional reason for the refund

Example: "Customer request"
Responses
200Coupon refunded successfully
successbooleanOptional
Example: true
dataobjectOptional
Show properties
successbooleanOptional
Example: true
messagestringOptional
Example: "Coupon refunded successfully"
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
400Invalid request or coupon not found
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
POST/rest_api/v2/rewards/coupons/refund
POST /rest_api/v2/rewards/coupons/refund HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 112


{
  "discountCode": "JOY-8PBFA801B2FH",
  "shopifyCustomerId": "7603687882987",
  "reason": "Customer request"
}
200Coupon refunded successfully
{
  "success": true,
  "data": {
    "success": true,
    "message": "Coupon refunded successfully"
  }
}
ActivitiesTiers
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.