User guide

Customers

Customer data and management

Get customers with pagination

get
Query parameters
beforestringOptional

Cursor for pagination (before) - Firestore document ID

afterstringOptional

Cursor for pagination (after) - Firestore document ID

limitinteger · min: 1 · max: 1000Optional

Number of customers per page

Default: 20
emailstringOptional

Search by customer email address

typestring · enumOptional

Filter by customer type

Possible values:
tierIdstringOptional

Filter by customer tier ID

updated_at_minstring · date-timeOptional

Filter customers updated after this date

updated_at_maxstring · date-timeOptional

Filter customers updated before this date

created_at_maxstring · date-timeOptional

Filter customers 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

Paginated list of customers

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

Paginated list of customers

{
  "success": true,
  "data": [
    {
      "id": "b1wvKrxdDZ11U8tUlyyx",
      "shopifyCustomerId": 7801029525739,
      "email": "[email protected]",
      "name": "John Doe",
      "type": "member",
      "point": 100,
      "tierPoint": 100,
      "pendingPoint": 0,
      "totalSpent": 0,
      "totalEarnedPoints": 100,
      "hasPoint": true,
      "hasJoinedProgram": true,
      "state": "enabled",
      "latestActivity": "2025-04-29T10:23:05.990Z",
      "notifications": {},
      "acceptsMarketing": false,
      "birthday": "05/15",
      "dateOfBirth": "1990-05-15",
      "tierName": "Bronze",
      "tierUpdatedAt": "2025-06-16T10:20:58.636Z",
      "phone": null,
      "pointsRemain": 4900,
      "isCustomerB2B": false,
      "earnSignUp": true,
      "referralCode": "2kxRoqlDQMp",
      "hasTier": false,
      "totalSpentCurrencyCode": "VND",
      "createdAt": "2025-04-29T10:23:05.991Z",
      "updatedAt": "2025-06-16T10:20:58.663Z"
    }
  ],
  "meta": {
    "pagination": {
      "hasNext": true,
      "hasPre": true,
      "total": 1,
      "totalPage": 1
    }
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get customer by ID

get
Path parameters
customerIdstringRequired

Internal customer 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

Customer details

application/json
Responseall of
get
GET /rest_api/v2/customers/{customerId} 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": "b1wvKrxdDZ11U8tUlyyx",
    "shopifyCustomerId": 7801029525739,
    "email": "[email protected]",
    "name": "John Doe",
    "type": "member",
    "point": 100,
    "tierPoint": 100,
    "pendingPoint": 0,
    "totalSpent": 0,
    "totalEarnedPoints": 100,
    "hasPoint": true,
    "hasJoinedProgram": true,
    "state": "enabled",
    "latestActivity": "2025-04-29T10:23:05.990Z",
    "notifications": {},
    "acceptsMarketing": false,
    "birthday": "05/15",
    "dateOfBirth": "1990-05-15",
    "tierName": "Bronze",
    "tierUpdatedAt": "2025-06-16T10:20:58.636Z",
    "phone": null,
    "pointsRemain": 4900,
    "isCustomerB2B": false,
    "earnSignUp": true,
    "referralCode": "2kxRoqlDQMp",
    "hasTier": false,
    "totalSpentCurrencyCode": "VND",
    "createdAt": "2025-04-29T10:23:05.991Z",
    "updatedAt": "2025-06-16T10:20:58.663Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get customer earned points

get

Retrieve total points earned by a customer across all programs

Path parameters
customerIdstringRequired

Internal customer 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

Customer earned points summary

application/json
Responseall of
get
GET /rest_api/v2/customers/{customerId}/points/earned HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*
200

Customer earned points summary

{
  "success": true,
  "data": {
    "totalEarnedPoints": 1
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer data

put

Update customer information (supports birthday fields)

Path parameters
customerIdstringRequired

Internal customer 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}}
Body
dateOfBirthstring · dateOptional

Date of birth in ISO 8601 format (YYYY-MM-DD)

birthdaystringOptional

Birthday in MM/DD format

Responses
200

Customer updated successfully

application/json
Responseall of
put
PUT /rest_api/v2/customers/{customerId} 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: 46

{
  "dateOfBirth": "2025-09-08",
  "birthday": "text"
}
{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer VIP tier

put

Update customer's VIP tier with comprehensive tier processing

Path parameters
customerIdstringRequired

Internal customer 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}}
Body
tierIdstringRequired

Target tier ID

triggerRewardbooleanOptional

Whether to trigger tier rewards

Default: true
adminNotestringOptional

Admin note for the tier change activity

Responses
200

Customer tier updated successfully

application/json
Responseall of
put
PUT /rest_api/v2/customers/{customerId}/tier 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: 57

{
  "tierId": "text",
  "triggerReward": true,
  "adminNote": "text"
}
{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text",
    "tierId": "text",
    "tierName": "text",
    "tierPoint": 1,
    "tierUpdatedAt": "2025-09-08T17:05:06.615Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer data by Shopify ID

put

Update customer information using Shopify customer ID

Path parameters
shopifyCustomerIdstringRequired

Shopify customer 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}}
Body
dateOfBirthstring · dateOptional

Date of birth in ISO 8601 format (YYYY-MM-DD)

birthdaystringOptional

Birthday in MM/DD format

Responses
200

Customer updated successfully

application/json
Responseall of
put
PUT /rest_api/v2/customers/external/{shopifyCustomerId} 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: 46

{
  "dateOfBirth": "2025-09-08",
  "birthday": "text"
}
200

Customer updated successfully

{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer VIP tier by Shopify ID

put

Update customer's VIP tier using Shopify customer ID

Path parameters
shopifyCustomerIdstringRequired

Shopify customer 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}}
Body
tierIdstringRequired

Target tier ID

triggerRewardbooleanOptional

Whether to trigger tier rewards

Default: true
adminNotestringOptional

Admin note for the tier change activity

Responses
200

Customer tier updated successfully

application/json
Responseall of
put
PUT /rest_api/v2/customers/external/{shopifyCustomerId}/tier 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: 57

{
  "tierId": "text",
  "triggerReward": true,
  "adminNote": "text"
}
200

Customer tier updated successfully

{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text",
    "tierId": "text",
    "tierName": "text",
    "tierPoint": 1,
    "tierUpdatedAt": "2025-09-08T17:05:06.615Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
PreviousREST API v2NextPrograms

Last updated