Create Loyalty Check-in

Creates a loyalty check-in for an online order against a given receipt. Requires menu items and parameters to be sent.

Headers

x-pch-digest
Type: string
required

The signature for the API call
Content-Type
Type: string
required

Set this header to application/json.
Accept
Type: string
required

Advertises which content types the client is able to understand
User-Agent
Type: string
required

For details, see User Agent.
Authorization
Type: string
required

You may pass the access_token instead of the authentication_token in Online Ordering endpoints to authorize the request. It must be supplied as Bearer ACCESS_TOKEN_GOES_HERE.

Body

application/json

client
Type: string
required

Client key of the business
external_uid
Type: string
required

Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice.
payable
Type: string
required

Amount paid after applying discounts and adding any taxes or service charges. For example, if the order amount is $10, the values of the receipt_amount and subtotal_amount parameters will be $10. If a $2 discount is applied, subtotal_amount becomes $8. However, if there are $3 service charges and $1 tax, the value of the payable parameter becomes $12 (10 – 2 + 3 + 1 = 12).
receipt_amount
Type: numberFormat: double
required

Order amount before taxes, calculated as the sum of item_amount for M line items in menu_items minus the item_amount for D line items; S, T, and P line items are excluded. See the description of the D, S, T, and P items in the menu_items.menu_item_type request parameter. The value of this parameter should match subtotal_amount.

⚠️ Important: Loyalty points and visits are calculated based on the individual item amounts in the menu_items array, not directly from receipt_amount. To ensure discounts are reflected correctly in loyalty calculations, include the discount as a separate line item in menu_items with a menu_item_type: D. The system evaluates D line items as negative amounts when calculating the order total. If the discount line item is omitted, points will be calculated based on the original item prices, resulting in more points being awarded than intended.

For example, if a guest purchases an item for $12.99 and a $3.00 discount is applied, receipt_amount should be $9.99, and a discount line item of $3.00 must be included in menu_items. If the discount line item is omitted, the system will calculate points based on $12.99 instead of $9.99.
receipt_datetime
Type: string
required

Timestamp of the receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format
store_number
Type: string
required

The location where the check-in occurred, as configured in the Punchh platform via Store Locations > All Store Locations. This is generally provided by the business.
subtotal_amount
Type: numberFormat: double
required

Order amount before taxes, calculated as the sum of item_amount for M line items in menu_items minus the item_amount for D line items; S, T, and P line items are excluded. See the description of the D, S, T, and P items in the menu_items.menu_item_type request parameter. Same as receipt_amount. For historical reasons, include this parameter along with receipt_amount in the API request.
transaction_no
Type: string
required

Receipt number or transaction number on the receipt. In case of redemption associated with the order, the same transaction number must be sent for both check-ins and redemptions.
authentication_token
Type: string

The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the SSO process.
cc_last4
Type: string

Last 4 digits of credit card number
channel
Type: stringenum

Channel through which the check-in was requested. Possible values are: online_order, pos,web, mobile, dashboard, chatbot, kiosk.

values
poswebonline_ordermobiledashboardchatbotkiosk
employee_id
Type: string

ID of the employee who took the order. In case of a system order, it can be a system-generated ID.

Responses

application/json
400

Sending missing/incorrect params, bad encoding etc
401

Sending invalid credentials
412

Sending invalid Signature
422

Sending invalid Entity

post/api/auth/checkins/online_order

curl https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/checkins/online_order \
  --request POST \
  --header 'x-pch-digest: SIGNATURE_GOES_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
  --header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
  --data '{
  "authentication_token": "AUTHENTICATION_TOKEN_GOES_HERE",
  "receipt_amount": 7.86,
  "cc_last4": 4387,
  "employee_id": 7,
  "employee_name": "EMPLOYEE_NAME_GOES_HERE",
  "store_number": "58",
  "menu_items": [
    {
      "item_name": "White rice",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": "3419",
      "menu_family": "800",
      "menu_major_group": "152",
      "serial_number": "1.0"
    },
    {
      "item_name": "Brown rice",
      "item_qty": 1,
      "item_amount": 7.86,
      "menu_item_type": "M",
      "menu_item_id": "3418",
      "menu_family": "800",
      "menu_major_group": "152",
      "serial_number": "2.0"
    },
    {
      "item_name": "Free rice",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": "3419",
      "menu_family": "800",
      "menu_major_group": "152",
      "serial_number": "3.0"
    }
  ],
  "subtotal_amount": 7.86,
  "receipt_datetime": "2015-03-20T15:23:20+05:30",
  "transaction_no": 5678,
  "external_uid": "a unique id",
  "client": "CLIENT_GOES_HERE",
  "channel": "online_order"
}'

Show Schema

{
  "first_name": "FIRST_NAME_GOES_HERE",
  "last_name": "LAST_NAME_GOES_HERE",
  "checkins": 2,
  "points": 22,
  "checkin": {
    "created_at": "2015-11-26T10:57:06Z",
    "external_uid": "EXTERNAL_UID_GOES_HERE",
    "checkin_id": 7415394,
    "pending_points": 0,
    "pending_refresh": false,
    "points_earned": 11,
    "bar_code": "BARCODE_GOES_HERE"
  }
}