User guide

Rewards

Customer rewards and redemptions

Get reward by ID

get
Path parameters
rewardIdstringRequired

Reward ID

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
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": "2025-09-08T23:38:57.092Z",
    "discountStatus": "active",
    "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"
}

Get customer rewards

get

Retrieve customer rewards with optional filtering and pagination

Query parameters
shopifyCustomerIdstringOptional

Filter by Shopify customer ID

statusstring · enumOptional

Filter by reward status

Possible values:
typeRewardstringOptional

Filter by reward type

beforestringOptional

Cursor for pagination (before) - Firestore document ID

afterstringOptional

Cursor for pagination (after) - Firestore document ID

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
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": "2025-09-08T23:38:57.092Z",
      "discountStatus": "active",
      "createdAt": "2025-06-12T10:31:25.781Z",
      "updatedAt": "2025-06-12T10:31:25.781Z",
      "program": {
        "id": "akwQ96WZJMIqrG26PNlC",
        "title": "Points for discounts"
      }
    }
  ],
  "meta": {
    "pagination": {
      "hasNext": true,
      "hasPre": true,
      "total": 1,
      "totalPage": 1
    }
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Refund coupon code

post

Process coupon refund and return points to customer

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}}
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
POST /rest_api/v2/rewards/coupons/refund HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
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"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
PreviousActivitiesNextTiers

Last updated