Fetch Loyalty Program Information
On a brand integrated with Punchh, GET /dlc-service/loyalty-program returns how the brand's loyalty program is set up: which kind of program it is, what the points convert into, and what to show on the loyalty card.
Request
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/dlc-service/loyalty-program",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"loyalty_program": {
"point_name": "",
"program_type": "points_convert_to_currency",
"description": "",
"faq_link": "",
"tos_link": "",
"card_code_type": "",
"scanner_code_type": "barcode",
"points_conversion_threshold": 50,
"currency_earned": 500,
"channels": [
{
"type_id": 3,
"reference_type": "DiscountMobileChannel"
},
{
"type_id": 5,
"reference_type": "DiscountPosIntegratedChannel"
},
{
"type_id": 1,
"reference_type": "DiscountPosChannel"
},
{
"type_id": 4,
"reference_type": "DiscountWebChannel"
},
{
"type_id": 2,
"reference_type": "DiscountKioskChannel"
}
],
"venue_ids": [
"1bced40f-95f8-441a-b02c-1f843f166820",
"bf1f796b-29c7-4e40-b05a-22f1886349ea",
"017b65dd-ba5e-411d-a114-8b5202956bd9",
"fa4d8537-22ab-4f0b-9b73-b25888b1850d",
"2bc1b91b-867b-403b-81e0-cd631637a36c",
"303de73c-81d2-401b-a726-eb752b0f689d",
"c221247b-5354-42e5-bdf2-c5a7a10e08a9",
"8666ec5d-89ff-4fc6-9cd1-d6cdb9568d57",
"230db645-2fdc-4582-865a-e2ff4c99b466",
"770e6d7c-f2b4-4ada-a48d-fb2657054a78",
"e1fe934e-dd5e-4548-8fe2-8251152c1902",
"b097222b-e314-4b7c-9747-7657e33a530c",
"fbbb606a-4121-406e-91f2-b801f7be14df",
"00e24f0b-c484-459d-93ba-6cca04a5ed54",
"6b76962a-7a42-4cf2-999c-1aa78c2547f4",
"c6baa105-d60d-44b7-8683-f80d82d978e6",
"e834616a-a61a-469c-ad72-8c799c86a138",
"0bcc5d17-cb7b-437f-acbc-4042def639ea",
"b3f599c8-40e5-4d08-8dd3-45d55f12af6d",
"34dce43f-078e-4272-be28-317bee4192ed"
],
"show_reward_tiers": false,
"reward_tiers": [],
"base_redeemable": []
}
}
}
| Property | Value | Description |
|---|---|---|
program_type |
String | Punchh only. One of points_convert_to_currency, points_convert_to_reward, points_unlock_redeemables, surprise_and_delight |
card_code_type |
String | barcode, qr_code or empty. How to draw the customer's loyalty card |
scanner_code_type |
String | Punchh only. barcode, qr_code or empty. What the customer scans from an in-store receipt |
points_conversion_threshold |
Number | Punchh points_convert_to_currency and points_convert_to_reward programs. Points needed for one conversion |
currency_earned |
Number | Punchh points_convert_to_currency programs. Currency banked per conversion, in minor units |
base_redeemable |
JSON | Punchh points_convert_to_reward programs. The reward granted per conversion: name, image_url, redeemable_properties (filter tags) and meta_data |
channels |
List | Channels the program is enabled on, as { type_id, reference_type }: 1 DiscountPosChannel, 2 DiscountKioskChannel, 3 DiscountMobileChannel, 4 DiscountWebChannel, 5 DiscountPosIntegratedChannel. Punchh programs have all five |
venue_ids |
List | Stores where loyalty is enabled. Hide loyalty UI and skip loyalty calls at any other store |
show_reward_tiers |
Boolean | Whether to group rewards into tiers in the UI |
reward_tiers |
List | The point values of those tiers |
faq_link, tos_link |
String | PAR Ordering loyalty only. Links to the program's FAQ and terms |
point_name, description |
String | Deprecated |
program_type tells you which of the four Punchh program types the brand runs:
-
Points unlock redeemables - Guests choose which redeemables to spend their points on. For example, your business may provide three redeemables: one at 30 points, one at 50 points, and one at 100 points. The guest accumulates points at each check in and chooses when and how to spend those points to unlock specific redeemables. When a guest unlocks a redeemable, the points are deducted from their account.
-
Points convert to rewards - Guests automatically unlock rewards at predefined point thresholds. For example, your business may provide three reward thresholds: one at 30 points, one at 50 points, and one at 100 points. When a guest reaches 30 points, the first reward is offered to them automatically. The points don’t deduct and when the guest reaches 50 points, the next reward is made available to them, and so on.
-
Points convert to currency - Guests automatically receive rewards at one predefined point threshold. For example, your business may provide a reward threshold of 30 points. When a guest reaches 30 points, the points are automatically converted into the reward and deducted from their account.
-
Visit-based - Guest points are based on the number of visits. A certain number of visits earns the guest a redeemable card, which represents a redeemable that your business has configured.
What the customer can do with their points depends on the program type. Punchh Offers and Program Types describes each type in full.
Points unlock redeemables program
On a points_unlock_redeemables program the customer spends points on rewards. Fetch the rewards with GET /dlc-service/loyalty-rewards.
Points convert to currency program
On a points_convert_to_currency program the customer spends the currency they have banked. Apply it on the cart with Update Cart; the response comes back priced.
card_code_type tells you whether to draw the loyalty card as a QR code or a barcode for the POS to scan; scanner_code_type tells you which of the two to expect when the customer scans a receipt code.
On the Points convert to currency and Points convert to rewards programs, points_conversion_threshold is the number of points that convert — into the amount in currency_earned, or into the reward in base_redeemable. For example, 100 points become $10 on a currency program, or 50 points become a free burger on a rewards program.
Every channel is enabled on a Punchh program. The stores that take part in the program are listed in venue_ids.
To know whether to display the loyalty rewards in tiers (i.e., grouped by their reward point cost), the show_reward_tiers and reward_tiers properties are used.
