User guide

Earning programs

Get all earning programs available to all or specific customers

List programs

get

Get a list of all earning programs.

Header parameters
X-Joy-Loyalty-App-KeystringOptional

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringOptional

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Responses
200
OK
application/json
get
GET /rest_api/v1/earning HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

OK

{
  "data": [
    {
      "showLoyaltyPage": true,
      "social": "telegram",
      "urlLocation": "",
      "limitUnit": "lifetime",
      "urlAccount": "https://t.me/joinchat",
      "title": "Join Telegram",
      "type": "earning",
      "priority": 24,
      "earnPoint": 100,
      "signUpGuide": "",
      "enabledAntiCheat": false,
      "hasLimit": true,
      "action": "join",
      "earnPointsTiers": {
        "0d3c2cea-e35a-411f-b3ba-f631bb57e653": {
          "earnPoint": 100,
          "limitUnit": "lifetime"
        }
      },
      "shopId": "tDWV2ZZn5Vv1vqu6ikqM",
      "event": "join_telegram",
      "startDate": "2024-10-02",
      "expired": false,
      "id": "5ZPAfgWnepkwxNuVwO2F",
      "changeProgramTitle": false,
      "isDraft": false,
      "rateMoney": "1",
      "translateTitle": {},
      "createdAt": "2024-10-02T09:35:38.230Z",
      "giftStatus": "none",
      "status": false,
      "updatedAt": "2024-10-17T07:16:35.567Z"
    }
  ]
}

Get an earning program

get

Retrieve an earning program by its ID.

Path parameters
programIdstringRequired
Header parameters
X-Joy-Loyalty-App-KeystringOptional

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringOptional

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Responses
200
OK
application/json
get
GET /rest_api/v1/earning/{programId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

OK

{
  "success": true,
  "program": {
    "id": "VHXPHriWMQlJYSBZbLmR",
    "limitUnit": "minute",
    "includeProducts": [],
    "autoRemovePoints": true,
    "earnBy": "price",
    "type": "earning",
    "title": "Place Order",
    "priority": 1,
    "productPointsCalculator": {
      "color": "#8F00C1",
      "fontSize": 14,
      "type": "congratulation",
      "font": "Noto+Sans"
    },
    "earnPoint": 10,
    "hasLimit": false,
    "typeProductMatch": "all",
    "priorityPlaceOrder": 1,
    "typeCondition": "all",
    "statusProductPointsCalculator": false,
    "shopId": "nDaevBKY0zGCzmJz8mCv",
    "event": "place_order",
    "conditions": [
      {
        "field": "title",
        "typeMatch": "contains",
        "content": ""
      }
    ],
    "excludeProducts": [],
    "statusUseCondition": false,
    "status": true,
    "limitInterval": 1,
    "createdAt": "2023-07-14T04:06:21.048Z",
    "rateMoney": 1,
    "updatedAt": "2023-07-14T04:07:23.364Z",
    "appliedCollectionIds": []
  }
}

List all earning programs available to a specific customer

get
Query parameters
customerIdstringOptional

At least one of customerId or shopifyCustomerId is required. priority

Example: {{customerId}}
Header parameters
X-Joy-Loyalty-App-KeystringOptional

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringOptional

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
stringOptional
Responses
200
OK
application/json
get
GET /rest_api/v1/earning-programs-by-customer HTTP/1.1
Host: dev-api.joy.so
Accept: */*
200

OK

{
  "data": [
    {
      "id": "4c34m1vNgXivLXJmrEFB",
      "excludePOSOrderProducts": false,
      "limitUnit": "minute",
      "includeProducts": [],
      "rateMoney": 100,
      "autoRemovePoints": true,
      "earnBy": "price",
      "type": "earning",
      "title": "Place Order",
      "excludeOSOrderProducts": false,
      "priority": 0,
      "hasLimit": false,
      "typeProductMatch": "all",
      "typeCondition": "all",
      "shopId": "umN0f3GKyQC3XS1AwVWg",
      "event": "place_order",
      "conditions": [
        {
          "field": "title",
          "typeMatch": "contains",
          "content": ""
        }
      ],
      "limitInterval": 1,
      "giftStatus": "none",
      "status": true,
      "excludeProducts": [
        {
          "image": {
            "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/gift_card.png?v=1703045153"
          },
          "images": [
            {
              "updated_at": "2023-12-19T23:05:53-05:00",
              "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/gift_card.png?v=1703045153",
              "product_id": 8209413800171,
              "admin_graphql_api_id": "gid://shopify/ProductImage/40721516593387",
              "alt": "Gift card that shows text: Generated data gift card",
              "width": 2881,
              "created_at": "2023-12-19T23:05:53-05:00",
              "variant_ids": [],
              "id": 40721516593387,
              "position": 1,
              "height": 2881
            }
          ],
          "options": [
            {
              "product_id": 8209413800171,
              "values": [
                "$10",
                "$25",
                "$50",
                "$100"
              ],
              "name": "Denominations",
              "id": 10444919046379,
              "position": 1
            }
          ],
          "handle": "gift-card",
          "id": 8209413800171,
          "variants": [
            {
              "inventory_quantity": 0,
              "src": "https://cdn.shopify.com/s/files/1/0680/3950/8203/products/gift_card.png?v=1703045153",
              "price": "10",
              "option3": null,
              "option1": "$10",
              "id": 44438017409259,
              "option2": null,
              "title": "$10"
            }
          ],
          "title": "Gift Card"
        }
      ],
      "statusUseCondition": true,
      "changeProgramTitle": false,
      "expired": false,
      "isDraft": false,
      "appliedPlaceOrderTo": "all",
      "earnPoint": 12,
      "earnPointsTiers": {
        "1Fe1kqHZbE7Alx1GmFEC": {
          "earnPoint": 12
        }
      },
      "createdAt": "2023-12-20T04:16:40.318Z",
      "translateTitle": "وضع الطلب",
      "updatedAt": "2024-08-30T09:50:37.994Z",
      "isEarned": false
    }
  ]
}

Calculate Earning Points

post

Calculate the points a user would earn for a given activity without actually awarding the points.

Header parameters
X-Joy-Loyalty-App-KeystringOptional

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringOptional

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}
Body
shopifyCustomerIdnumberOptional
sourceNamestring · enumOptionalPossible values:
Responses
200
OK
application/json
post
POST /rest_api/v1/earn/calc-points HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "products": [
    {
      "id": 8209413964011,
      "quantity": 1,
      "price": 630
    }
  ]
}
200

OK

{
  "data": {
    "pointsEarn": 264,
    "products": [
      {
        "title": "The Multi-managed Snowboard",
        "vendor": "Multi-managed Vendor",
        "tags": [
          "Premium",
          "Snow",
          "Snowboard",
          "Sport",
          "Winter"
        ],
        "variants": {
          "nodes": [
            {
              "id": "gid://shopify/ProductVariant/44438017671403"
            }
          ]
        },
        "resourcePublicationsV2": {
          "nodes": [
            {
              "publication": {
                "name": "Online Store"
              }
            }
          ]
        },
        "published_scope": "web",
        "id": 8209413964011,
        "type": "",
        "collections": [
          {
            "title": "Automated Collection",
            "published_scope": "web"
          }
        ]
      }
    ]
  },
  "success": true
}

Social Interaction Points

post

Calculate and award points for a social interaction activity.

Header parameters
X-Joy-Loyalty-App-KeystringOptional

App ID of your shop which is retrieved from the Settings page

Example: {{appKey}}
X-Joy-Loyalty-Secret-KeystringOptional

Secret Key of your shop which is retrieved from the Settings page

Example: {{secretKey}}
Body
shopifyCustomerIdnumberRequired
earningIdnumberRequired
Responses
200
OK
application/json
post
POST /rest_api/v1/earn/interact-social HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "shopifyCustomerId": 7106943058056,
  "earningId": "Y224ET3WNTuVHbEf0nib"
}
200

OK

{
  "success": true,
  "data": {
    "newPoint": 100
  }
}
PreviousCustomersNextRedeeming programs

Last updated