User guide

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.

Query parameters
customerIdstringOptional

Joy internal customer ID

Example: XLacU68YKR5tC3moGqUP
shopifyCustomerIdstringOptional

Shopify customer ID

Example: 8720295559390
statusstring · enumOptional

Filter by reward status

Possible values:
typeRewardstringOptional

Filter by reward type

beforestringOptional

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

afterstringOptional

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

limitinteger · min: 1 · max: 1000Optional

Number of rewards per page

Default: 10
created_at_minstring · date-timeOptional

Filter rewards created after this date

created_at_maxstring · date-timeOptional

Filter rewards created before this date

orderstring · enumOptional

Sort order for results

Default: createdAt_descPossible values:
hasCountbooleanOptional

Include total count in response (may increase response time)

Default: false
Header parameters
X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Responses
200

List of customer rewards

application/json
Responseall of
get
/rest_api/v2/rewards
GET /rest_api/v2/rewards HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*

{
  "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}
Path parameters
rewardIdstringRequired

Reward ID

Example: OPfV7dXaPn1Ejbm9piPs
Header parameters
X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Responses
200

Reward details

application/json
Responseall of
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: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*
200

Reward 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

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
200

Coupon refunded successfully

application/json
Responseall of
post
/rest_api/v2/rewards/coupons/refund
POST /rest_api/v2/rewards/coupons/refund HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "discountCode": "JOY-8PBFA801B2FH",
  "shopifyCustomerId": "7603687882987",
  "reason": "Customer request"
}
{
  "success": true,
  "data": {
    "success": true,
    "message": "Coupon refunded successfully"
  }
}
PreviousActivitiesNextTiers