Programs | Joy dev docs

Get programs by customer eligibility

get

Retrieve earning programs for a specific customer with earned status

Query parameters

shopifyCustomerIdstringOptional

Shopify customer ID

customerIdstringOptional

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

Programs for customer with earned status

application/json

Responseall of

404

Customer not found

application/json

get

GET /rest_api/v2/programs/earning/eligibility 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": "prog_abc123",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z",
      "expired": false,
      "isDraft": false,
      "earnBy": "price",
      "rateMoney": 1,
      "earnPoint": 100,
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-12-31T23:59:59.000Z",
      "autoRemovePoints": false,
      "appliedPlaceOrderTo": "all",
      "appliedSource": [
        "web",
        "pos"
      ],
      "excludeProducts": [],
      "includeProducts": [],
      "conditions": [],
      "earnPointsTiers": [],
      "roundingMethod": "round",
      "skipEarnPointGuest": false,
      "translateTitle": {},
      "typeMilestone": "order_based",
      "milestones": [],
      "spendPoint": 500,
      "earnAmount": "10",
      "redeemType": "fixed",
      "appliedTo": "all",
      "appliedCollectionIds": [],
      "redeemIn": "available_in_online_store",
      "orderReq": "none",
      "orderReqAmount": 0,
      "minSpendPoint": "",
      "maxSpendPoint": "",
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "totalLimitationRedeem": 0,
      "combinedWith": [],
      "specificProducts": [],
      "specificProductIds": [],
      "specificCollections": [],
      "variantIds": [],
      "freeProductIds": [],
      "giftStatus": "none",
      "isEarned": true
    }
  ],
  "meta": {
    "count": 1
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get earning programs

get

Retrieve all earning programs for the authenticated shop

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 earning programs

application/json

Responseall of

403

Plan upgrade required or authentication failed

application/json

500

Internal server error

application/json

get

GET /rest_api/v2/programs/earning 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": "prog_earning_001",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "earnPoint": 100,
      "priority": 1,
      "expired": false,
      "isDraft": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z"
    }
  ],
  "meta": {
    "count": 1
  },
  "timestamp": "2024-01-20T14:45:30.000Z"
}

Get redemption programs

get

Retrieve all point spending/redemption programs

Query parameters

shopifyCustomerIdstringOptional

Shopify customer ID for program limitations

eventstring · enumOptional

Filter by program event type

Possible values:

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 spending programs

application/json

Responseall of

get

GET /rest_api/v2/programs/redemption HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*

200

List of spending programs

{
  "success": true,
  "data": [
    {
      "id": "prog_abc123",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z",
      "expired": false,
      "isDraft": false,
      "earnBy": "price",
      "rateMoney": 1,
      "earnPoint": 100,
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-12-31T23:59:59.000Z",
      "autoRemovePoints": false,
      "appliedPlaceOrderTo": "all",
      "appliedSource": [
        "web",
        "pos"
      ],
      "excludeProducts": [],
      "includeProducts": [],
      "conditions": [],
      "earnPointsTiers": [],
      "roundingMethod": "round",
      "skipEarnPointGuest": false,
      "translateTitle": {},
      "typeMilestone": "order_based",
      "milestones": [],
      "spendPoint": 500,
      "earnAmount": "10",
      "redeemType": "fixed",
      "appliedTo": "all",
      "appliedCollectionIds": [],
      "redeemIn": "available_in_online_store",
      "orderReq": "none",
      "orderReqAmount": 0,
      "minSpendPoint": "",
      "maxSpendPoint": "",
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "totalLimitationRedeem": 0,
      "combinedWith": [],
      "specificProducts": [],
      "specificProductIds": [],
      "specificCollections": [],
      "variantIds": [],
      "freeProductIds": [],
      "giftStatus": "none"
    }
  ],
  "meta": {
    "count": 1
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Calculate earning points

post

Calculate points that would be earned for given products

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

shopifyCustomerIdstringOptional

sourceNamestringOptionalDefault: web

Responses

200

Calculated points

application/json

Responseall of

post

POST /rest_api/v2/programs/earning/points/calculate 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: 97

{
  "products": [
    {
      "id": "text",
      "quantity": 1,
      "price": 1
    }
  ],
  "shopifyCustomerId": "text",
  "sourceName": "web"
}

200

Calculated points

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

post

Process social media interactions for earning points

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

shopifyCustomerIdstringRequired

eventstringOptional

earningIdstringOptional

Responses

200

Social earning processed

application/json

post

POST /rest_api/v2/programs/earning/social/interactions 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: 62

{
  "shopifyCustomerId": "text",
  "event": "text",
  "earningId": "text"
}

200

Social earning processed

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

Redeem points for rewards

post

Redeem customer points for rewards through a redemption program

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

programIdstringRequired

shopifyCustomerIdstringRequired

quantityintegerOptionalDefault: 1

Responses

200

Redemption successful

application/json

post

POST /rest_api/v2/programs/redemption/redeem 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: 60

{
  "programId": "text",
  "shopifyCustomerId": "text",
  "quantity": 1
}

200

Redemption successful

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

Get programs by customer eligibility

Get earning programs

Get redemption programs

Calculate earning points

Handle social earning interactions

Redeem points for rewards