Programs

Earning and spending programs management

Get earning programs

get

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

/rest_api/v2/programs/earning

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

403

Plan upgrade required

application/json

500

Internal server error

application/json

get

/rest_api/v2/programs/earning

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/earning/eligibility

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

404

Customer not found

application/json

get

/rest_api/v2/programs/earning/eligibility

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/earning/points/calculate

Calculate points that would be earned for given products

Body

application/json

shopifyCustomerIdstringOptional

sourceNamestringOptionalDefault: web

Responses

200

Calculated points

application/json

post

/rest_api/v2/programs/earning/points/calculate

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/earning/social/interactions

Process social media interactions for earning points

Body

application/json

shopifyCustomerIdstringRequired

eventstringOptional

earningIdstringOptional

Responses

200

Social earning processed

application/json

successbooleanOptionalExample: true

dataobjectOptional

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

post

/rest_api/v2/programs/earning/social/interactions

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/redemption

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

get

/rest_api/v2/programs/redemption

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/{programId}

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

404

Program not found

application/json

get

/rest_api/v2/programs/{programId}

HTTPcURLJavaScriptPython

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

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

/rest_api/v2/programs/redemption/redeem

Redeem customer points for rewards through a redemption program

Body

application/json

programIdstringRequired

shopifyCustomerIdstringRequired

quantityintegerOptionalDefault: 1

Responses

200

Redemption successful

application/json

successbooleanOptionalExample: true

dataobjectOptional

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

post

/rest_api/v2/programs/redemption/redeem

HTTPcURLJavaScriptPython

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