Use Rewards, Offers, Customer Credits, and Promo Codes
Updating the cart only prices the reward, offer, credit, or code. Placing the order redeems it in Punchh and checks the customer in. Canceling the order voids that redemption.
Authenticating to Punchh
Punchh is authenticated with its own header, Dlc-Authorization. Your Authorization header is the PAR Ordering customer token and does not authenticate you to Punchh.
When to send it depends on who the customer is:
- A signed-in registered customer: send it on every cart call. Any cart with at least one item triggers a loyalty calculation against Punchh, whether or not a discount is on the cart. Order creation additionally sends the loyalty check-in.
- A guest: send it only when the cart carries a reward, offer, credit or promo code. Nothing else in a guest cart reaches Punchh, and a guest order skips the check-in.
These are the calls it applies to:
PUT /cart/{cart_id}POST /cart/{cart_id}/checkoutPOST /cart/{cart_id}/transfer-venuePOST /cart/{cart_id}/order
Group carts follow the same rule, applied per caller. Loyalty is evaluated for whoever the request is authenticated as, so every caller sends their own Punchh token and never anybody else's:
- The host sends the host's token on the calls the host makes — the session view, the session update, checkout, order creation, and edits to a participant's slice.
- A participant sends their own token on
PUT /group-cart/{group_cart_uuid}/my-cartonly if they are a signed-in registered customer on the same brand. A guest participant has no Punchh token and sends none.
Never hand the host's Dlc-Authorization token to participant clients. It is the host's customer credential, it is not scoped to the group session, and a participant holding it could act as the host against Punchh outside the group order. Only the host's slice may carry discounts in any case, so a participant never needs it.
Omitting the header does not fail the call. We fall back to the Punchh token stored for that customer at sign-in, which may be stale and will produce balances or redemptions that do not match the customer's current state. Send it explicitly rather than relying on the fallback.
Which token to send
Whether the two headers carry the same value depends on how the brand authenticates its customers. Your Integration Manager will tell you which configuration applies to yours.
Two tokens — the standard PAR Ordering sign-in. Customer sign-in, customer sign-up and the STS token exchange all return a second token in dlc_access_token, alongside the usual token:
token.valueis the PAR Ordering customer token. It goes onAuthorization.dlc_access_token.valueis the Punchh token. It goes onDlc-Authorization.
dlc_access_token is null for a brand that is not integrated with Punchh, so you can read it to tell whether any of this applies.
One token — brands on PAR Guest Identity. On these brands sign-in issues a single access token that is placed on both headers. There is no separate dlc_access_token to store. Confirm with your Integration Manager that your brand is configured this way before building against it.
Refreshing covers both tokens. On a Punchh brand, GET /customers/refresh returns a new token and a new dlc_access_token. Replace both headers from the refresh response. The one exception is a session created by the STS token exchange: refresh is rejected with 403, and you re-run the exchange instead.
On a two-token brand, store the two separately and never substitute one for the other — the PAR Ordering token is not accepted by Punchh. On a PAR Guest Identity brand there is only one token to store, and you put that same value on both headers.
Rewards
How to use rewards for an online order
Fetch the rewards the customer can redeem with GET /dlc-service/loyalty-rewards.
Request
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/dlc-service/loyalty-rewards",
"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": {
"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
}
]
}
}
Each entry in discounts is one reward. The fields that carry a value on a Punchh reward are:
| Property | Value | Description |
|---|---|---|
id |
Number | PAR Ordering's id for the discount. Send it back in discounts on the cart |
type_id, reference_type |
Number, String | Always 2 and LoyaltyReward |
name, description |
String | What to show the customer |
image |
JSON | fullsize, thumbnail_medium and thumbnail_small URLs |
channels |
Array | Always all five channels (type_id 1–5: POS, kiosk, mobile, web, POS-integrated) |
point_cost |
Number | Points the customer spends to redeem it |
The remaining discount fields (brand_id, position, tracking_code, max_redemption_count, date_from, date_to, the reduction_* fields, is_registered_only, show_only_in_ordering_flow, discount_tags, discount_conditions, translations, created_at, updated_at) belong to PAR Ordering's own discounts and carry no information on a Punchh reward. They come back as null, 0, false, an empty string or an empty array, as in the example above — read the fields in the table and ignore the rest.
When the customer picks a reward, update the cart with it in discounts as { "id": <reward id>, "type_id": 2 }. The response comes back with the reward priced in, and the customer can place the order with POST /cart/{cart_id}/order.
Offers
How to use offers for an online order
Fetch the offers available to the customer with GET /dlc-service/loyalty-promotions.
Request
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/dlc-service/loyalty-promotions",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"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"
]
}
]
}
}
Each entry in discounts is one offer. The fields that carry a value on a Punchh offer are:
| Property | Value | Description |
|---|---|---|
id |
Number | PAR Ordering's id for the discount. Send it back in discounts on the cart |
type_id, reference_type |
Number, String | Always 3 and Promotion |
name, description |
String | What to show the customer |
date_to |
Date | When the offer expires |
image |
JSON | fullsize, thumbnail_medium and thumbnail_small URLs |
channels |
Array | Always all five channels (type_id 1–5: POS, kiosk, mobile, web, POS-integrated) |
venue_codes |
Array | Store codes the offer can be redeemed at; empty means this field puts no limit on it |
The other discount fields carry no Punchh information either and come back as null, 0, false or empty, as on a reward — with one exception. discount_conditions can hold a DiscountConditionSpecificStore entry whose properties.venue_ids are the PAR Ordering store ids the offer is limited to; when it is there, only offer the discount at those stores.
When the customer picks an offer, update the cart with it in discounts as { "id": <offer id>, "type_id": 3 }. The response comes back with the offer priced in, and the customer can place the order with POST /cart/{cart_id}/order.
Customer's Credit
How to redeem a credit for an online transaction
To apply banked credit, update the cart with it in discounts. The discount object is { "discount_amount": 1200 } for a $12 credit. The amount is in minor units. Place the order with POST /cart/{cart_id}/order. The credit is already on the cart, so it is not sent again on the order.
Promo Codes
How to use unlock-in-app and direct-at-pos promo codes
Try the code on the cart first: update the cart with { "redemption_code": "THECODE" } in discounts, without a type_id. If that succeeds it was a direct-at-POS code, and the discount is on the cart.
If it is rejected, it is an unlock-in-app code. Call POST /api/dlc-service/loyalty-coupons with { "code": "THECODE" }, where the value is the promo code as configured in Punchh.
On success the code has unlocked an offer on the customer's account; fetch GET /dlc-service/loyalty-promotions again and apply it like any other offer.
