info:
title: Online Ordering and SSO API
version: '1.0'
description: "The Punchh SSO API endpoints provide user-management functions such as login, registration,\
\ forgot password, and connect with Facebook for users on the Punchh loyalty platform. You can also\
\ fetch user-specific information such as rewards or point balances. \n\nThe Punchh Online Ordering\
\ API endpoints enable users to earn and redeem rewards for online orders."
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
paths:
/api/auth/customers.json:
post:
responses:
'201':
description: Created - The response returns basic details about the user account, including
the authentication token that you must use to authenticate other API calls on the user's behalf.
content:
application/json:
schema:
$ref: '#/components/schemas/user-object'
examples:
default:
value:
address_line1: ADDRESS_GOES_HERE
anniversary: null
avatar_remote_url: null
birthday: null
city: ''
created_at: '2016-10-10T07:19:19Z'
email: test@example.com
email_verified: false
fb_uid: ''
first_name: FIRST_NAME_GOES_HERE
gender: ''
id: 111111111
last_name: User
state: ''
updated_at: '2017-10-11T16:03:19Z'
zip_code: '25110'
allow_multiple: true
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
favourite_locations: '308052'
favourite_store_numbers: '2310'
marketing_email_subscription: true
marketing_pn_subscription: true
passcode_configured: false
profile_field_answers: {}
referral_code: REFERRAL_CODE_GOES_HERE
referral_path: URL_GOES_HERE
secondary_email: ''
terms_and_conditions: false
title: ''
user_as_barcode: '1111111'
user_as_qrcode: QR_CODE_GOES_HERE
user_code: P11111111
user_id: 111111111
user_relations: []
wants_menu_notifications: false
work_zip_code: null
mindbody_client_id: null
preferred_locale: en
phone: ''
migrate_status: false
email_unsubscribe: false
allow_push_notifications: true
facebook_signup: false
communicable_email: test@example.com
access_token: null
expiration_date: '2018-07-31'
user_joined_at: '2022-11-01T19:17:44Z'
sms_subscription: false
age_verified_status: true
'400':
description: Bad Request - The API returns a 400 response code if the user's age is not verified,
thereby blocking the access to age-restricted content and prompting the user to complete the
age verification process.
content:
application/json:
schema:
type: object
properties: {}
'412':
description: Sending invalid Signature
content:
application/json:
schema:
type: object
examples:
default:
value: ''
'422':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
device_already_shared:
type: array
items:
type: string
examples:
default:
value:
errors:
device_already_shared:
- with maximum number of guests allowed.
summary: Create New User
description: 'Sign up a new user by using information such as email, first name, last name, birthday,
anniversary, password, etc. This will create/register the new user in the Punchh system.
**NOTE**
If the business is using a referral code, it is mandatory to pass the first_name and last_name
of the guest as the referral code will be generated from first_name, last_name, and some random
characters. Also, if you do not pass the first_name or the last_name, the API response may be
delayed or time out.
### Using Referral Code As Invite Code in the Sign-up Process
When a user signs up using the Create New User API, the API returns a referral code within the
user object. The user can share this code with non-loyalty users to invite them to join the business
loyalty program.
When a referred user signs up and enters the shared referral code, this `referral_code` must be
passed in the `invite_code` request parameter when calling the Create New User API.'
operationId: sso_signup
parameters:
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Signature'
tags:
- User Sign-up and SSO
x-stoplight:
id: 58f18dfdd2a3d
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
email:
type: string
description: Email address of the user for sign-up
first_name:
type: string
description: 'First name of the user (always recommended)
'
last_name:
type: string
description: 'Last name of the user (always recommended)
'
password:
type: string
description: Password for sign-up. Must be at least 8 characters in length.
birthday:
type: string
enum:
- YYYY-MM-DD
format: date
description: 'Birthday of the user, in YYYY-MM-DD format
'
anniversary:
type: string
description: Wedding anniversary date of the user, in YYYY-MM-DD format
enum:
- YYYY-MM-DD
format: date
external_source:
type: string
enum:
- SOURCE_GOES_HERE
description: "External source name (third-party IDP). Possible values for external_source\
\ are salesforce, customer_id, mparticle, azure, aws_cognito, auth0, and ext_idp.\
\ If you are using a different one, please reach out to your implementation manager\
\ to add a new value. The values are case-sensitive. \n"
external_source_id:
type: string
description: ID of the customer in the mentioned external source name (external_source),
a unique identifier generated by the third-party IDP (GUID format).
send_compliance_sms:
type: boolean
description: Send true to trigger compliance/opt-in SMS message for the user.
signup_channel:
type: string
enum:
- MobileEmail
- MobileFacebook
- POS
- WebEmail
- WebFacebook
- eclub
- OnlineOrder
- Chatbot
- Wifi
- MobileApple
description: 'Use this field to overrride the default channel of "OnlineOrder".
Possible values are: `MobileEmail`, `MobileFacebook`, `POS`, `WebEmail`, `WebFacebook`,
`eClub`, `OnlineOrder`, `Chatbot`, `Wifi`, `MobileApple`.'
password_confirmation:
type: string
description: Password confirmation for sign-up
fav_location_id:
type: string
description: 'Comma-separated list of the user''s favorite location IDs. NOTE: Location
IDs are different from store numbers.'
phone:
type: string
description: Phone number of the user
apn_token:
type: string
description: Apple Push Notification (APN) token
apn_token_readability:
type: boolean
description: Whether Apple Push Notification (APN) is enabled on iOS mobile app
or not
gcm_token:
type: string
description: Google Cloud Messaging (GCM) token
gcm_token_readability:
type: boolean
description: Whether Google Cloud Messaging (GCM) is enabled on the Android mobile
app or not
card_number:
type: string
description: Card number of the user
epin_number:
type: string
description: Epin number of the user
unsubscribed:
type: boolean
description: 'Whether the user has unsubscribed from emails
'
secondary_email:
type: string
description: Secondary email address of the user
app_device_id:
type: string
description: Device ID of the mobile app. It can also be sent in the header via
the punchh-app-device-id field.
city:
type: string
description: 'City where the user lives
'
zip_code:
type: string
description: Zip code where the user lives
address_line1:
type: string
description: 'Address information (part 1) of the user
'
address_line2:
type: string
description: 'Address information (part 2) of the user
'
state:
type: string
description: State where the user lives
office_phone:
type: string
description: Phone number of the user's office
cell_phone:
type: string
description: Cell phone number of the user
website:
type: string
description: Website of the user
twitter:
type: string
description: Twitter page of the user
gender:
type: string
description: Gender of the user (e.g., male or female)
invite_code:
type: string
description: 'The referral code of the user making the referral. When a user signs
up for the business loyalty program using the Create New User API, the API returns
a referral code within the user object.
When a referred user signs up and enters the shared referral code, this `referral_code`
must be passed in the `invite_code` request parameter when calling the Create
New User API.'
work_zip_code:
type: string
description: 'Zip code of the user''s office
'
terms_and_conditions:
type:
- string
- boolean
description: 'Whether the user has agreed to the terms and conditions to use the
app as per the configuration
'
user_relations:
$ref: '#/components/schemas/user-relations'
profile_field_answers:
$ref: '#/components/schemas/profile_field_answers'
marketing_email_subscription:
type: boolean
description: Whether the user has subscribed to receive marketing emails or not.
This is mandatory if Explicit Opt-in is enabled in the Punchh platform.
marketing_pn_subscription:
type: boolean
description: Whether the user has subscribed to receive marketing push notifications
or not
age_verified_status:
type: boolean
x-stoplight:
id: nezt0i39gju4r
description: 'Whether or not the user has undergone age verification by Koupon Media.
Possible Values: true, false. The parameter is accepted in the request if Koupon
Media is selected as the age verification adapter for the business in the Punchh
platform. Contact your Punchh representative to update this configuration. '
required:
- email
- password
client:
type: string
description: Client key of the business
required:
- client
examples:
default:
value:
user:
email: test@example.com
first_name: FIRST_NAME_GOES_HERE
last_name: LAST_NAME_GOES_HERE
password: PASSWORD_GOES_HERE
birthday: '1992-10-03'
anniversary: '1996-10-03'
phone: '1111111111'
terms_and_conditions: true
send_compliance_sms: true
external_source: SOURCE_GOES_HERE
external_source_id: SOURCE_ID_GOES_HERE
signup_channel: WebEmail
gender: male
city: Mountain View
secondary_email: test@example.com
state: California
zip_code: '30201'
invite_code: INVITE_CODE_GOES_HERE
age_verified_status: true
client: CLIENT_GOES_HERE
/api/auth/customers/sign_in:
post:
responses:
'200':
description: The response returns basic details about the user account, including the authentication
token that you must use to authenticate other API calls on the user's behalf.
content:
application/json:
schema:
$ref: '#/components/schemas/user-object'
examples:
default:
value:
address_line1: ADDRESS_GOES_HERE
anniversary: null
avatar_remote_url: null
birthday: null
city: ''
created_at: '2016-10-10T07:19:19Z'
email: test@example.com
email_verified: false
fb_uid: ''
first_name: FIRST_NAME_GOES_HERE
gender: ''
id: 111111111
last_name: LAST_NAME_GOES_HERE
state: ''
updated_at: '2017-10-11T16:03:19Z'
zip_code: '25110'
allow_multiple: true
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
favourite_locations: '308052'
favourite_store_numbers: '2310'
marketing_email_subscription: true
marketing_pn_subscription: true
passcode_configured: false
profile_field_answers:
children: '0'
dish: Pizza
referral_code: REFERRAL_CODE_GOES_HERE
referral_path: URL_GOES_HERE
secondary_email: ''
terms_and_conditions: false
title: ''
user_as_barcode: '1111111'
user_as_qrcode: QR_CODE_GOES_HERE
user_code: P11111111
user_id: 111111111
user_relations: []
wants_menu_notifications: false
work_zip_code: null
mindbody_client_id: null
preferred_locale: en
phone: ''
migrate_status: false
email_unsubscribe: false
allow_push_notifications: true
facebook_signup: false
communicable_email: test@example.com
access_token: null
expiration_date: '2018-07-31'
user_joined_at: '2022-11-01T19:17:44Z'
age_verified_status: true
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: Incorrect information submitted. Please retry.
'412':
description: "{\n \"Invalid Signature\"\n}"
'422':
description: '{
Sending invalid Entity
}'
summary: Log in With Email and Password
operationId: sso_login
description: 'Log in a user with the user''s email address and password information.
'
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
tags:
- User Sign-up and SSO
x-stoplight:
id: 97dc4430bb3aa
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
required:
- email
- password
properties:
email:
type: string
default: test@example.com
description: Email address of the user
password:
type: string
default: PASSWORD_GOES_HERE
description: Password of the user
age_verified_status:
type: boolean
x-stoplight:
id: 58201m9b6cve0
description: 'Whether or not the user has undergone age verification by Koupon Media.
Possible values: true, false. The parameter is accepted in the request if Koupon
Media is selected as the age verification adapter for the business in the Punchh
platform. Contact your Punchh representative to update this configuration. '
client:
type: string
description: Client key of the business
required:
- user
- client
examples:
default:
value:
user:
email: test@example.com
password: PASSWORD_GOES_HERE
age_verified_status: true
client: CLIENT_GOES_HERE
/api/auth/checkins/balance:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
balance:
$ref: '#/components/schemas/Account-Balance'
rewards:
$ref: '#/components/schemas/Rewards-Attribute'
redeemables:
$ref: '#/components/schemas/Redeemables-Attributes'
examples:
default:
value:
balance:
banked_rewards: '376.00'
membership_level: null
membership_level_id: null
net_balance: 376
net_debits: 1100
pending_points: 0
points_balance: 1476
signup_anniversary_day: 09/30
total_credits: 1476
total_debits: '1100.0'
total_point_credits: 1476
total_redeemable_visits: 98
expired_membership_level: null
total_visits: 87
initial_visits: 0
unredeemed_cards: 19
membership_qualification_points: 500
rewards:
- business_id: 603
end_date: null
end_date_tz: null
gaming_level_id: null
gifted_for_type: null
gift_reason: null
id: 1089
location_ids: []
read_at: null
redeemable_id: 1089
reward_properties: null
start_date: '2017-12-14'
start_date_tz: '2017-12-14T13:04:55Z'
external_store_numbers: []
type: redeemable
- business_id: 603
end_date: null
end_date_tz: null
gaming_level_id: null
gifted_for_type: FeedbackReply
gift_reason: Support Activity
id: 17111231
location_ids: []
read_at: '2016-12-12T07:53:20Z'
redeemable_id: 1260
reward_properties: null
start_date: '2016-11-28'
start_date_tz: '2016-11-28T13:56:29Z'
external_store_numbers: []
type: reward
redeemables:
- applicable_as_loyalty_redemption: true
redeemable_properties: null
discount_amount: 0
discount_channel: all
expire_redemption_code_with_reward_end_date: false
id: 1089
image: IMAGE_URL_GOES_HERE
points: 100
redeemable_id: 1089
redemption_expiry: 240
thumb_image: IMAGE_URL_GOES_HERE
name: Free Pizza or Entree Salad @ 100 Points
description: Congrats! You banked a Free Pizza or Entree Salad for earning 100 points!
- applicable_as_loyalty_redemption: false
redeemable_properties: null
discount_amount: 0
discount_channel: null
expire_redemption_code_with_reward_end_date: null
id: 1260
image: IMAGE_URL_GOES_HERE
points: 0
redeemable_id: 1260
redemption_expiry: 240
thumb_image: IMAGE_URL_GOES_HERE
name: Free Cookie
description: Enjoy your free cookie.
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
content:
application/json:
schema:
type: array
items:
type: string
examples:
application/json; charset=utf-8:
value:
- Invalid Signature
'422':
description: Sending invalid Entity
summary: Fetch Account Balance of User
description: 'Returns account balance details of a guest, such as banked_rewards, membership_level,
net_balance, net_debits, pending_points, points_balance, signup_anniversary_day, total_credits,
total_debits, total_point_credits, total_redeemable_visits, etc.
>User authentication required
>
>This API requires authentication_token to be supplied as `HTTP_AUTHORIZATION` header or in the
`authentication_token` parameter.'
operationId: sso_account_balance
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/accept language'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
tags:
- Check User Balance
x-stoplight:
id: 046241990d510
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).
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
/api/auth/rewards:
get:
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Rewards-Attribute'
examples:
application/json; charset=utf-8:
value:
- reward:
id: 309203
business_id: 452
location_id: 302576
user_id: 111111111
redeemable_id: 41
free_punchh_campaign_id: null
redemption_id: null
checkin_id: null
admin_id: null
created_at: '2015-03-31T11:41:52Z'
updated_at: '2015-03-31T11:41:52Z'
code: '907350'
start_date: '2015-03-31'
end_date: '2015-04-29'
read_at: null
gaming_level_id: null
gifted_for_type: SignupCampaign
gifted_for_id: 50
gift_reason: 'Signup: Free Small The Original Sandwich with purchase of chips and
32 oz drink'
location_ids:
- 303133
- 303134
external_store_numbers:
- '3613'
- '3614'
'401':
description: ''
'412':
description: Sending invalid Signature
'422':
description: Sending invalid Entity
summary: List Available Rewards
description: Fetch available rewards or offers details of a user. This request returns how many
rewards are available to the user.
operationId: sso_list_available_rewards
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Authorization'
tags:
- Check User Balance
x-stoplight:
id: 5ba386685f23e
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).
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
/api/auth/users/forgot_password:
post:
responses:
'200':
description: Blank Response.
content:
application/json:
schema: {}
examples:
default:
value: Blank Response
'412':
description: ' Sending invalid Signature'
'422':
description: Sending invalid Entity
summary: Forgot Password
description: Triggers the forgot password email sent to the user's email address containing the
password reset link.
operationId: sso_forgot_password
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
tags:
- User Management
x-stoplight:
id: 6e9f023450f46
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
email:
type: string
description: Email address of the user
required:
- email
client:
type: string
description: Client key of the business
required:
- client
examples:
default:
value:
user:
email: test@example.com
client: CLIENT_GOES_HERE
/api/auth/users:
get:
responses:
'200':
description: ''
co
# --- truncated at 32 KB (246 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-online-ordering-sso-api-openapi.yml