Programs

Earning and spending programs management

Get earning programs

get

/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

successbooleanOptionalExample: true

messagestringOptionalExample: Operation completed successfully

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

403

Plan upgrade required

application/json

500

Internal server error

application/json

get

/rest_api/v2/programs/earning

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

/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

successbooleanOptionalExample: true

messagestringOptionalExample: Operation completed successfully

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

404

Customer not found

application/json

get

/rest_api/v2/programs/earning/eligibility

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

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

Calculate points that would be earned for given products

Body

shopifyCustomerIdstringOptional

sourceNamestringOptionalDefault: web

Responses

200

Calculated points

application/json

successbooleanOptionalExample: true

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/points/calculate

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

post

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

Process social media interactions for earning points

Body

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

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

/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

successbooleanOptionalExample: true

messagestringOptionalExample: Operation completed successfully

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

get

/rest_api/v2/programs/redemption

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

/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

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

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

404

Program not found

application/json

get

/rest_api/v2/programs/{programId}

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

/rest_api/v2/programs/redemption/redeem

Redeem customer points for rewards through a redemption program

Body

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

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

PreviousAPI references NextCustomers

Last updated 2 months ago

hashtagGet earning programs

hashtagGet programs by customer eligibility

hashtagCalculate earning points

hashtagHandle social earning interactions

hashtagGet redemption programs

hashtagGet program by ID

hashtagRedeem points for rewards

Get earning programs

Get programs by customer eligibility

Calculate earning points

Handle social earning interactions

Get redemption programs

Get program by ID

Redeem points for rewards