Punchh

Use Rewards, Offers, Customer Credits, and Promo Codes

Rewards

How to use rewards for an online order

To fetch loyalty rewards available for customers, make an HTTP GET request to the following endpoint:/dlc-service/loyalty-rewards

Request 

{
  "method": "get",
  "url": "https://api-public-playground.menu.app/api/dlc-service/loyalty-rewards",
  "headers": {
    "X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
    "Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
    "Api-Version": 4.38.0,
    "Content-Type": "application/json"
  }
}

Response 

{
    "status": "OK",
    "code": 200,
    "data": {
        "discounts": [
            {
                "id": 46168,
                "type_id": 2,
                "reference_type": "LoyaltyReward",
                "brand_id": null,
                "position": null,
                "name": "Reward with cart spent condition",
                "description": "Spend 20$ and get 5$ off",
                "tracking_code": null,
                "max_redemption_count": null,
                "date_from": null,
                "date_to": null,
                "reduction_type": 0,
                "reduction_level_type": 0,
                "reduction_price": 0,
                "reduction_amount": 0,
                "reduction_percentage": null,
                "is_registered_only": false,
                "show_only_in_ordering_flow": null,
                "image": {
                    "fullsize": "https://res.cloudinary.com/punchh/image/upload/c_limit,f_auto,fl_lossy,g_center,q_auto/v1/punchhstatic/redeemables/redeemable_images/000/046/168/original/b63aa56ee7848bbb5ed6b88de9fbcd97e992d228.jpeg",
                    "thumbnail_medium": "https://res.cloudinary.com/punchh/image/upload/c_limit,f_auto,fl_lossy,g_center,q_auto/v1/punchhstatic/redeemables/redeemable_images/000/046/168/original/b63aa56ee7848bbb5ed6b88de9fbcd97e992d228.jpeg",
                    "thumbnail_small": "https://res.cloudinary.com/punchh/image/upload/c_limit,f_auto,fl_lossy,g_center,q_auto/v1/punchhstatic/redeemables/redeemable_images/000/046/168/original/b63aa56ee7848bbb5ed6b88de9fbcd97e992d228.jpeg"
                },
                "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"
                    }
                ],
                "discount_tags": [],
                "discount_conditions": null,
                "translations": null,
                "created_at": "",
                "updated_at": "",
                "point_cost": 30
            },
            {
                "id": 47200,
                "type_id": 2,
                "reference_type": "LoyaltyReward",
                "brand_id": null,
                "position": null,
                "name": "Free Moringa Bowl",
                "description": "POS QA testing",
                "tracking_code": null,
                "max_redemption_count": null,
                "date_from": null,
                "date_to": null,
                "reduction_type": 0,
                "reduction_level_type": 0,
                "reduction_price": 0,
                "reduction_amount": 0,
                "reduction_percentage": null,
                "is_registered_only": false,
                "show_only_in_ordering_flow": null,
                "image": {
                    "fullsize": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_medium": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_small": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png"
                },
                "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"
                    }
                ],
                "discount_tags": [],
                "discount_conditions": null,
                "translations": null,
                "created_at": "",
                "updated_at": "",
                "point_cost": 50
            },
       ]
    }
}

Property Value Description
discounts JSON Contains all properties related to a punchh loyalty reward.
id Number It indicates the internal id of the discount.
type_id Number Possible values: 2. It indicates the type of discount being a loyalty reward.
reference_type String Possible values: "LoyaltyReward". It indicates the type of discount being a loyalty reward.
brand_id Null Not supported in punchh
position Null Not supported in punchh
name String The name of the loyalty reward.
description String The description of the loyalty reward.
tracking_code Null Not supported in punchh
max_redemption_count Null Not supported in punchh
date_from Null Not supported in punchh
date_to Null Not supported in punchh
reduction_type Null Not supported in punchh
reduction_level_type Null Not supported in punchh
reduction_price Null Not supported in punchh
reduction_amount Null Not supported in punchh
reduction_percentage Null Not supported in punchh
is_registered_only False Not supported in punchh
show_only_in_ordering_flow Null Not supported in punchh
image JSON Object containing image URL links.
fullsize String URL link for a fullsize image
thumbnail_medium String URL link for a medium thumbnail image.
thumbnail_small String URL link for a small thumbnail image.
channels Array Array containing channels the reward can be redeemed on. Always returns all 5 channels: web, mobile, kiosk, pos, posintegrated
type_id Number Possible values: 1, 2, 3, 4, 5. It refers to the channel id that a reward can be redeemed on.
reference_type String Possible values:
"DiscountPosChannel", "DiscountKioskChannel", "DiscountMobileChannel", "DiscountWebChannel", "DiscountPosIntegratedChannel"
discount_tags Array Not supported in punchh
discount_conditions Null Not supported in punchh
translations Null Not supported in punchh
created_at Null Not supported in punchh
updated_at Null Not supported in punchh
point_cost Number Number of points required to redeem reward.

When a customer adds a reward to their cart, you need to calculate the appropriate discount or benefits associated with that reward. To achieve this, make an HTTP POST request to the calculate endpoint with the necessary information, including the selected reward with the type_id: 2 in the discounts object and the cart details:

/orders/calculate

If successful, the reward is calculated and applied to the cart and the customer can proceed to place the order. To create the order with the selected reward, make an HTTP POST request to the following endpoint:

/orders

After order creation the backend will internally call Punchh service to validate the redemption and update the point balance of the user.

Offers

How to use offers for an online order

To fetch loyalty offers available for customers, make an HTTP GET request to the following endpoint: /dlc-service/loyalty-promotions

Request 

{
  "method": "get",
  "url": "https://api-public-playground.menu.app/api/dlc-service/loyalty-promotions",
  "headers": {
    "X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
    "Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
    "Api-Version": 4.38.0,
    "Content-Type": "application/json",
    "Dlc-Authorization": ""
  }
}

Response 

{
    "status": "OK",
    "code": 200,
    "data": {
        "discounts": [
            {
                "id": 9968351573,
                "type_id": 3,
                "reference_type": "Promotion",
                "brand_id": 0,
                "position": 0,
                "name": "Reduced price for Lápana Bowl and Smoothie ",
                "description": "",
                "tracking_code": "",
                "max_redemption_count": 0,
                "date_from": null,
                "date_to": null,
                "reduction_type": 0,
                "reduction_level_type": 0,
                "reduction_price": 0,
                "reduction_amount": 0,
                "reduction_percentage": 0,
                "is_registered_only": false,
                "show_only_in_ordering_flow": false,
                "image": {
                    "fullsize": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_medium": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_small": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png"
                },
                "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"
                    }
                ],
                "discount_tags": [],
                "discount_conditions": [
                    {
                        "id": 0,
                        "type_id": 1,
                        "reference_type": "DiscountConditionSpecificStore",
                        "discount_id": 9968351573,
                        "properties": {
                            "venue_ids": [
                                2809,
                                2833,
                                2836,
                                2995,
                                2996
                            ]
                        }
                    }
                ],
                "translations": null,
                "created_at": "2023-07-26T06:33:12-05:00",
                "updated_at": "",
                "venue_codes": []
            },
            {
                "id": 9968376108,
                "type_id": 3,
                "reference_type": "Promotion",
                "brand_id": 0,
                "position": 0,
                "name": "Reduced price for Passion Mango",
                "description": "",
                "tracking_code": "",
                "max_redemption_count": 0,
                "date_from": null,
                "date_to": null,
                "reduction_type": 0,
                "reduction_level_type": 0,
                "reduction_price": 0,
                "reduction_amount": 0,
                "reduction_percentage": 0,
                "is_registered_only": false,
                "show_only_in_ordering_flow": false,
                "image": {
                    "fullsize": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_medium": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png",
                    "thumbnail_small": "https://res.cloudinary.com/punchh/image/upload/fl_lossy,q_auto/v1/static/punchh-icon-thumb.png"
                },
                "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"
                    }
                ],
                "discount_tags": [],
                "discount_conditions": [
                    {
                        "id": 0,
                        "type_id": 1,
                        "reference_type": "DiscountConditionSpecificStore",
                        "discount_id": 9968376108,
                        "properties": {
                            "venue_ids": [
                                2809
                            ]
                        }
                    }
                ],
                "translations": null,
                "created_at": "2023-07-26T06:33:25-05:00",
                "updated_at": "",
                "venue_codes": [
                    "11"
                ]
            }
        ]
    }
}

Property Value Description
discounts JSON Contains all properties related to a punchh promotion.
id Number It indicates the internal id of the discount.
type_id Number Possible values: 3. It indicates the type of discount being a promotion.
reference_type String Possible values: "Promotion". It indicates the type of discount being a loyalty promotion.
brand_id Null Not supported in punchh.
position Null Not supported in punchh.
name String The name of the promotion.
description String The description of the promotion.
tracking_code Null Not supported in punchh.
max_redemption_count Null Not supported in punchh.
date_from Null Not supported in punchh.
date_to Date Date when the promotion will expire and can no longer be used.
reduction_type Null Not supported in punchh.
reduction_level_type Null Not supported in punchh.
reduction_price Null Not supported in punchh.
reduction_amount Null Not supported in punchh.
reduction_percentage Null Not supported in punchh.
is_registered_only False Not supported in punchh.
show_only_in_ordering_flow Null Not supported in punchh.
image JSON Object containing image URL links.
fullsize String URL link for a fullsize image.
thumbnail_medium String URL link for a medium thumbnail image.
thumbnail_small String URL link for a small thumbnail image.
channels Array Array containing channels the promotion can be redeemed on. Always returns all 5 channels: web, mobile, kiosk, pos, posintegrated
type_id Number Possible values: 1, 2, 3, 4, 5. It refers to the channel id that a promotion can be redeemed on.
reference_type String Possible values:
"DiscountPosChannel", "DiscountKioskChannel", "DiscountMobileChannel", "DiscountWebChannel", "DiscountPosIntegratedChannel"
discount_tags Array Not supported in punchh.
discount_conditions Null Not supported in punchh.
translations Null Not supported in punchh.
created_at Null Not supported in punchh.
updated_at Null Not supported in punchh.
venue_codes Array Array of venue_ids that the promotion can be redeemed at. If empty, it can be redeemed at all locations.

When a customer adds an offer to their cart, you need to calculate the appropriate discount or benefits associated with that offer. To achieve this, make an HTTP POST request to the calculate endpoint with the necessary information, including the selected offer with the type_id: 3 in the Discount object and the cart details:

/orders/calculate

If successful, the offer is calculated and applied to the cart, the customer can proceed to place the order. To create the order with the selected offer, make an HTTP POST request to the following endpoint:

/orders

Customer's Credit

How to redeem a credit for an online transaction

In order to redeem a customer’s credit against an order, a discounts property must be populated for the calculate and orders endpoints.

The calculate endpoint request payload should include a discounts property with an array value that includes an object {discount_amount: amount_of_discount} where amount_of_discount equals the amount in cents. E.g. {discount_amount: 1200} for $12 credit discount.

The orders endpoint request payload should include the same discounts property as above.

Promo Codes

How to use unlock-in-app and direct-at-pos promo codes

The direct-at-pos coupon is validated first by calling the calculate endpoint: /orders/calculate

with the redemption code included in the request body in the discount object as a discount: {redemption_code: code, type_id: 0} where code is the value of the direct-at-pos promo code.

If successful for a direct-at-pos promo code, the discount amount is added to the calculate object.

If not successful, then the following endpoint is called: loyalty-coupons

with a request payload that includes the object {code: code_value} where code_value equals the promo code value as configured in Punchh.

If successful, the loyalty promotions can be re-fetched using the following endpoint: /dlc-service/loyalty-promotions

Previous
Fetch Loyalty Related Customer Information
Next
Extenal Discounts