Previous Topic	Next Topic
Online Ordering Module 5: Redemptions	Online Ordering Module 7: Updating/Voiding Transactions

Online Ordering API Certification Tutorial - Module 6: Check-in

Goal

Create a check-in for a loyalty guest and send check-in details to Punchh to grant the customer a visit or loyalty points.

Prerequisites

You must have read the Online Ordering Module 3a: Show Offers in Guest Account and Online Ordering Module 5: Redemptions tutorials.
The user for which a check-in is created must be a loyalty guest.

Use Cases and Context

Check-in is a required step for loyalty guests and is done at the end of every loyalty transaction, after the check is paid in full and closed out. When a loyalty guest who has offers that can be used logs in and places an order online, the user can select which offers to use. When the user makes the final payment, the user is attached to the transaction and a check-in is created in the Punchh system so that the user can earn loyalty points or visits (depending on the program type of the business). This ensures that the loyalty guest is getting awarded appropriately for the final check amount. A check-in records the guest’s visit along with order details (e.g., menu items ordered, prices, redemptions made, etc.). The Create Loyalty Check-in API call must be sent in order for the guest to earn points on the transaction. If the transaction is not a loyalty transaction, and the guest is not a rewards member, skip this step.

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Create Loyalty Check-in POST {server-name}/api/auth/checkins/online_order	client access_token transaction_no external_uid receipt_datetime subtotal_amount receipt_amount channel store_number The required parameters under the Menu Items object: - item_name - item_qty - item_amount - menu_item_type - menu_item_id - menu_family - menu_major_group - serial_number	points (guest's total points) first_name last_name The Checkin object shows the details of this order: - bar_code - created_at - external_uid - checkin_id - pending_points - pending_refresh - points_earned (points earned on this specific order)

Example Code

The following code samples demonstrate how to send a check-in request. A check-in is required at the end of every loyalty transaction and is how users can earn loyalty points/visits on orders.

curl --location --request POST 'https://server-name-goes-here.punchh.com/api/auth/checkins/online_order' \
--header 'Content-Type: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
--data-raw '{
  "client": "CLIENT_GOES_HERE",
  "transaction_no": "1111111111",
  "external_uid": "1111-1111-1111-1111",
  "receipt_datetime": "2022-09-16T07:42:03-00:00",
  "store_number":"001",
  "menu_items": [
    {
      "item_name": "Pizza with Pepperoni Topping",
      "item_qty": 1,
      "item_amount": 10.99,
      "menu_item_type": "M",
      "menu_item_id": "3001",
      "menu_family": "Pizza",
      "menu_major_group": "Pizza",
      "serial_number": "1.0"
    },
    {
      "item_name": "Pepperoni Topping",
      "item_qty": 1,
      "item_amount": 0.99,
      "menu_item_type": "M",
      "menu_item_id": "3002",
      "menu_family": "Pizza Topping",
      "menu_major_group": "Pizza",
      "serial_number": "1.1"
    },
    {
      "item_name": "Discount",
      "item_qty": 1,
      "item_amount": 0.99,
      "menu_item_type": "D",
      "menu_item_id": "4001",
      "menu_family": "Discount",
      "menu_major_group": "Discount",
      "serial_number": "2.0"
    }
  ],
  "subtotal_amount": 6.98,
  "receipt_amount": 6.98,
  "channel": "online_order"
}'

import json
from http_client import send_request

def checkin():
  path = "/api/auth/checkins/online_order"
  http_verb = "POST"
  menu_items = [{"item_name": "Pizza with Pepperoni Topping", "item_qty": 1, "item_amount": 10.99, "menu_item_type": "M", "menu_item_id": "3001", "menu_family": "Pizza", "menu_major_group": "Pizza", "serial_number": "1.0"}, {
      "item_name": "Pepperoni Topping", "item_qty": 1, "item_amount": 0.99, "menu_item_type": "M", "menu_item_id": "3002", "menu_family": "Pizza Topping", "menu_major_group": "Pizza", "serial_number": "1.1"}, {
      "item_name": "Discount", "item_qty": 1, "item_amount": 0.99, "menu_item_type": "D", "menu_item_id": "4001", "menu_family": "Discount", "menu_major_group": "Discount", "serial_number": "2.0"}]
  receipt_amount = 0
  for item in menu_items:
    if item["menu_item_type"] == "M":
      receipt_amount += item["item_amount"]
    if item["menu_item_type"] == "D":
      receipt_amount -= item["item_amount"]
  body = json.dumps({
    "client": "CLIENT_GOES_HERE",
    "receipt_amount": receipt_amount,
    "subtotal_amount": receipt_amount,
    "store_number": "001",
    "menu_items": menu_items,
    "receipt_datetime": "2022-09-16T07:42:03-00:00",
    "external_uid": "1111-1111-1111-1111",
    "transaction_no": "111111111"
  })
  response = send_request(path, http_verb, body)
  print(f"Response: {response}")
  
checkin()

class Checkin
  require_relative 'generate_signature.rb'
  require_relative 'http_client.rb'
  require 'json'
  
  # Client for the environment that you are pointing the request to
  CLIENT = "CLIENT_GOES_HERE"
  PATH = "/api/auth/checkins/online_order"
  HTTP_VERB = "POST"
  MENU_ITEMS = [{ item_name: "Pizza with Pepperoni Topping", item_qty: 1, item_amount: 10.99, menu_item_type: "M", menu_item_id: "3001", menu_family: "Pizza", menu_major_group: "Pizza", serial_number: "1.0" }, { item_name: "Pepperoni Topping", item_qty: 1, item_amount: 0.99, menu_item_type: "M", menu_item_id: "3002", menu_family: "Pizza Topping", menu_major_group: "Pizza", serial_number: "1.1" }, {item_name: "Discount", item_qty: 1, item_amount: 0.99, menu_item_type: "D", menu_item_id: "4001", menu_family: "Discount", menu_major_group: "Discount", serial_number: "2.0"}]
  
  def self.checkin
    receipt_amount = 0
    MENU_ITEMS.each do |item|
      if item[:menu_item_type] == "M"
        receipt_amount += item[:item_amount]
      end
      if item[:menu_item_type] == "D"
        receipt_amount -= item[:item_amount]
      end
    end
    
    body = {client: CLIENT, receipt_amount: receipt_amount, subtotal_amount: receipt_amount, store_number: "001", menu_items: MENU_ITEMS, receipt_datetime: "2022-09-16T07:42:03-00:00", external_uid: "1111-1111-1111-1111", transaction_no: "1111111111", channel: "online_order"}.to_json
    response = HttpClient::send_request(PATH, HTTP_VERB, body)
  end
end

Checkin.checkin

Workflow

The online ordering system must call the Create Loyalty Check-in API endpoint for every loyalty guest at the end of a transaction so that the guest can earn points for the transaction. The Create Loyalty Check-in API call requires you to send the final check information with menu item data related to different items, such as: 1) menu items with menu item type M; 2) discounts both internal and Punchh with menu item type D; 3) service charges and delivery fees; 4) tips and gift card purchases with menu item type S; 5) tax applied to the check with menu item type T; and 6) the payment collected on the check with menu item type P. The payment should be the final payment amount. For example, if the guest pays $30 in cash for a $28 order, the payment should be $28.

The online ordering system needs to send the menu items to Punchh in the format prescribed in How To Send Menu Items to Punchh. API developers are responsible for sending the Menu Items object exactly how Punchh specifies in that topic. There is no flexibility in the way menu items are sent in the Create Loyalty Check-in API call.

After a completed transaction, create a check-in for the guest by sending details to the Create Loyalty Check-in endpoint. Along with the menu item data, you need to send the transaction number, date and time of receipt, order amount before taxes, and the final payable amount, etc. See the Create Loyalty Check-in endpoint topic for a list of required request parameters. The Create Loyalty Check-in API response returns the points earned by the guest on the check-in.

Note: Punchh recommends sending the store_number request parameter with the Create Loyalty Check-in call to indicate the store for which the order was placed and to help the business with reporting. If the store_number parameter is not sent with the request, the location defaults to the setting for the business as specified in the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration.

Updating a Check-in

You can update a check-in call by enabling the pending points feature and then sending an Update Loyalty Check-in API call with the change. See the “Updating a Transaction” section in the Online Ordering Module 7: Updating/Voiding Transactions tutorial.

Best Practices

Perform a check-in call at the end of every loyalty transaction, whether the guest has redeemed an offer or not.
Make sure that the check-in call shows the final state of the receipt (everything that is relevant to transaction): menu items (M), discounts (D), service charges (S), taxes (T), and payments (P).
Payments (P) should be the final payment amount.
A check-in may be registered only to one user. Attempting to process a check-in for the same transaction but for multiple users will result in an error.
Review How To Send Menu Items to Punchh to gain a better understanding of Punchh menu item requirements.