Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Punchh Check In API
version: '1.0'
description: 'Operations tagged Check-in across 2 of this provider''s published API definitions: punchh-online-ordering-sso-api-openapi.yml, punchh-platform-functions-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Check-in
paths:
/api/auth/checkins/online_order:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
description: First name of the user
last_name:
type: string
description: Last name of the user
checkins:
type: integer
description: Total number of check-ins for this online order
points:
type: integer
description: Total points earned for this online order
checkin:
type: object
properties:
created_at:
type: string
format: date-time
description: Date/time when the check-in was created in the system, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format
external_uid:
type: string
description: Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice.
checkin_id:
type: integer
description: ID of the loyalty check-in
pending_points:
type: integer
description: Number of pending points that will be earned once the pending points window expires
pending_refresh:
type: boolean
description: Whether the check-in is pending refresh or not
points_earned:
type: integer
description: Number of points earned for the loyalty check-in
bar_code:
type: string
description: Barcode in string format
examples:
default:
value:
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
'400':
description: Sending missing/incorrect params, bad encoding etc
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
'422':
description: Sending invalid Entity
summary: Create Loyalty Check-in
description: Creates a loyalty check-in for an online order against a given receipt. Requires menu items and parameters to be sent.
operationId: sso_loyalty_checkin
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content_type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Authorization'
tags:
- Check-in
x-stoplight:
id: f1943957e38b4
requestBody:
content:
application/json:
schema:
type: object
properties:
authentication_token:
type: string
description: 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](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
cc_last4:
type: string
description: Last 4 digits of credit card number
employee_id:
type: string
description: ID of the employee who took the order. In case of a system order, it can be a system-generated ID.
employee_name:
type: string
description: Name of the employee who took the order. In case of a system order, it can be the name of the system.
store_number:
type: string
description: 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.
menu_items:
$ref: '#/components/schemas/menu_items'
receipt_amount:
type: number
format: double
description: Order amount before taxes, calculated as the sum of all item amounts minus any discounts. This is the amount used to calculate loyalty points/visits. The value of this parameter should match `subtotal_amount`. For example, if the order amount is $10, both `receipt_amount` and `subtotal_amount` will be 10. If a $2 discount is applied, both will be 8.
subtotal_amount:
type: number
format: double
description: Order amount before taxes (sum of all item amounts minus any discounts). Same as `receipt_amount`. For historical reasons, include this parameter along with `receipt_amount` in the API request.
receipt_datetime:
type: string
description: Timestamp of the receipt as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), in YYYY-MM-DDThh:mm:ssZ format
transaction_no:
type: string
description: 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.
external_uid:
type: string
description: Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice.
client:
type: string
description: Client key of the business
channel:
type: string
enum:
- pos
- web
- online_order
- mobile
- dashboard
- chatbot
- kiosk
description: 'Channel through which the check-in was requested. Possible values are: `online_order`, `pos`,`web`, `mobile`, `dashboard`, `chatbot`, `kiosk`.'
payable:
type: string
description: 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).
revenue_id:
type: string
description: 'ID of the online ordering function that designates order fulfillment method. Example: 1 for dine-in, 2 for to-go/take out, 3 for call-in pickup, 4 for call-in deliver, etc. Some vendors call this revenue center, order method, order mode, etc. The values assigned here should represent the way the order is fulfilled for the customer, not the area in the restaurant where the order is placed (e.g., not bar, patio, dining room, etc.).'
revenue_code:
type: string
description: Name of the online ordering function that designates order fulfillment method (e.g., to-go/take out, call-in pickup, call-in deliver, etc.). Some online ordering systems call this Revenue Center, Order Method, Order Mode, etc. The values assigned here should represent the way the order is fulfilled for the customer, not the area in the restaurant where the order is placed (e.g., not bar, patio, dining room, etc.).
state:
type: string
description: 'The current state of the check-in. Possible values are: `committed`, `pending` or `void` (required in case of leveraging pending points via explicit API option).'
required:
- store_number
- receipt_amount
- subtotal_amount
- receipt_datetime
- transaction_no
- external_uid
- client
- payable
examples:
Request:
value: "{\n\"authentication_token:AUTHENTICATION_TOKEN_GOES_HERE\"\n\"receipt_amount\":7.86,\n\"cc_last4\":4387,\n\"employee_id\":7,\n\"employee_name\":\"EMPLOYEE_NAME_GOES_HERE\",\n\"store_number\":\"58\",\n\"menu_items\":[ \n{\n\"item_name\":\"White rice\",\n\"item_qty\":1,\n\"item_amount\":2.86,\n\"menu_item_type\":\"M\",\n\"menu_item_id\":\"3419\",\n\"menu_family\":\"800\",\n\"menu_major_group\":\"152\",\n\"serial_number\":\"1.0\"\n},\n{\n\"item_name\":\"Brown rice\",\n\"item_qty\":1,\n\"item_amount\":7.86,\n\"menu_item_type\":\"M\",\n\"menu_item_id\":\"3418\",\n\"menu_family\":\"800\",\n\"menu_major_group\":\"152\",\n\"serial_number\":\"2.0\"\n},\n{\n\"item_name\":\"Free rice\",\n\"item_qty\":1,\n\"item_amount\":2.86,\n\"menu_item_type\":\"D\",\n\"menu_item_id\":\"3419\",\n\"menu_family\":\"800\",\n\"menu_major_group\":\"152\",\n\"serial_number\":\"3.0\"\n}\n],\n\"subtotal_amount\":7.86,\n\"receipt_datetime\":\"2015-03-20T15:23:20+05:30\",\n\"transaction_no\":5678,\n\"external_uid\":\"a unique id\",\n\"client\":\"CLIENT_GOES_HERE\",\n\"channel\":\"online_order\"\n}"
put:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
description: First name of the user
last_name:
type: string
description: Last name of the user
checkins:
type: integer
description: Total number of check-ins for this online order
points:
type: integer
description: Total points earned for this online order
checkin:
type: object
properties:
bar_code:
type: string
description: Barcode in string format
created_at:
type: string
description: Date/time when the check-in occurred
external_uid:
type: string
description: Unique external ID associated with the check-in
checkin_id:
type: integer
description: Unqiue ID of the check-in
pending_points:
type: integer
description: Number of pending points
pending_refresh:
type: boolean
points_earned:
type: integer
description: Points earned on the check-in
examples:
default:
value:
first_name: FIRST_NAME_GOES_HERE
last_name: LAST_NAME_GOES_HERE
checkins: 3
points: 183
checkin:
bar_code: BARCODE_GOES_HERE
created_at: '2019-10-07T12:09:06Z'
external_uid: EXTERNAL_UID_GOES_HERE
checkin_id: 235355451
pending_points: 0
pending_refresh: false
points_earned: 11
'400':
description: Sending missing/incorrect params, bad encoding etc
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
'422':
description: Sending invalid Entity
summary: Update Loyalty Check-in
description: Updates a loyalty check-in in the pending state based on external_uid. Requires all parameters to be sent again (no deltas).
operationId: sso_update_loyalty_checkin
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content_type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
tags:
- Check-in
x-stoplight:
id: 386045cf184bc
requestBody:
content:
application/json:
schema:
type: object
properties:
employee_id:
type: string
description: Employee ID. In case of a system order, it can be a system-generated ID.
employee_name:
type: string
description: Employee who took the order. In case of a system order, it can the be name of the system.
cc_last4:
description: Last 4 digits of credit card number
type: string
menu_items:
$ref: '#/components/schemas/menu_items'
receipt_amount:
type: number
format: double
description: Order amount before taxes, calculated as the sum of all item amounts minus any discounts. This is the amount used to calculate loyalty points/visits. The value of this parameter should match `subtotal_amount`. For example, if the order amount is $10, both `receipt_amount` and `subtotal_amount` will be 10. If a $2 discount is applied, both will be 8.
subtotal_amount:
type: number
format: double
description: Order amount before taxes (sum of all item amounts minus any discounts). Same as `receipt_amount`. For historical reasons, include this parameter along with `receipt_amount` in the API request.
receipt_datetime:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Timestamp of the receipt as per ISO 8601, in YYYY-MM-DDTHH:MM:SSZ format
transaction_no:
type: string
description: Receipt number or transaction number on the receipt
external_uid:
type: string
description: Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice.
client:
type: string
description: Client key of the business
authentication_token:
type: string
description: 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](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
required:
- client
examples:
default:
value:
receipt_amount: 14.72
cc_last4: 4387
employee_id: '7'
employee_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE
menu_items:
- item_name: White rice
item_qty: 1
item_amount: 4.86
menu_item_type: M
menu_item_id: '3419'
menu_family: '800'
menu_major_group: '152'
- item_name: Brown rice
item_qty: 1
item_amount: 9.86
menu_item_type: M
menu_item_id: '3418'
menu_family: '800'
menu_major_group: '152'
subtotal_amount: 14.72
receipt_datetime: '2019-10-05T15:23:20+05:30'
transaction_no: 5090
external_uid: EXTERNAL_UID_GOES_HERE
client: CLIENT_GOES_HERE
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api/auth/checkins:
delete:
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties: {}
'417':
description: ''
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
code:
type: string
examples:
default:
value:
error:
message: Checkin associated with external_uid EXTERNAL_UID_GOES_HERE not found
code: not_found
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
code:
type: string
summary: Void Loyalty Check-in
description: Deletes/voids a loyalty check-in in the pending state
operationId: sso_void_loyalty_checkin
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content_type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
tags:
- Check-in
x-stoplight:
id: 25514e759947a
requestBody:
content:
application/json:
schema:
type: object
properties:
external_uid:
type: string
description: External unique identifer associated with the check-in
authentication_token:
type: string
description: 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](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
client:
type: string
description: Client key of the business
required:
- external_uid
- client
examples:
default:
value:
external_uid: EXTERNAL_UID_GOES_HERE
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
client: CLIENT_GOES_HERE
post:
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: Check-in ID
business_id:
type: integer
description: ID of the business at which the check-in occurred
card_id:
type: integer
location_id:
type: integer
description: ID of the location where the check-in occurred
created_at:
type: string
enum:
- ' YYYY-MM-DDThh:mm:ssZ'
format: date-time
description: Date/time when the check-in occurred, in ISO8601 format
share_message:
x-nullable: true
status:
type: string
description: Status of the check-in
verifications_count:
x-nullable: true
for_referring_full_name:
x-nullable: true
points_earned:
type: integer
description: Points earned for the check-in
points_spent:
type: integer
description: Points spent on the check-in (e.g., 10 points redeemed during check-in)
first_punchh_at_business:
type: boolean
location_name:
type: string
description: Name of the location
receipt_picture_url:
type: string
description: URL of the receipt picture
points_available:
type: integer
first_checkin_message:
description: Check-in message for the first check-in
x-nullable: true
pending_refresh:
type: boolean
current_membership_level:
description: Membership level of the user
x-nullable: true
scheduled_expiry_on:
description: Expiry of the check-in
x-nullable: true
receipt_checkin_message:
description: Check-in message printed on the receipt
x-nullable: true
fan_page_id:
x-nullable: true
allows_rating:
type: boolean
survey_url:
description: Survey URL
x-nullable: true
examples:
default:
value:
id: 5908374
business_id: 576
card_id: ID_GOES_HERE
location_id: 306093
created_at: '2015-08-26T09:14:50Z'
share_message: null
status: loyalty
verifications_count: null
for_referring_full_name: null
points_earned: 1
points_spent: 0
first_punchh_at_business: true
location_name: CafeLab
receipt_picture_url: IMAGE_URL_GOES_HERE
points_available: 1
first_checkin_message: null
pending_refresh: false
current_membership_level: null
scheduled_expiry_on: null
receipt_checkin_message: null
fan_page_id: null
allows_rating: false
survey_url: null
'400':
description: ''
summary: Create Loyalty Check-in (OLD)
description: 'NOTE: This is an old endpoint. Use [this endpoint](/docs/dev-portal-online-ordering/f1943957e38b4-grant-loyalty-checkin-against-given-receipt) instead.
Creates a loyalty check-in by store number'
operationId: sso_create_loyalty_checkin
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content_type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/accept_language'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
x-internal: false
tags:
- Check-in
x-stoplight:
id: c1a797cf02da6
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: Client key of the business
store_number:
type: string
description: Store number of the location where the user is located
access_token:
type: string
description: Security token that identifies the user
required:
- client
- store_number
- access_token
examples:
default:
value:
client: CLIENT_GOES_HERE
store_number: '3256'
access_token: ACCESS_TOKEN_GOES_HERE
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
bar_code:
type: string
description: Barcode of the check-in
created_at:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the check-in occurred, in ISO 8601 format
external_uid:
type: string
description: External UID associated with the check-in
checkin_id:
type: integer
description: Check-in ID of the check-in
pending_points:
type: integer
description: The number of pending points that will be credited to the user once the pending points window expires
pending_refresh:
type: boolean
points_earned:
type: integer
description: Points earned on the check-in
examples:
default:
value:
bar_code: BARCODE_GOES_HERE
created_at: '2017-08-14T10:17:01Z'
external_uid: EXTERNAL_UID_GOES_HERE
checkin_id: 5212416
pending_points: 0
pending_refresh: false
points_earned: 24
'400':
description: ''
'412':
description: ''
summary: Fetch a Check-in by External ID
description: Returns the details of a check-in using external_id for reference
operationId: sso_Fetch_a_Checkin_by_external_uid
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/content_type'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
tags:
- Check-in
x-stoplight:
id: 65a6130a73c7b
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: Client key of the business
default: CLIENT_GOES_HERE
authentication_token:
type: string
description: 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](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
external_uid:
type: string
description: External UID associated with the check-in
required:
- client
- external_uid
examples:
default:
value:
external_uid: EXTERNAL_UID_GOES_HERE
client: CLIENT_GOES_HERE
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api2/dashboard/checkins:
post:
summary: Create Loyalty Check-in
operationId: post-api2-dashboard-checkins
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
x-stoplight:
id: 92i7d1m5a7mcu
description: First name of the user
last_name:
type: string
x-stoplight:
id: mt5v6whtcaavo
description: Last name of the user
checkins:
type: integer
x-stoplight:
id: h4pzhwpgluvgz
description: Total number of check-ins for this online order
points:
type: integer
x-stoplight:
id: mxl9jg80wisnp
description: Total points earned for this online order
checkin:
$ref: '#/components/schemas/checkin'
examples:
default:
value:
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
'400':
description: Bad Request - Sending missing/incorrect params, bad encoding etc
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: i98czqxxs0o7z
examples:
default:
value:
error: 'Required parameter missing or the value is empty: user_id'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
description: 'Not Found: Sending incorrect values in search parameters or missing/invalid search parameters'
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
error_name:
type: string
examples:
- user_not_found
examples:
Sending incorrect values in search parameters or missing/invalid search parameters:
value:
errors:
user_not_found: User Not Found
'422':
description: 'Unprocessable Entity: Phone number uniqueness is disabled'
content:
application/json:
schema:
type: object
properties:
errors:
type: object
x-stoplight:
id: kjnapwqm7iv0k
properties:
error_name:
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-check-in-api-openapi.yml