User guide

Customers

Customer data and management

Get customers with pagination

get
Query parameters
beforestringOptional

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

afterstringOptional

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

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",
      "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
Path parameters
customerIdstringRequired

Internal customer ID

Responses
200

Customer details

application/json
Responseall of
get
GET /rest_api/v2/customers/{customerId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*

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

Update customer information (supports birthday fields)

Path parameters
customerIdstringRequired

Internal customer ID

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
Content-Type: application/json
Accept: */*
Content-Length: 28

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

Get customer by external ID

get

Retrieve customer information using external system ID (e.g., Shopify customer ID)

Path parameters
externalIdstringRequired

External customer ID (e.g., Shopify customer ID)

Responses
200

Customer details

application/json
Responseall of
get
GET /rest_api/v2/customers/external/{externalId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

Customer details

{
  "success": true,
  "data": {
    "id": "cust_def456",
    "shopifyCustomerId": 7891234567891,
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "point": 225,
    "pointsRemain": 275,
    "tierId": "tier_silver_456",
    "tierName": "Silver",
    "createdAt": "2023-07-10T14:20:00.000Z",
    "updatedAt": "2023-07-27T15:45:32.456Z"
  }
}

Get customer earned points

get

Retrieve total points earned by a customer across all programs

Path parameters
customerIdstringRequired

Customer ID (can be internal ID or Shopify customer ID)

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
Accept: */*
200

Customer 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

Retrieve customer information using Shopify customer ID

Path parameters
shopifyCustomerIdstringRequired

Shopify customer ID

Responses
200

Customer details

application/json
Responseall of
get
GET /rest_api/v2/customers/external/{shopifyCustomerId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*

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

Update customer information using Shopify customer ID

Path parameters
shopifyCustomerIdstringRequired

Shopify customer ID

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
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "dateOfBirth": "1990-05-15"
}
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

put

Update customer's VIP tier with comprehensive tier processing

Path parameters
customerIdstringRequired

Internal customer ID

Body
tierIdstringRequired

Target tier ID

isInitTierbooleanOptional

Whether this is an initial tier assignment

Default: false
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
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "tierId": "tier_gold_123",
  "isInitTier": false,
  "triggerReward": true,
  "adminNote": "Tier upgraded via REST API"
}
{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text",
    "tierId": "text",
    "tierName": "text",
    "tierPoint": 1,
    "tierUpdatedAt": "2025-10-03T23:07:43.275Z"
  },
  "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

Body
tierIdstringRequired

Target tier ID

isInitTierbooleanOptional

Whether this is an initial tier assignment

Default: false
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
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "tierId": "tier_gold_123",
  "triggerReward": true
}
200

Customer tier updated successfully

{
  "success": true,
  "data": {
    "id": "text",
    "shopifyCustomerId": "text",
    "tierId": "text",
    "tierName": "text",
    "tierPoint": 1,
    "tierUpdatedAt": "2025-10-03T23:07:43.275Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
PreviousProgramsNextActivities