Fetch Loyalty Related Customer Information

GET /dlc-service/customer-account-loyalty returns the signed-in customer's balance — points or banked currency, depending on the program — and the code to show on their loyalty card so the store or kiosk can identify them. Send the customer's Punchh token in Dlc-Authorization.

Request

{
  "method": "get",
  "url": "https://api-public-demo.menu.app/api/dlc-service/customer-account-loyalty",
  "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": {
    "customer_account_loyalty": {
      "point_balance": 0,
      "banked_currency": 0,
      "total_points_accrued": 0,
      "unbanked_points": 0,
      "user_as_qrcode": "PUNCHHBAhJIiMzMDYwNzYyMzE6bWFyaW9wKzIyMzNAbWVudS5hcHAGOgZFRg==--5aea56cd9fec5ad10fa75da35d0fb046fbc00b49PUNCHH",
      "user_as_barcode": "",
      "user_code_type": "",
      "loyalty_code": "P3WLXVW1O",
      "referral_code": "Mar2233M827",
      "referral_path": "https://engagement.punchh.com/whitelabel/brinkdemo/invite?invite_code=Mar2233M827",
      "expiring_banked_currency": 0,
      "banked_currency_expiring_on": ""
    }
  }
}

Property Value Description
point_balance Number Points the customer can spend
total_points_accrued Number Points earned over the lifetime of the account
banked_currency Number points_convert_to_currency programs. Currency the customer can spend, in minor units
unbanked_points Number points_convert_to_currency programs. Points earned toward the next conversion. With a 100-point threshold, a customer on 55 points shows 55; after 45 more, the currency is banked and this returns to 0
expiring_banked_currency Number points_convert_to_currency programs where banked currency expires. The amount that will expire next; null when the program has no expiry
banked_currency_expiring_on String Not populated yet
user_code_type String barcode, qrcode or empty. How to draw the loyalty card
user_as_qrcode, user_as_barcode String The content to encode in the QR code or barcode
referral_path String The invite link the customer can share
loyalty_code, referral_code String Not used on Punchh programs

Which balance to show depends on the program type: point_balance on points_unlock_redeemables and points_convert_to_reward, unbanked_points (with banked_currency) on points_convert_to_currency. A surprise-and-delight program has no points or currency to show.

Loyalty Card Number

user_code_type says how to draw the loyalty card for the POS scanner: qrcode means render user_as_qrcode as a QR code, barcode means render user_as_barcode as a barcode.

Points earned on an order

To show how many points an order will earn, update the cart and read summary.loyalty from the response. There is no separate calculation call; the cart recalculates on every update.

Response (excerpt)

{
  "status": "OK",
  "code": 200,
  "data": {
    "cart": {
      "id": "f6ce31f7b7549cc7c3e5326661cf1dc3b5ea5c3fd89cce634667e483e23fb51a",
      "summary": {
        "subtotal": 2500,
        "total": 2625,
        "discount": 0,
        "payment_amount": 2625,
        "total_tax": 125,
        "total_fee": 0,
        "tip": 0,
        "loyalty": {
          "points_spent": 0,
          "points_accrued": 25,
          "available_points": 0
        }
      }
    }
  }
}

summary.loyalty.points_accrued is what the customer will earn for this order, as calculated by Punchh; points_spent is what a reward on the cart costs them. The points are granted when the order is placed — you do not make a separate call for it. A brand can still grant points by hand from the Punchh dashboard.

Points from an in-store receipt

A customer who paid in store without identifying themselves can still earn the points by scanning the code printed on the receipt.

Screenshot 2023-08-08 at 09.38.01.jpg

Send the scanned code to POST /dlc-service/loyalty/checkin:

Property Value Description
type string barcode or qrcode
code number The scanned code
latitude, longitude number The customer's current location, optional
is_manual boolean true when the customer typed the code instead of scanning it

Request

{
  "method": "post",
  "url": "https://api-public-demo.menu.app/api/dlc-service/loyalty/checkin",
  "headers": {
    "X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
    "Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
    "Api-Version": "<current-release-version>",
    "Content-Type": "application/json",
    "Dlc-Authorization": ""
	
  },
  "body": {
  
    "type": "barcode", 
    "code": 5504339697795,
    "is_manual": true
  }
}

Response

{
    "status": "OK",
    "code": 200,
    "data": {
        "checkin": {
            "checkin_id": "1054637900",
            "points_earned": 15,
            "is_first_checkin": true
        }
    }
}

Property Value Description
checkin_id integer Punchh's id for the check-in
points_earned integer Points added to the customer's balance
is_first_checkin boolean Whether this is a first check-in. A receipt code earns points only once