Rewards

Customer rewards and redemptions

Get customer rewards

get

https://dev-api.joy.sohttps://api.joy.so

/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

404

Customer not found

application/json

get

/rest_api/v2/rewards

HTTPcURLJavaScriptPython

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

https://dev-api.joy.sohttps://api.joy.so

/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

get

/rest_api/v2/rewards/{rewardId}

HTTPcURLJavaScriptPython

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

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/rewards/coupons/refund

Process coupon refund and return points to customer

Body

application/json

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

400

Invalid request or coupon not found

application/json

post

/rest_api/v2/rewards/coupons/refund

HTTPcURLJavaScriptPython

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"
  }
}