Customers

Customer data and management

Get customers with pagination

get

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

/rest_api/v2/customers

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

get

/rest_api/v2/customers

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/customers/{customerId}

Path parameters

customerIdstringRequired

Internal customer ID

Responses

200

Customer details

application/json

404

Customer not found

application/json

get

/rest_api/v2/customers/{customerId}

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/customers/{customerId}

Update customer information (supports birthday fields)

Path parameters

customerIdstringRequired

Internal customer ID

Body

application/json

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

400

Invalid request data

application/json

404

Customer not found

application/json

put

/rest_api/v2/customers/{customerId}

HTTPcURLJavaScriptPython

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 earned points

get

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

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

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

get

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

HTTPcURLJavaScriptPython

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

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

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

Retrieve customer information using Shopify customer ID

Path parameters

shopifyCustomerIdstringRequired

Shopify customer ID

Responses

200

Customer details

application/json

404

Customer not found

application/json

get

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

HTTPcURLJavaScriptPython

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

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

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

Update customer information using Shopify customer ID

Path parameters

shopifyCustomerIdstringRequired

Shopify customer ID

Body

application/json

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

put

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

HTTPcURLJavaScriptPython

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

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

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

Update customer's VIP tier with comprehensive tier processing

Path parameters

customerIdstringRequired

Internal customer ID

Body

application/json

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

400

Invalid request data

application/json

404

Customer or tier not found

application/json

put

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

HTTPcURLJavaScriptPython

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": "2026-01-06T23:57:27.150Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update customer VIP tier by Shopify ID

put

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

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

Update customer's VIP tier using Shopify customer ID

Path parameters

shopifyCustomerIdstringRequired

Shopify customer ID

Body

application/json

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

put

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

HTTPcURLJavaScriptPython

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": "2026-01-06T23:57:27.150Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}