User guide

Programs

Earning and spending programs management

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
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",
      "description": "Get points for creating an account",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "earnPoint": 100,
      "rateMoney": 1,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z"
    },
    {
      "id": "prog_earning_002",
      "title": "Place Order Reward",
      "description": "Earn points for every purchase",
      "type": "earning",
      "event": "place_order",
      "status": true,
      "earnBy": "price",
      "earnPoint": 1,
      "rateMoney": 1,
      "appliedPlaceOrderTo": "all",
      "appliedSource": [
        "web",
        "pos"
      ],
      "autoRemovePoints": false,
      "skipEarnPointGuest": false,
      "roundingMethod": "round",
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-25T16:20:45.000Z"
    }
  ]
}

Get programs by customer eligibility

get

Retrieve earning programs for a specific customer. Single earn event programs (like social media follows, sign up, birthday) will include an isEarned field indicating whether the customer has already earned points from that program.

Customer Identifier Required: Must provide either customerId or shopifyCustomerId parameter.

Query parameters
shopifyCustomerIdstringOptional

Shopify customer ID

customerIdstringOptional

Internal customer ID

Responses
200

Programs for customer with earned status

application/json
Responseall of
get
GET /rest_api/v2/programs/earning/eligibility HTTP/1.1
Host: dev-api.joy.so
Accept: */*

{
  "success": true,
  "data": [
    {
      "id": "prog_earning_001",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "earnPoint": 100,
      "isEarned": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z"
    },
    {
      "id": "prog_earning_002",
      "title": "Place Order",
      "type": "earning",
      "event": "place_order",
      "earnPoint": 10,
      "createdAt": "2024-01-16T08:00:00.000Z",
      "updatedAt": "2024-01-21T10:15:00.000Z"
    },
    {
      "id": "prog_earning_003",
      "title": "Follow Instagram",
      "type": "earning",
      "event": "follow_instagram",
      "earnPoint": 50,
      "isEarned": false,
      "createdAt": "2024-01-16T12:00:00.000Z",
      "updatedAt": "2024-01-21T16:30:00.000Z"
    }
  ]
}

Calculate earning points

post

Calculate points that would be earned for given products

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

Handle social earning interactions

post

Process social media interactions for earning points

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

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": "aYorhxYUTkUKIDZgL1R5",
      "title": "Free Product Test",
      "type": "spending",
      "event": "free_gift",
      "status": true,
      "spendPoint": 200,
      "earnAmount": 700,
      "priority": 0,
      "redeemType": "fixed",
      "appliedTo": "sf_product",
      "redeemIn": "available_in_online_store",
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "totalLimitationRedeem": 0,
      "combinedWith": [
        "orderDiscounts",
        "productDiscounts",
        "shippingDiscounts"
      ],
      "specificProductIds": [
        44438017147115,
        44438017114347
      ],
      "variantIds": [
        44438017147115,
        44438017179883,
        44438017245419,
        44438017114347
      ],
      "specificProducts": [
        {
          "id": 8209413669099,
          "title": "The Complete Snowboard",
          "handle": "the-complete-snowboard",
          "image": {
            "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/Main_589fc064-24a2-4236-9eaf-13b2bd35d21d.jpg?v=1703045153"
          }
        }
      ],
      "giftStatus": "none",
      "expired": false,
      "isDraft": false,
      "createdAt": "2024-08-27T08:09:46.757Z",
      "updatedAt": "2025-06-18T08:13:55.797Z"
    },
    {
      "id": "vIswMZYogmKyw94GzEvn",
      "title": "Points for discounts",
      "type": "spending",
      "event": "amount_discount",
      "status": true,
      "spendPoint": 100,
      "earnAmount": "5",
      "priority": 3,
      "redeemType": "fixed",
      "appliedTo": "sf_product",
      "orderReq": "none",
      "orderReqAmount": 0,
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "combinedWith": [],
      "specificProductIds": [
        44438017114347
      ],
      "conditions": [
        {
          "type": "criteria_customer",
          "field": "customer_country_code",
          "typeMatch": "equal"
        }
      ],
      "giftStatus": "none",
      "expired": false,
      "isDraft": false,
      "createdAt": "2024-10-14T04:36:02.987Z",
      "updatedAt": "2025-06-18T08:13:55.283Z"
    }
  ]
}

Get program by ID

get

Retrieve a specific program by its ID

Path parameters
programIdstringRequired

Program ID

Query parameters
shopifyCustomerIdstringOptional

Shopify customer ID for program limitations

Responses
200

Program details

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

{
  "success": true,
  "data": {
    "id": "aYorhxYUTkUKIDZgL1R5",
    "title": "Free Product Test",
    "type": "spending",
    "event": "free_gift",
    "status": true,
    "spendPoint": 200,
    "earnAmount": 700,
    "priority": 0,
    "redeemType": "fixed",
    "appliedTo": "sf_product",
    "redeemIn": "available_in_online_store",
    "expiredTime": "",
    "userAvailability": "userRedeemed",
    "showLoyaltyPage": true,
    "limitRedeem": "redeemWithoutLimit",
    "totalLimitationRedeem": 0,
    "combinedWith": [
      "orderDiscounts",
      "productDiscounts",
      "shippingDiscounts"
    ],
    "specificProductIds": [
      44438017147115,
      44438017114347
    ],
    "variantIds": [
      44438017147115,
      44438017179883,
      44438017245419,
      44438017114347
    ],
    "specificProducts": [
      {
        "id": 8209413669099,
        "title": "The Complete Snowboard",
        "handle": "the-complete-snowboard",
        "image": {
          "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/Main_589fc064-24a2-4236-9eaf-13b2bd35d21d.jpg?v=1703045153"
        },
        "variants": [
          {
            "id": 44438017147115,
            "price": "700",
            "title": "Ice",
            "inventory_quantity": 10
          }
        ]
      }
    ],
    "giftStatus": "none",
    "expired": false,
    "isDraft": false,
    "createdAt": "2024-08-27T08:09:46.757Z",
    "updatedAt": "2025-06-18T08:13:55.797Z"
  }
}

Redeem points for rewards

post

Redeem customer points for rewards through a redemption program

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
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"
}
PreviousREST API v2NextCustomers