REST API v2
API references
Customers

Customers

Customer data and management

Get customers with pagination

GET/rest_api/v2/customers
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
beforequery · stringOptional

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

afterquery · stringOptional

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

limitquery · integerOptional

Number of customers per page

emailquery · stringOptional

Search by customer email address

typequery · stringOptional

Filter by customer type

tierIdquery · stringOptional

Filter by customer tier ID

updated_at_minquery · string · date-timeOptional

Filter customers updated after this date

updated_at_maxquery · string · date-timeOptional

Filter customers updated before this date

created_at_maxquery · string · date-timeOptional

Filter customers created before this date

orderquery · stringOptional

Sort order for results

hasCountquery · booleanOptional

Include total count in response (may increase response time)

Responses
200Paginated list of customers
successbooleanOptional
Example: true
dataCustomer[]Required
Show properties
idstringOptional

Internal customer ID

Example: "b1wvKrxdDZ11U8tUlyyx"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
namestringOptional

Customer full name

Example: "John Doe"
firstNamestringOptional

Customer first name

Example: "John"
lastNamestringOptional

Customer last name

Example: "Doe"
typestringOptional

Customer type

Example: "member"
pointintegerOptional

Current available points

Example: 100
tierPointintegerOptional

Points used for tier calculation

Example: 100
pendingPointintegerOptional

Points pending approval

Example: 0
totalSpentnumberOptional

Total amount spent

Example: 0
totalEarnedPointsintegerOptional

Lifetime earned points

Example: 100
hasPointbooleanOptional

Whether customer has available points

Example: true
hasJoinedProgrambooleanOptional

Whether customer joined loyalty program

Example: true
orderCountintegerOptional

Number of orders placed

Example: 0
statestringOptional

Account state

Example: "enabled"
latestActivitystring · date-timeOptional

Last activity timestamp

Example: "2025-04-29T10:23:05.990Z"
notificationsobjectOptional

Customer notification preferences

Example: {}
acceptsMarketingbooleanOptional

Marketing consent

Example: false
birthdaystringOptional

Birthday in MM/DD format

Example: "05/15"
dateOfBirthstring · dateOptional

Date of birth in YYYY-MM-DD format

Example: "1990-05-15"
tierIdstringOptional

Current tier ID

Example: "1Fe1kqHZbE7Alx1GmFEC"
tierNamestringOptional

Current tier name

Example: "Bronze"
tierUpdatedAtstring · date-timeOptional

Last tier update timestamp

Example: "2025-06-16T10:20:58.636Z"
phonestringOptional

Phone number

Example: null
pointsRemainintegerOptional

Points needed for next tier

Example: 4900
birthMonthstringOptional

Birth month in MM format

Example: "05"
isCustomerB2BbooleanOptional

Whether customer is B2B

Example: false
earnSignUpbooleanOptional

Whether customer earned signup points

Example: true
referralCodestringOptional

Customer's referral code

Example: "2kxRoqlDQMp"
hasTierbooleanOptional

Whether customer has a tier assigned

Example: false
totalSpentCurrencyCodestringOptional

Currency code for spending

Example: "VND"
createdAtstring · date-timeOptional

Account creation timestamp

Example: "2025-04-29T10:23:05.991Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-16T10:20:58.663Z"
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"
GET/rest_api/v2/customers
GET /rest_api/v2/customers 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: */*
200Paginated list of customers
{
  "success": true,
  "data": [
    {
      "id": "b1wvKrxdDZ11U8tUlyyx",
      "shopifyCustomerId": 7801029525739,
      "email": "[email protected]",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "type": "member",
      "point": 100,
      "tierPoint": 100,
      "totalEarnedPoints": 100,
      "hasPoint": true,
      "hasJoinedProgram": true,
      "state": "enabled",
      "acceptsMarketing": false,
      "tierId": "1Fe1kqHZbE7Alx1GmFEC",
      "tierName": "Bronze",
      "pointsRemain": 4900,
      "isCustomerB2B": false,
      "earnSignUp": true,
      "referralCode": "2kxRoqlDQMp",
      "hasTier": true,
      "totalSpentCurrencyCode": "VND",
      "createdAt": "2025-04-29T10:23:05.991Z",
      "updatedAt": "2025-06-16T10:20:58.663Z"
    }
  ],
  "meta": {
    "pagination": {
      "hasNext": true,
      "hasPre": false,
      "total": 1250,
      "totalPage": 63
    }
  },
  "timestamp": "2025-06-16T10:20:58.663Z"
}

Get customer by ID

GET/rest_api/v2/customers/{customerId}
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
customerIdpath · stringRequired

Internal customer ID

Responses
200Customer details
successbooleanOptional
Example: true
dataCustomerOptional
Show properties
idstringOptional

Internal customer ID

Example: "b1wvKrxdDZ11U8tUlyyx"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
namestringOptional

Customer full name

Example: "John Doe"
firstNamestringOptional

Customer first name

Example: "John"
lastNamestringOptional

Customer last name

Example: "Doe"
typestringOptional

Customer type

Example: "member"
pointintegerOptional

Current available points

Example: 100
tierPointintegerOptional

Points used for tier calculation

Example: 100
pendingPointintegerOptional

Points pending approval

Example: 0
totalSpentnumberOptional

Total amount spent

Example: 0
totalEarnedPointsintegerOptional

Lifetime earned points

Example: 100
hasPointbooleanOptional

Whether customer has available points

Example: true
hasJoinedProgrambooleanOptional

Whether customer joined loyalty program

Example: true
orderCountintegerOptional

Number of orders placed

Example: 0
statestringOptional

Account state

Example: "enabled"
latestActivitystring · date-timeOptional

Last activity timestamp

Example: "2025-04-29T10:23:05.990Z"
notificationsobjectOptional

Customer notification preferences

Example: {}
acceptsMarketingbooleanOptional

Marketing consent

Example: false
birthdaystringOptional

Birthday in MM/DD format

Example: "05/15"
dateOfBirthstring · dateOptional

Date of birth in YYYY-MM-DD format

Example: "1990-05-15"
tierIdstringOptional

Current tier ID

Example: "1Fe1kqHZbE7Alx1GmFEC"
tierNamestringOptional

Current tier name

Example: "Bronze"
tierUpdatedAtstring · date-timeOptional

Last tier update timestamp

Example: "2025-06-16T10:20:58.636Z"
phonestringOptional

Phone number

Example: null
pointsRemainintegerOptional

Points needed for next tier

Example: 4900
birthMonthstringOptional

Birth month in MM format

Example: "05"
isCustomerB2BbooleanOptional

Whether customer is B2B

Example: false
earnSignUpbooleanOptional

Whether customer earned signup points

Example: true
referralCodestringOptional

Customer's referral code

Example: "2kxRoqlDQMp"
hasTierbooleanOptional

Whether customer has a tier assigned

Example: false
totalSpentCurrencyCodestringOptional

Currency code for spending

Example: "VND"
createdAtstring · date-timeOptional

Account creation timestamp

Example: "2025-04-29T10:23:05.991Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-16T10:20:58.663Z"
metaobjectOptional

Additional metadata such as counts and pagination

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/customers/{customerId}
GET /rest_api/v2/customers/{customerId} 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: */*
200Customer details
{
  "success": true,
  "data": {
    "id": "cust_abc123",
    "shopifyCustomerId": 7891234567890,
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "point": 150,
    "pointsRemain": 350,
    "tierId": "tier_gold_123",
    "tierName": "Gold",
    "createdAt": "2023-07-15T10:30:00.000Z",
    "updatedAt": "2023-07-28T07:27:54.123Z"
  }
}

Update customer data

PUT/rest_api/v2/customers/{customerId}

Update customer information (supports birthday fields)

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
customerIdpath · stringRequired

Internal customer ID

Request body
dateOfBirthstring · dateOptional

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

birthdaystringOptional

Birthday in MM/DD format

Responses
200Customer updated successfully
successbooleanOptional
Example: true
dataobjectOptional
Show properties
idstringOptional
shopifyCustomerIdstringOptional
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 data
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"
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"
PUT/rest_api/v2/customers/{customerId}
PUT /rest_api/v2/customers/{customerId} 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: 33


{
  "dateOfBirth": "1990-05-15"
}
200Customer updated successfully
{
  "success": true,
  "data": {
    "id": "string",
    "shopifyCustomerId": "string"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get customer earned points

GET/rest_api/v2/customers/{customerId}/points/earned

Retrieve total points earned by a customer across all programs

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
customerIdpath · stringRequired

Internal customer ID

Responses
200Customer earned points summary
successbooleanOptional
Example: true
dataobjectOptional
Show properties
totalEarnedPointsintegerOptional
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/customers/{customerId}/points/earned
GET /rest_api/v2/customers/{customerId}/points/earned 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: */*
200Customer earned points summary
{
  "success": true,
  "data": {
    "totalEarnedPoints": 1
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get customer by Shopify ID

GET/rest_api/v2/customers/external/{shopifyCustomerId}

Retrieve customer information using Shopify customer ID

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
shopifyCustomerIdpath · stringRequired

Shopify customer ID

Responses
200Customer details
successbooleanOptional
Example: true
dataCustomerOptional
Show properties
idstringOptional

Internal customer ID

Example: "b1wvKrxdDZ11U8tUlyyx"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
namestringOptional

Customer full name

Example: "John Doe"
firstNamestringOptional

Customer first name

Example: "John"
lastNamestringOptional

Customer last name

Example: "Doe"
typestringOptional

Customer type

Example: "member"
pointintegerOptional

Current available points

Example: 100
tierPointintegerOptional

Points used for tier calculation

Example: 100
pendingPointintegerOptional

Points pending approval

Example: 0
totalSpentnumberOptional

Total amount spent

Example: 0
totalEarnedPointsintegerOptional

Lifetime earned points

Example: 100
hasPointbooleanOptional

Whether customer has available points

Example: true
hasJoinedProgrambooleanOptional

Whether customer joined loyalty program

Example: true
orderCountintegerOptional

Number of orders placed

Example: 0
statestringOptional

Account state

Example: "enabled"
latestActivitystring · date-timeOptional

Last activity timestamp

Example: "2025-04-29T10:23:05.990Z"
notificationsobjectOptional

Customer notification preferences

Example: {}
acceptsMarketingbooleanOptional

Marketing consent

Example: false
birthdaystringOptional

Birthday in MM/DD format

Example: "05/15"
dateOfBirthstring · dateOptional

Date of birth in YYYY-MM-DD format

Example: "1990-05-15"
tierIdstringOptional

Current tier ID

Example: "1Fe1kqHZbE7Alx1GmFEC"
tierNamestringOptional

Current tier name

Example: "Bronze"
tierUpdatedAtstring · date-timeOptional

Last tier update timestamp

Example: "2025-06-16T10:20:58.636Z"
phonestringOptional

Phone number

Example: null
pointsRemainintegerOptional

Points needed for next tier

Example: 4900
birthMonthstringOptional

Birth month in MM format

Example: "05"
isCustomerB2BbooleanOptional

Whether customer is B2B

Example: false
earnSignUpbooleanOptional

Whether customer earned signup points

Example: true
referralCodestringOptional

Customer's referral code

Example: "2kxRoqlDQMp"
hasTierbooleanOptional

Whether customer has a tier assigned

Example: false
totalSpentCurrencyCodestringOptional

Currency code for spending

Example: "VND"
createdAtstring · date-timeOptional

Account creation timestamp

Example: "2025-04-29T10:23:05.991Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-16T10:20:58.663Z"
metaobjectOptional

Additional metadata such as counts and pagination

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/customers/external/{shopifyCustomerId}
GET /rest_api/v2/customers/external/{shopifyCustomerId} 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: */*
200Customer details
{
  "success": true,
  "data": {
    "id": "cust_abc123",
    "shopifyCustomerId": "7891234567890",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "point": 150,
    "totalEarnedPoints": 300,
    "hasPoint": true,
    "hasJoinedProgram": true,
    "state": "enabled"
  }
}

Update customer data by Shopify ID

PUT/rest_api/v2/customers/external/{shopifyCustomerId}

Update customer information using Shopify customer ID

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
shopifyCustomerIdpath · stringRequired

Shopify customer ID

Request body
dateOfBirthstring · dateOptional

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

birthdaystringOptional

Birthday in MM/DD format

Responses
200Customer updated successfully
successbooleanOptional
Example: true
dataobjectOptional
Show properties
idstringOptional
shopifyCustomerIdstringOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
PUT/rest_api/v2/customers/external/{shopifyCustomerId}
PUT /rest_api/v2/customers/external/{shopifyCustomerId} 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: 33


{
  "dateOfBirth": "1990-05-15"
}
200Customer updated successfully
{
  "success": true,
  "data": {
    "id": "string",
    "shopifyCustomerId": "string"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer VIP tier

PUT/rest_api/v2/customers/{customerId}/tier

Update customer's VIP tier with comprehensive tier processing

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
customerIdpath · stringRequired

Internal customer ID

Request body
tierIdstringRequired

Target tier ID

isInitTierbooleanOptional

Whether this is an initial tier assignment

triggerRewardbooleanOptional

Whether to trigger tier rewards

adminNotestringOptional

Admin note for the tier change activity

Responses
200Customer tier updated successfully
successbooleanOptional
Example: true
dataobjectOptional
Show properties
idstringOptional
shopifyCustomerIdstringOptional
tierIdstringOptional
tierNamestringOptional
tierPointintegerOptional
tierUpdatedAtstring · date-timeOptional
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 data
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"
404Customer or tier 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"
PUT/rest_api/v2/customers/{customerId}/tier
PUT /rest_api/v2/customers/{customerId}/tier 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: 124


{
  "tierId": "tier_gold_123",
  "isInitTier": false,
  "triggerReward": true,
  "adminNote": "Tier upgraded via REST API"
}
200Customer tier updated successfully
{
  "success": true,
  "data": {
    "id": "string",
    "shopifyCustomerId": "string",
    "tierId": "string",
    "tierName": "string",
    "tierPoint": 1,
    "tierUpdatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer VIP tier by Shopify ID

PUT/rest_api/v2/customers/external/{shopifyCustomerId}/tier

Update customer's VIP tier using Shopify customer ID

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
shopifyCustomerIdpath · stringRequired

Shopify customer ID

Request body
tierIdstringRequired

Target tier ID

isInitTierbooleanOptional

Whether this is an initial tier assignment

triggerRewardbooleanOptional

Whether to trigger tier rewards

adminNotestringOptional

Admin note for the tier change activity

Responses
200Customer tier updated successfully
successbooleanOptional
Example: true
dataobjectOptional
Show properties
idstringOptional
shopifyCustomerIdstringOptional
tierIdstringOptional
tierNamestringOptional
tierPointintegerOptional
tierUpdatedAtstring · date-timeOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
PUT/rest_api/v2/customers/external/{shopifyCustomerId}/tier
PUT /rest_api/v2/customers/external/{shopifyCustomerId}/tier 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: 56


{
  "tierId": "tier_gold_123",
  "triggerReward": true
}
200Customer tier updated successfully
{
  "success": true,
  "data": {
    "id": "string",
    "shopifyCustomerId": "string",
    "tierId": "string",
    "tierName": "string",
    "tierPoint": 1,
    "tierUpdatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
ProgramsActivities
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.