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: '' content: application/json: schema: $ref: '#/components/schemas/user-object' examples: default: value: address_line1: ADDRESS_GOES_HERE anniversary: '2013-07-13' avatar_remote_url: null birthday: '1985-03-21' city: Mountain View created_at: '2016-03-15T06:33:42Z' email: test@example.com email_verified: false fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: male id: 111111111 last_name: LAST_NAME_GOES_HERE state: California updated_at: '2016-03-15T06:38:34Z' zip_code: '94040' allow_multiple: false authentication_token: AUTHENTICATION_TOKEN_GOES_HERE favourite_locations: '304988' 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: null terms_and_conditions: false title: Mr. user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 user_relations: - id: 774 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: spouse birthday: '1984-07-18' wants_menu_notifications: false work_zip_code: null mindbody_client_id: null preferred_locale: '' phone: '1111111111' migrate_status: false email_unsubscribe: false allow_push_notifications: true facebook_signup: false communicable_email: test@example.com access_token: ACCESS_TOKEN_GOES_HERE expiration_date: '2018-07-31' age_verified_status: true summary: Fetch User Information description: Returns the user's details including birthday, anniversary, gender, zip code, etc. operationId: sso_fetch_user_informaton parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' tags: - User Management x-stoplight: id: bcce4b1009ba3 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). client: type: string description: Client key of the business required: - client examples: default: value: authentication_token: AUTHENTICATION_TOKEN_GOES_HERE client: client_key_goes_here put: responses: '200': description: '' 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: profile_question_key: Answer 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' age_verified_status: true sms_subscription: true '401': description: '' '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Update User Information description: "Updates details in the user profile, such as first name, last name, birthday, anniversary,\ \ or change password. \n\nNote: Due to fraud protections, guests are permitted to update their\ \ birthdays only once. Subsequent attempts to modify the birthday parameter using the API will\ \ fail. In such a case, the API returns a 200 response, but the birthday is not updated. " operationId: sso_update_user_information parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' tags: - User Management x-stoplight: id: eef4eef6c97a0 requestBody: content: application/json: schema: type: object properties: 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). user: $ref: '#/components/schemas/user-input-object' required: - client examples: Update user information: value: client: CLIENT_ID_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE user: address_line1: ADDRESS_GOES_HERE anniversary: null avatar_remote_url: URL_GOES_HERE birthday: '1993-01-01' city: Columbus email: test@example.com first_name: FIRST_NAME_GOES_HERE age_verified: true privacy_policy: true gender: female last_name: LAST_NAME_GOES_HERE state: Ohio zip_code: '43016' allow_multiple: true favourite_locations: '' marketing_email_subscription: true marketing_pn_subscription: true profile_field_answers: upf0: Coffee|Tea|Lemonade upf1: Pasta|Pizza|Hamburger upf2: Movies|Music|Sports secondary_email: test@example.com terms_and_conditions: true title: '' user_relations: - relation: spouse name: SPOUSE_NAME_GOES_HERE birthday: '1999-01-01' work_zip_code: '' preferred_locale: '' phone: '1111111111' unsubscribed: true allow_push_notifications: true apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE age_verified_status: true Update access token for an external IDP user: value: client: CLIENT_ID_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE user: external_source: customer_id external_source_id: '11111111111111111111' description: '' /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 /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 /api/auth/accounts: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: date: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the event was created in the system, in ISO 8601 format title: type: string description: Event title event_name: type: string description: Event name (e.g., Checkin, Redemption, etc.) event_value: type: string description: Event value (e.g., Visit, Point, or Item) description: type: string description: Reason for the event sub_value: type: string description: Sub-value of the event x-nullable: true bar_column1: type: string description: Points details bar_column2: type: string description: Visit details x-nullable: true bar_column3: type: string description: Item details points: type: integer description: Total number of points that were redeemed visits: type: integer description: Total number of visits that were redeemed x-nullable: true rewards: type: number format: double description: Total number of rewards that were redeemed items: type: integer description: Total number of items that were redeemed pending_refresh: type: boolean description: If the event is related to a check-in, whether the check-in is pending refresh or not expired: type: boolean description: Whether the event has expired or not disapproved: type: boolean description: Whether the event is disapproved or not level: type: string description: Membership level at the time of the event event_details: type: object description: Details of the event store_number: type: string description: Store number or other external identifier set on the location event_expiry: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Expiry date of the event as configured in the Punchh platform channel: type: string description: Channel where the event took place (e.g., POS) external_uid: type: string description: External UID received at the time of check-in examples: default: value: - date: '2019-05-18T13:15:27Z' title: Item Gifted event_name: Reward event_value: +Item description: 'You were gifted: Sandwich (Signup)' sub_value: null bar_column1: 'Points: 0' bar_column2: 'Punchh: 1' bar_column3: 'Item: 1' points: 0 visits: 1 rewards: 0 items: 1 pending_refresh: false expired: false disapproved: false level: null event_details: null store_number: null event_expiry: '2019-06-26T06:59:59Z' - date: '2019-05-27T15:24:52Z' title: Item Gifted channel: null event_name: Reward event_value: +Item external_uid: null description: 'You were gifted: BOGO Cookie for customers who buy cookies 50% of the time (Expired)' sub_value: null bar_column1: 'Points: 820' bar_column2: null bar_column3: 'Items: 0' points: 820 visits: null rewards: 0 items: 0 pending_refresh: false expired: true disapproved: false level: null event_details: null store_number: null event_expiry: '2019-06-26T06:59:59Z' - date: '2019-05-18T08:20:00Z' title: Points Earned channel: POS event_name: Checkin event_value: +13 points external_uid: '' description: 13 points earned for your $12.86 purchase at Adrian sub_value: null bar_column1: 'Points: 820' bar_column2: null bar_column3: 'Items: 0' points: 820 visits: null rewards: 0 items: 0 pending_refresh: false expired: false disapproved: false level: null event_details: null store_number: '' event_expiry: '2019-06-26' - date: '2019-05-18T08:12:57Z' title: Points Earned channel: POS event_name: Checkin event_value: +13 points external_uid: '' description: 13 points earned for your $12.86 purchase at Adrian sub_value: null bar_column1: 'Points: 807' bar_column2: null bar_column3: 'Items: 0' points: 807 visits: null rewards: 0 items: 0 pending_refresh: false expired: false disapproved: false level: null event_details: null store_number: '' event_expiry: '2019-06-20' summary: Get Account History description: 'Returns the user''s account history details. Event expiry is displayed in date format for check-in and date/time format (ISO 8601) for other events. ' operationId: sso_account_history 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' tags: - User Management x-stoplight: id: b4e529bdacc41 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 description: '' /api/auth/sso: post: responses: '200': description: '' content: application/json: schema: type: object properties: token: type: object properties: access_token: type: string description: Security token that identifies the user user: $ref: '#/components/schemas/user-object' examples: default: value: token: access_token: ACCESS_TOKEN_GOES_HERE user: anniversary: null avatar_remote_url: null birthday: null created_at: '2015-08-18T13:53:06Z' email: test@example.com fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE gender: null id: 111111111 last_name: LAST_NAME_GOES_HERE updated_at: '2015-08-18T13:53:06Z' allow_multiple: false authentication_token: AUTHENTICATION_TOKEN_GOES_HERE favourite_locations: '' preferred_menu_items: [] referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: null user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_relations: [] wants_menu_notifications: false profile_field_answers: {} address_line1: null zip_code: null phone: null migrate_status: false work_zip_code: null email_unsubscribe: null allow_push_notifications: true facebook_signup: false communicable_email: test@example.com access_token: null '400': description: '' '401': description: '' content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string examples: default: value: error: message: Invalid/Expired security token. code: invalid_token summary: Create SSO Access Token operationId: sso_create_acces_token_for_sso 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 description: Generates authentication token using the security token. x-stoplight: id: aa3488b317017 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business security_token: type: string description: Security token required to generate the authentication token. For more information on generating the security token, see [Mobile SSO Flow](https://developers.punchh.com/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#mobile-sso-flow). required: - client - security_token examples: default: value: client: CLIENT_GOES_HERE security_token: SECURITY_TOKEN_GOES_HERE /api/auth/users/change_password: patch: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/user-object' examples: default: value: address_line1: ADDRESS_GOES_HERE anniversary: '2013-07-13' avatar_remote_url: null birthday: '1985-03-21' city: Mountain View created_at: '2016-03-15T06:33:42Z' email: test@example.com email_verified: false fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: male id: 111111111 last_name: LAST_NAME_GOES_HERE state: California updated_at: '2016-03-15T11:57:44Z' zip_code: '94040' allow_multiple: false authentication_token: AUTHENTICATION_TOKEN_GOES_HERE favourite_locations: 304988,304989,304991 marketing_email_subscription: true marketing_pn_subscription: true passcode_configured: false preferred_menu_items: [] profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: null terms_and_conditions: false title: Mr. user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_id: 111111111 user_relations: - id: 774 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: spouse birthday: '1984-07-18' wants_menu_notifications: false work_zip_code: null mindbody_client_id: null phone: null migrate_status: false email_unsubscribe: false allow_push_notifications: true facebook_signup: false communicable_email: test@example.com access_token: null '400': description: '' summary: Change Password operationId: sso_change_password parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - schema: type: string default: Bearer ACCESS_TOKEN_GOES_HERE in: header name: Authorization description: You may pass access_token instead of authentication_token in the Authorization header. It will be passed as a bearer token. If the reset_password_token parameter is included in the request body, an Authorization header is not needed. description: Changes the user's password without using the current password tags: - User Management x-stoplight: id: 08d53a1922d23 requestBody: content: application/json: schema: type: object properties: user: type: object properties: password: type: string description: New password of the user password_confirmation: type: string description: Confirm the new password of the user required: - password 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). reset_password_token: type: string description: The user's reset password token. Required if the access_token is not passed via the Authorization header or the authentication_token parameter is not included in the request body. If the reset_password_token parameter is included in the request body, an Authorization header is not needed. required: - client examples: default: value: user: password: PASSWORD_GOES_HERE password_confirmation: PASSWORD_GOES_HERE client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE /api/auth/users/reset_password_token: post: responses: '200': description: '' content: application/json: schema: type: object properties: reset_password_token: type: string description: Token with which the user can request the password reset token_expire_at: type: string description: Date/time when the reset password token will expire examples: default: value: reset_password_token: RESET_PASSWORD_TOKEN_GOES_HERE token_expire_at: '2016-02-26T23:36:38Z' '400': description: '' operationId: sso_Get_reset_password_token_of_the_user summary: Get Password Reset Token parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' tags: - User Sign-up and SSO description: '' x-stoplight: id: 5e3a4b08fd4ad requestBody: content: application/json: schema: type: object properties: user: type: object properties: email: type: string description: Email address of the user requesting the reset password token required: - email client: type: string description: Client key of the business required: - client examples: default: value: user: email: guest@example.com client: CLIENT_GOES_HERE /api/auth/loyalty_points_estimator: get: responses: '200': description: '' content: application/json: schema: type: object properties: estimated_points: type: integer description: 'System-estimated loyalty points of the user based on the `subtotal_amount` provided in the request. This value depends on the points conversion rate, which can be configured in the Punchh platform. Contact your Punchh representative to update this configuration. ' examples: default: value: estimated_points: 46 summary: Estimate Loyalty Points Earning description: 'Returns a prediction of how many points can be earned before submitting the transaction. The estimate is derived from the base earning rate of the business and does not account for special promotions or campaigns. ' operationId: sso_estimate_loyalty_points_earning parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Rewards x-stoplight: id: f588025c608a3 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 default: AUTHENTICATION_TOKEN_GOES_HERE 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). subtotal_amount: type: number format: float description: Order amount before any taxes (sum of all amounts minus any discounts). This is the amount upon which loyalty points/visits are granted. required: - client - subtotal_amount examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE subtotal_amount: 10 /api/auth/users/balance: get: responses: '200': description: '' content: application/json: schema: type: object properties: active_redemptions: type: array items: type: object challenge_badges: type: array items: type: object properties: badge_id: type: integer description: Badge ID of the challenge challenge_campaign_id: type: integer description: Campaign ID of the challenge published: type: boolean public_url: type: string description: Public URL of the challenge coupons: $ref: '#/components/schemas/Coupons' messages: $ref: '#/components/schemas/Messages' notifications: $ref: '#/components/schemas/Notifications' rewards: $ref: '#/components/schemas/Rewards-Attribute' punch_cards: type: array items: type: object properties: progress: type: array items: type: object properties: completed_steps: type: integer total_steps: type: integer name: type: string description: Name of the card description: type: string description: Description of the card image_url: type: string description: Image URL of the card icon_url: type: string icon_completed_url: type: string start_date: type: string end_date: type: string gift_reason: type: string miscellaneous: type: string challenge_id: type: integer preferred_charities: type: array items: type: object properties: user_donations: type: object properties: reward: type: object properties: user_donations: type: integer last_donated_item: x-nullable: true last_donation_time: x-nullable: true name: type: string description: type: string social_cause_id: type: integer image_url: type: string miscellaneous: type: string city: type: string state: type: string street: type: string zip: type: string phone_number: x-nullable: true email: type: string address: type: string converted_category_balances: $ref: '#/components/schemas/Converted-Category-Balance' account_balance: $ref: '#/components/schemas/Account-balance-details' examples: default: value: converted_category_balances: [] active_redemptions: [] challenge_badges: [] coupons: [] messages: [] notifications: [] rewards: [] punch_cards: [] preferred_charities: [] account_balance: banked_currency: 0 banked_currency_expiring_on: null checkins_on_current_card: 0 current_membership_level_id: null current_membership_level_expiring_on: null expiring_banked_currency: null pending_points: null redeemed_cards: null total_loyalty_visits: null unbanked_points: 0 unredeemed_cards: null current_membership_level_name: null lifetime_points: 0 redeemable_points: 0 membership_qualification_points: 500 summary: Fetch User Balance description: Displays user information regarding active redemptions, notifications, badges, balance, etc. operationId: sso_fetch_user_balance parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - schema: type: string default: no cache in: header name: cache-control - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' tags: - Check User Balance x-stoplight: id: 67319738d3ef8 requestBody: content: application/json: schema: type: object properties: 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: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE /api/auth/conversions: post: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - 250 points converted into 2 summary: Convert Points description: Converts points to cash, fuel discounts, and charities based on the configuration or conversion rules set in the Punchh platform operationId: sso_points_conversion_api parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content type' tags: - Rewards x-stoplight: id: d23537781e07c 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 default: AUTHENTICATION_TOKEN_GOES_HERE conversion_rule_id: type: integer description: Conversion rule ID set for the Punchh platform configuration (returned for the converted_category_balances object as category_id) format: int32 source_value: type: integer format: int32 description: Number of points the user wants to convert to cash, fuel discounts, or charities converted_value: type: integer description: Values of the cash, fuel discounts, or charities converted from points format: int32 social_cause_campaign_id: type: string description: Campaign ID in case of points converted to charity required: - client - conversion_rule_id - source_value - converted_value examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE conversion_rule_id: 8 source_value: 100 converted_value: 10 social_cause_campaign_id: '12' /api/auth/deals: get: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/deals' examples: default: value: - applicable_as_loyalty_redemption: false redeemable_properties: '' discount_amount: 0 discount_channel: all expire_redemption_code_with_reward_end_date: false id: 23 image: IMAGE_URL_GOES_HERE points: 0 redeemable_id: 23 redemption_expiry: 240 thumb_image: IMAGE_URL_GOES_HERE meta_data: '' redeemable_uuid: ID_GOES_HERE name: BOGO Breadsticks description: '' start_time: '2021-04-28T13:59:47+05:30' '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: List All Deals description: Returns all available deals for a user operationId: sso_list_all_deals parameters: - $ref: '#/components/parameters/Signature' - schema: type: string default: no-cache in: header name: cache-control - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Deals x-stoplight: id: 40844ae91bcb3 requestBody: content: application/json: schema: type: object properties: client: type: string default: CLIENT_GOES_HERE description: Client key of the business authentication_token: type: string default: AUTHENTICATION_TOKEN_GOES_HERE 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 post: responses: '200': description: '' content: application/json: schema: type: object properties: {} '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Save Selected Deals description: Adds the selected deal to the user's account operationId: sso_save_selected_deals parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' tags: - Deals x-stoplight: id: 06e600d4accdf 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 default: AUTHENTICATION_TOKEN_GOES_HERE 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). redeemable_uuid: type: string description: Redeemable UUID of the deal to be saved by the user default: REDEEMABLE_UUID_GOES_HERE required: - client - redeemable_uuid examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE redeemable_uuid: REDEEMABLE_UUID_GOES_HERE /api/auth/deals/{redeemable_uuid}: get: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/deals' examples: default: value: redeemable_image_url: IMAGE_URL_GOES_HERE redeemable_properties: '' redeemable_id: 36 name: Large Pizza (Box Top Pizza) description: '' points_required_to_redeem: null meta_data: '' expiry_days: null expiring_at: null discount_amount: null created_at: '2019-05-31T20:04:54Z' redeemable_uuid: ID_GOES_HERE start_time: '2021-04-28T13:59:47+05:30' '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Get Deal Details description: Returns the details of the deal operationId: sso_get_the_deal_detail parameters: - $ref: '#/components/parameters/Signature' - schema: type: string in: path name: redeemable_uuid required: true description: UUID that uniquely identifies the redeemable - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/accept language' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Deals x-stoplight: id: 31b74446c54ab requestBody: content: application/json: schema: type: object properties: client: type: string default: CLIENT_GOES_HERE 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). default: AUTHENTICATION_TOKEN_GOES_HERE required: - client examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE description: '' parameters: - schema: type: string name: redeemable_uuid in: path required: true /api/auth/estimate_points: get: responses: '200': description: '' content: application/json: schema: type: object properties: estimated_points: type: integer description: System-estimated loyalty points of the user based on the subtotal_amount provided in the request. This value depends on the points conversion rate, which can be configured in the Punchh platform. Contact your Punchh representative to update this configuration. examples: default: value: estimated_points: 200 summary: Estimate Points Earning description: Returns a prediction of how many points can be earned before submitting the transaction. The estimate is derived from the base earning rate of the business and does not account for special promotions or campaigns. operationId: sso_estimate_points_earning parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Rewards x-stoplight: id: bce80fc26cf46 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 default: AUTHENTICATION_TOKEN_GOES_HERE menu_items: $ref: '#/components/schemas/menu_items' subtotal_amount: type: number format: float 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_amount: type: number 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. format: double required: - client - subtotal_amount - receipt_amount examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE menu_items: - item_name: White rice item_qty: 1 item_amount: 2 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: 8 menu_item_type: M menu_item_id: '3418' menu_family: '800' menu_major_group: '152' serial_number: '2.0' subtotal_amount: 10 receipt_amount: 10 /api/auth/balance_timelines: get: responses: '200': description: '' content: application/json: schema: type: object properties: currency: type: array items: type: object properties: actual_earned_currency: type: number format: float description: Actual earned currency at the time of conversion unredeemed_currency: type: number format: float description: Remaining currency available to redeem expiration_date: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Expiration date of the conversion status: type: string description: 'Status of the entire conversion. The values can be: partially_redeemed, unredeemed, honored, partially_redeemed_expired, unredeemed_expired' x-nullable: true fuel_discount: type: array items: type: object properties: actual_earned_currency: type: number format: float unredeemed_currency: type: number format: float expiration_date: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time status: type: string examples: default: value: currency: - actual_earned_currency: 2 unredeemed_currency: 0 expiration_date: null status: honored - actual_earned_currency: 1 unredeemed_currency: 0 expiration_date: '2019-07-17T23:59:59-05:00' status: null - actual_earned_currency: 10 unredeemed_currency: 4 expiration_date: '2019-07-17T23:59:59-05:00' status: unredeemed_expired fuel_discount: - actual_earned_currency: 0.05 unredeemed_currency: 0.05 expiration_date: '2019-08-15T23:59:59-05:00' status: unredeemed - actual_earned_currency: 0.5 unredeemed_currency: 0.5 expiration_date: '2019-08-15T23:59:59-05:00' status: unredeemed '400': description: '' summary: Balance Timelines description: Gets balance timelines of the user operationId: sso_balance_timelines 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 User Balance x-stoplight: id: cb5962b14aa0b 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/user_enrollments: post: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - Successfully registered '400': description: '' summary: User Enrollment description: Enrolls a user in a campaign (currently supported for social cause campaigns) operationId: sso_user_enrollment parameters: - $ref: '#/components/parameters/Signature' - schema: type: string default: no-cache in: header name: cache-control - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/content type' tags: - User Management x-stoplight: id: 6da2a2909eae2 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). item_id: type: integer description: ID of the campaign in which the user will be enrolled default: 1 format: int32 item_type: type: string description: Type of the campaign in which the user will be enrolled. The currently supported type is `social_cause_campaign`. default: social_cause_campaign enum: - social_cause_campaign required: - client - item_id - item_type examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE item_id: 1 item_type: social_cause_campaign delete: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - Successfully deregistered '201': description: Created content: application/json: schema: type: object properties: ? '' : type: string '400': description: '' summary: User Disenrollment description: Disenrolls a user from a campaign (currently supported for social cause campaigns) operationId: sso_user_disenrollment parameters: - $ref: '#/components/parameters/Signature' - schema: type: string default: no-cache in: header name: cache-control - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' tags: - User Management x-stoplight: id: f79a7ffc641d7 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). item_id: type: integer description: ID of the campaign in which the user will be enrolled default: 1 format: int32 item_type: type: string description: Type of the campaign in which the user will be enrolled. The currently supported type is `social_cause_campaign`. default: social_cause_campaign enum: - social_cause_campaign required: - client - item_id - item_type examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE item_id: 1 item_type: social_cause_campaign /api/auth/ordering_meta: get: responses: '200': description: '' content: application/json: schema: type: object properties: base_redeemable_name: type: string description: Name of the base reedemable base_redeemable_description: type: string description: Description of the base reedemable base_redeemable_image: type: string description: Image of the base reedemable base_redeemable_properties: type: - string - 'null' description: Properties of the base reedemable examples: default: value: base_redeemable_name: 'Punch Card = FREE Adult Buffet or Carryout 1-Topping Pizza ' base_redeemable_description: 'You just earned yourself an awesome reward! Now, you get to choose a FREE Adult Buffet or your favorite Carryout 1-Topping Pizza. Either way, you win. *To redeem, use your Punch Card Reward when ordering online or through the MyAcme App.' base_redeemable_image: IMAGE_URL_GOES_HERE base_redeemable_properties: null '400': description: Sending invalid credentials '412': description: Sending invalid Signature summary: Ordering Meta description: Retrieves information about the base redeemable operationId: sso_ordering_meta parameters: - $ref: '#/components/parameters/Signature' - schema: type: string default: base_redeemable in: query name: filter required: true description: Send "base_redeemable" to get metadata about the redeemable - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' tags: - Rewards x-stoplight: id: 7108126712419 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 x-stoplight: id: h11lxep7b4xy6 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](https://developers.partech.com/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile). required: - client examples: default: value: client: CLIENT_GOES_HERE /api/auth/offers: get: responses: '200': description: '' content: application/json: schema: type: object properties: pinned_message: type: string description: Message attached with available offers rewards: $ref: '#/components/schemas/Rewards-Attribute' notifications: $ref: '#/components/schemas/Notifications' redeemables: $ref: '#/components/schemas/Redeemables-Attributes' examples: default: value: pinned_message: '' rewards: - code: '531611' id: 1014491 business_id: 470 redeemable_id: 105 start_date: '2015-06-16' end_date: '2015-07-15' read_at: null start_date_tz: '2015-06-15T18:30:00Z' end_date_tz: '2015-07-15T18:29:59Z' gaming_level_id: null gifted_for_type: Admin gift_reason: Admin Generosity location_ids: - 303133 - 303134 external_store_numbers: - '3613' - '3614' notifications: - id: 8415352 message: notification message user_id: 111111111 token: null sent_at: '2015-05-28T17:03:27Z' kind: campaign network: null status: sent deleted_at: null created_at: '2015-05-28T17:03:26Z' updated_at: '2015-05-28T17:03:27Z' read_at: null business_name: BUSINESS_NAME_GOES_HERE sent_at_tz: '2015-05-28T11:03:27-06:00' redeemables: - description: Free Soft Drink (600 ml) when you purchase a Pizza!! discount_amount: 700 id: 105 image: /images/punchh-icon-small.png name: Free Soft Drink Offer! points: 0 redeemable_id: 105 thumb_image: /images/punchh-icon-thumb.png applicable_as_loyalty_redemption: null '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Fetch Available Offers description: Fetches available offers or offer details of a user. This request returns how many offers are available to the user. operationId: sso_auth_fetchavailableoffers parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' tags: - Rewards x-stoplight: id: ba92ee7891a30 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). client: type: string description: Client key of the business required: - client examples: default: value: authentication_token: AUTHENTICATION_TOKEN_GOES_HERE client: CLIENT_GOES_HERE /oauth/token: post: responses: '200': description: '' content: application/json: schema: type: object properties: access_token: type: string description: Client instance-level access token that your application can use to retrieve the access and authentication token of the user token_type: type: string description: Type of security token (e.g., bearer) refresh_token: type: string description: Refresh token that the client application can use to get a new access token scope: type: string description: Actions or data the bearer of the token is allowed to perform or access created_at: type: string format: date-time description: Date and time in epoch format examples: - '1695818361' examples: default: value: access_token: ACCESS_TOKEN_GOES_HERE token_type: Bearer refresh_token: REFRESH_TOKEN_GOES_HERE scope: 'null' created_at: '1695818361' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string examples: - invalid_client error_description: type: string examples: - Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method. examples: Missing authentication code parameter or code is expired: value: error: invalid_grant error_description: The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. Missing client parameter or client value is incorrect: value: error: invalid_client error_description: Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method. Missing redirect URI or redirect URI is incorrect: value: error: invalid_request error_description: The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. summary: Get SSO Token description: 'Retrieves a client instance-level access token from your redirect URI after a successful user login through the Punchh-hosted authentication form. After you retrieve the client-level access token from this endpoint, supply it to the [Fetch User Information](/docs/dev-portal-online-ordering/b3A6NTAyODQ5NzA-fetch-user-information) API to retrieve a user-level authentication or access token. You can then use that user-level token to authenticate API calls for the remainder of the user''s session. **Note:** This endpoint is the second step in a multi-step authorization process. For more information, see [SSO Flow for Web and Mobile](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#step-2).' operationId: oauth_token parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' tags: - User Sign-up and SSO x-stoplight: id: 70d60c1db9257 requestBody: content: application/json: schema: type: object properties: client_id: type: string description: OAuth client ID of the business client_secret: type: string description: OAuth client secret of the business redirect_uri: type: string description: Redirect URI configured in the OAuth app where users are sent after a successful user login through the Punchh-hosted authentication form grant_type: type: string x-stoplight: id: jshu6v4hp9ek1 default: authorization_code description: Grant type the Punchh server will use to generate the access token code: type: string description: Authorization code retrieved from the redirect URL after a successful user login. See [SSO Flow for Web and Mobile](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile#web-sso-flow) required: - client_id - client_secret - redirect_uri - grant_type - code examples: default: value: code: TOKEN_GOES_HERE client_id: CLIENT_GOES_HERE client_secret: SECRET_GOES_HERE grant_type: authorization_code redirect_uri: https://redirect-uri.com/auth description: '' parameters: [] /api/auth/users/connect_with_facebook: post: responses: '200': description: The response returns basic details about the user account, including the access token that you must use to authenticate other API calls on the user's behalf. content: application/json: schema: type: object properties: access_token: description: Security token that identifies the user type: string address_line1: type: string description: 'Address information (part 1) of the user ' anniversary: type: string enum: - YYYY-MM-DD format: date description: Anniversary of the user, in YYYY-MM-DD format avatar_remote_url: type: string description: Avatar URL of the user profile image birthday: type: string enum: - YYYY-MM-DD format: date description: Birthday of the user, in YYYY-MM-DD format city: type: string description: 'City where the user lives ' created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user was created in the system, in ISO 8601 format email: type: string description: Email address of the user email_verified: type: boolean description: Whether the email address is verified or not fb_uid: type: integer description: Unique Facebook ID of the User first_name: type: string description: First name of the user gender: type: string description: Gender of the user (e.g., male or female) id: type: integer description: Unique ID of the user last_name: type: string description: Last name of the user state: type: string description: State where the user lives updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user was updated in the system, in ISO 8601 format zip_code: type: string description: Zip code of the user allow_multiple: type: boolean description: Whether multiple check-ins are allowed for the user or not 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). favourite_locations: type: string description: List of the user's favorite locations favourite_store_numbers: type: string description: List of store numbers of the user's favorite locations marketing_email_subscription: type: boolean description: Whether the user has subscribed to receive marketing emails or not marketing_pn_subscription: type: boolean description: Whether the user has subscribed to receive marketing push notifications or not passcode_configured: type: boolean description: Whether the passcode has been configured or not profile_field_answers: type: object referral_code: type: string description: Referral code of the user to refer other users referral_path: type: string description: URL that points to the referred path secondary_email: type: string description: Secondary email address of the user terms_and_conditions: type: boolean description: Whether the user has agreed to the terms and conditions to use the app as per the configuration title: type: string description: Title used for the user (e.g., Mr., Mrs., etc.) user_as_barcode: type: integer description: Unique user ID in barcode format user_as_qrcode: type: string description: Unique user ID in QR code format user_code: type: string user_id: type: integer description: Unique user ID user_relations: $ref: '#/components/schemas/user-relations' wants_menu_notifications: type: boolean description: Whether the user wants to receive menu notifications or not work_zip_code: description: 'Zip code of the user''s office ' x-nullable: true mindbody_client_id: x-nullable: true preferred_locale: type: string description: Preferred locale of the user phone: type: string description: Phone number of the user migrate_status: type: boolean description: Whether the user has been migrated or not email_unsubscribe: type: string description: Unsubscribed email address of the user allow_push_notifications: type: boolean description: Whether the user has allowed push notifications or not facebook_signup: type: boolean description: Indicates whether the user signed up using Facebook. This parameter returns true the first time a user signs up using Facebook. For all subsequent logins, it returns a false value. communicable_email: type: string description: Email address where emails should be sent expiration_date: type: string enum: - YYYY-MM-DD format: date description: This value will be returned only if "Account re-evaluation strategy" is set to Guest Inactivity. All other cases return a NULL value. x-nullable: true age_verified_status: type: boolean x-stoplight: id: 91hldu9l3f9wc description: 'Whether or not the user has undergone age verification by Koupon Media. Possible values: true, false. The value is set to true if the user''s age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs 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. ' examples: default: value: access_token: ACCESS_TOKEN_GOES_HERE address_line1: ADDRESS_GOES_HERE allow_multiple: false allow_push_notifications: true anniversary: '2015-05-17' authentication_token: AUTHENTICATION_TOKEN_GOES_HERE avatar_remote_url: null birthday: '1990-05-17' communicable_email: test@example.com created_at: '2015-12-08T10:57:35Z' email: test@example.com email_unsubscribe: null email_verified: false facebook_signup: false favourite_locations: '30245' favourite_store_numbers: '1023' fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: male id: 111111111 last_name: LAST_NAME_GOES_HERE marketing_email_subscription: false marketing_pn_subscription: false migrate_status: false passcode_configured: false phone: 1111111111 preferred_menu_items: [] profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com terms_and_conditions: false title: '' updated_at: '2016-01-07T09:24:27Z' user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_id: 111111111 user_relations: - id: 229 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: kid birthday: '2013-12-31' - id: 230 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: spouse birthday: '1992-12-31' wants_menu_notifications: false work_zip_code: null zip_code: '70001' expiration_date: '2018-07-31' age_verified_status: true '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Log in With Facebook description: This API is invoked when a user registers on a business app using Facebook ID, email address, first name, last name, etc. On success, the API returns the user's profile details. operationId: sso_connect_with_facebook parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/accept language' - $ref: '#/components/parameters/User-Agent' tags: - User Sign-up and SSO x-stoplight: id: 6d2912e1c25a4 requestBody: content: application/json: schema: type: object properties: access_token: type: string description: Access token provided by Facebook email: type: string description: Email address of the user for sign-up birthday: type: string enum: - YYYY-MM-DD format: date description: 'Birthday of the user ' anniversary: type: string description: Anniversary of the user send_compliance_sms: type: boolean description: Send true to trigger the compliance/opt-in SMS message for the user. 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 the 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 unsubscribed: type: boolean description: 'Whether the user has unsubscribed from emails and notifications or not ' secondary_email: type: string description: Secondary email address of the user app_device_id: type: string description: Device ID of the mobile app 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 country: type: string description: Country where the user lives 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: Invitation code that the user can use to invite other users 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' client: type: string description: 'Client key of the business ' fb_uid: type: string description: Facebook ID of the user age_verified_status: type: boolean x-stoplight: id: h65jgoyr9f8pm 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: - access_token - email - client examples: default: value: access_token: ACCESS_TOKEN_GOES_HERE address_line_1: ADDRESS_GOES_HERE anniversary: '2015-05-17' apn_token: APN_TOKEN_GOES_HERE app_device_id: APP_DEVICE_ID_GOES_HERE birthday: '1990-05-17' cell_phone: +1-111-111-1111 client: CLIENT_GOES_HERE country: USA email: test@example.com fav_location_id: 30245 fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE gender: male invite_code: DianeM97 last_name: LAST_NAME_GOES_HERE password: PASSWORD_GOES_HERE password_confirmation: PASSWORD_GOES_HERE secondary_email: test@example.com state: Ohio unsubscribed: false user_relations: - id: 229 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: kid birthday: '2013-12-31' - id: 230 name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE relation: spouse birthday: '1992-12-31' work_zip_code: '1234556' zip_code: '70001' age_verified_status: true /api/auth/users/connect_with_apple: 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. Additionally, an access token is provided for the same purpose. content: application/json: schema: type: object properties: access_token: $ref: '#/components/schemas/Access_token-object' user: $ref: '#/components/schemas/User-object-mobile' examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null refresh_token: REFRESH_TOKEN_GOES_HERE scopes: [] user: address: null anniversary: null avatar_remote_url: null birthday: null city: null communicable_email: test@example.com created_at: '2020-09-09T06:56:37Z' email: test@example.com email_verified: false facebook_signup: null apple_signup: null apple_uid: APPLE_UID_GOES_HERE favourite_location_ids: '' favourite_store_numbers: '' fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: null has_generated_fb_email: false last_name: LAST_NAME_GOES_HERE marketing_email_subscription: false marketing_pn_subscription: false migrate_status: false passcode_configured_for_giftcards: false phone: null profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: null state: null superuser: false terms_and_conditions: false title: null updated_at: '2020-09-09T07:48:41Z' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 preferred_locale: null user_relations: [] zip_code: null verification_mode: null sms_subscription: false age_verified_status: true '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: authentication_failed: type: array items: type: string summary: Log in With Apple description: A user can sign in with Apple using a random email ID generated by Apple on the web. The generated authorization code corresponds to each redirect URI as provided in the `redirect_uri` request parameter. operationId: Sign_in_with_apple parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/accept language' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' tags: - User Sign-up and SSO x-stoplight: id: bfb567810d1f9 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business redirect_uri: type: string description: The URI used when authenticating with Apple user: type: object properties: first_name: type: string description: First name of the user last_name: type: string description: Last name of the user email: type: string description: Email address of the user external_source_id: type: string description: Apple ID of the user authorization_code: type: string description: Unique authorization code generated by Apple for every request (expires after 5 minutes) age_verified_status: type: boolean x-stoplight: id: o82we382wv69j 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: - first_name - last_name required: - client examples: default: value: client: CLIENT_GOES_HERE redirect_uri: https://redirect-uri.com/auth/apple user: first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE email: test@example.com external_source_id: SOURCE_ID_GOES_HERE authorization_code: AUTHORIZATION_CODE_GOES_HERE age_verified_status: true description: '' /api/auth/users/connect_with_google: post: summary: Log in With Google operationId: post-api-auth-users-connect_with_google responses: '200': description: Success Response - 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. Additionally, an access token is provided for the same purpose. content: application/json: schema: type: object properties: address_line1: type: string description: Address of the user anniversary: type: string description: Anniversary date of the user, in YYYY-MM-DD format avatar_remote_url: type: string description: URL of the user's profile image uploaded to an online file storage system. This will be used for users who signed up using email. birthday: type: string description: Date of birth of the user, in YYYY-MM-DD format city: type: string description: City where the user lives created_at: type: string description: Date/time when the user was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format format: date-time enum: - YYYY-MM-DDThh:mm:ssZ examples: - '2023-08-18T12:32:13Z' email: type: string description: Unique email address used to identify the user email_verified: type: boolean description: Whether the email address of the user has been verified or not fb_uid: type: string description: Facebook ID that identifies the user first_name: type: string description: First name of the user age_verified: type: boolean description: Whether the age of the user has been verified or not. A value is shown when the business-level age verification is enabled. privacy_policy: type: boolean description: Whether the user has agreed to the privacy policy to use the app as per the configuration. A value is shown when the business-level privacy policy is enabled. gender: type: string description: Gender of the user id: type: integer description: Unique ID of the user last_name: type: string description: Last name of the user state: type: string description: State where the user lives updated_at: type: string format: date-time description: Date/time when the user was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ examples: - '2023-08-18T12:32:13Z' zip_code: type: string description: Zip code where the user lives test_user: type: boolean description: Whether the user is allowed to switch the environment in the Web application or not allow_multiple: type: boolean description: Whether multiple check-ins are allowed for the user or not authentication_token: type: string description: Authentication token of the user that identifies the user making the API request auth_token: type: object description: An authentication token is needed to identify the user making the API request. properties: token: type: string description: Authentication token of the user that identifies the user making the API request seconds_to_expire: type: integer description: Number of seconds after which the token expires. A NULL value for this parameter means the token does not expire. revoked_at: type: string format: date-time description: Date and time when the token was created in the system in ISO 8601 format. A NULL value for this parameter means the token has not been revoked yet. enum: - YYYY-MM-DDThh:mm:ssZ refresh_token: type: string description: Refresh token that the client application can use to get a new access token scopes: type: array description: Actions or data the bearer of the token is allowed to perform or access items: type: string favourite_locations: type: string description: List of the user's favorite locations favourite_store_numbers: type: string description: List of store numbers of the user's favorite locations marketing_email_subscription: type: boolean description: Whether the user has subscribed to receive marketing emails or not marketing_pn_subscription: type: boolean description: Whether the user has subscribed to marketing push notifications or not passcode_configured: type: string description: Whether the passcode has been configured or not profile_field_answers: $ref: '#/components/schemas/profile_field_answers' referral_code: type: string description: Referral code of the user referral_path: type: string description: Referral URL of the user secondary_email: type: string description: The secondary email address of the user is configured when a user signs up with Google but does not share the email address. The app asks for an alternate email address, which is kept as the `secondary_email`. terms_and_conditions: type: boolean description: Whether the terms and conditions of a business have been accepted by a user or not title: type: string description: Salutation as selected by the user user_as_barcode: type: string description: Barcode that identifies the user user_as_qrcode: type: string description: QR code that identifies the user user_code: type: string description: A unique ID that identifies the user. This smaller code can be converted to a QR code in the app and scanned at some POS systems that do not support longer codes. Alternatively, a user could give this to the POS operator if the POS does not have a scanner. user_id: type: integer description: ID that identifies the user user_relations: $ref: '#/components/schemas/user-relations' work_zip_code: type: string description: Zip code of the user's office preferred_locale: type: string description: Preferred locale of the user force_password_reset: type: boolean description: Whether the password of the user matches the password policy set in the Punchh platform or not. Contact your Punchh representative for more information about this Punchh platform configuration. expiration_date: type: string description: Last user inactivity date increased by inactive days set for the business. This value is returned only if "Account re-evaluation strategy" is set to Guest Inactivity. All other cases return a NULL value. format: date sms_subscription: type: boolean description: Whether the user has subscribed to SMS services or not phone: type: string description: Phone number of the user migrate_status: type: boolean description: Whether the user has a migrate status or not email_unsubscribe: type: boolean description: Whether the user has unsubscribed to email notifications or not allow_push_notifications: type: boolean description: Whether the user has subscribed to receive push notifications or not facebook_signup: type: boolean description: Indicates whether the user signed up using Facebook. This parameter returns true the first time a user signs up using Facebook. For all subsequent logins, it returns a false value. communicable_email: type: string description: Email address used for communication with the user access_token: type: string description: Access token of the user that identifies the user making the API request verification_mode: type: string description: Mode of verification (available only for a user in awaiting migration state) apple_signup: type: boolean description: Whether the user has an Apple sign-up or not. This will return true for the first time sign-up. apple_uid: type: string description: Unique ID generated by Apple age_verified_status: type: boolean x-stoplight: id: 9mqoljk86kfbq description: 'Whether or not the user has undergone age verification by Koupon Media. Possible values: true, false. The value is set to true if the user''s age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs 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. ' examples: default: value: address_line1: ADDRESS_GOES_HERE anniversary: null avatar_remote_url: null birthday: '1999-01-01' city: Mountain View created_at: '2023-05-24T13:25:23Z' email: test@example.com email_verified: false fb_uid: null first_name: FIRST_NAME_GOES_HERE age_verified: false privacy_policy: false gender: female id: 94731770 last_name: LAST_NAME_GOES_HERE state: California updated_at: '2023-05-25T06:29:55Z' zip_code: '45672' test_user: false allow_multiple: false authentication_token: AUTHENTICATION_TOKEN_GOES_HERE auth_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null refresh_token: REFRESH_TOKEN_GOES_HERE scopes: - wifi favourite_locations: '' favourite_store_numbers: '1023' marketing_email_subscription: false marketing_pn_subscription: false passcode_configured: false profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com terms_and_conditions: false title: null user_as_barcode: '11111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 94731770 user_relations: [] work_zip_code: null preferred_locale: en force_password_reset: null expiration_date: null sms_subscription: false phone: '1111111111' migrate_status: false email_unsubscribe: true allow_push_notifications: false facebook_signup: false communicable_email: test@example.com access_token: ACCESS_TOKEN_GOES_HERE verification_mode: null apple_signup: false apple_uid: null age_verified_status: true '400': description: Bad Request - Client ID missing or the value is empty content: application/json: schema: type: object properties: errors: type: object examples: Client ID missing or the value is empty: value: errors: client: Required parameter missing or the value is empty. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array items: {} examples: Google Sign-in is enabled but the client ID is not configured: value: errors: - Google sign-in client ID not configured. Platform configuration is not enabled: value: errors: - Google sign-in not enabled. Passing an invalid Google ID token: value: errors: - Google Id Token is not valid. tags: - User Sign-up and SSO description: 'This API enables users to log in using Google Sign-in on the Web. The following must be configured for the business in the Punchh platform to make a successful call to the API: * Google sign-in must be enabled. * Google web client ID, Google iOS client ID / Google Andriod client ID, and Google web client secret must be specified. Contact your Punchh representative to update these configurations.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/accept language' requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business google_id_token: type: string description: Token received from Google first_name: type: string description: First name of the user last_name: type: string description: Last name of the user privacy_policy: type: boolean description: Whether the user has agreed to the privacy policy to use the app as per the configuration. Required when the business-level privacy policy is enabled. age_verified: type: boolean description: Whether the age of the user has been verified or not. Required when the business-level age verification is enabled. phone: type: string description: Phone number of the user birthday: type: string description: Date of birth of the user, in YYYY-MM-DD format favourite_location_ids: type: string description: Favorite location IDs of the user secondary_email: type: string description: The secondary email address of the user is configured when a user signs up with Google but does not share the email address. The app asks for an alternate email address, which is kept as the `secondary_email`. marketing_email_subscription: type: boolean description: Whether the user has subscribed to receive marketing emails or not marketing_pn_subscription: type: boolean description: Whether the user has subscribed to marketing push notifications or not anniversary: type: string description: Anniversary date of the user enum: - YYYY-MM-DD zip_code: type: string description: Zip code where the user lives address: type: string description: Address of the user city: type: string description: City where the user lives state: type: string description: State where the user lives gender: type: string description: Gender of the user terms_and_conditions: type: boolean description: Whether the terms and conditions of a business have been accepted by a user or not send_compliance_sms: type: boolean description: Send a value of true to trigger the compliance/opt-in SMS message for the user. The user will receive an opt-in SMS message only if the configuration is set up correctly on the Punchh platform. See [Implementing SMS Marketing](/docs/dev-portal-mobile/02814dcf572d5-implementing-sms-marketing) age_verified_status: type: boolean x-stoplight: id: kodeguipznncb 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: - client - google_id_token examples: default: value: client: CLIENT_KEY_GOES_HERE google_id_token: GOOGLE_ID_TOKEN_GOES_HERE first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE privacy_policy: true age_verified: false phone: 1111111111 birthday: '1999-01-01' favourite_location_ids: '304155' secondary_email: test@example.com marketing_email_subscription: true marketing_pn_subscription: true anniversary: '2013-07-13' zip_code: '30201' address: ADDRESS_GOES_HERE city: Mountain View state: California gender: female send_compliance_sms: true terms_and_conditions: true age_verified_status: true tags: - name: User Sign-up and SSO - name: Check User Balance - name: Check-in - name: User Management - name: Rewards - name: Deals x-stoplight: id: 73bbc35439926 openapi: 3.1.1 servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com components: schemas: Access_token-object: type: object description: An access token`is needed to identify the user making the API request. title: Access Token (Object) x-stoplight: id: 9ead861cdb7e6 properties: token: type: string description: App-specific access token of the given user. seconds_to_expire: type: integer description: Number of seconds after which the token expires. A NULL value for this parameter means the token does not expire. revoked_at: type: string description: Date and time when the token was created in the system in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format. A NULL value for this parameter means the token has not been revoked yet. enum: - YYYY-MM-DDThh:mm:ssZ format: date-time refresh_token: type: string description: Refresh token that the client application can use to get a new access token scopes: type: array description: Actions or data the bearer of the token is allowed to perform or access items: type: string Account-Balance: type: object title: Account Balance Attributes (Object) x-stoplight: id: eaa5f08504941 properties: banked_rewards: type: number format: double description: Banked rewards value of the current account membership_level: type: string description: Membership level of the current account membership_level_id: type: integer description: ID of membership level net_balance: type: number description: Net balance of the current account format: double net_debits: type: number description: Net debits of the current account format: double pending_points: type: integer description: Pending points of the current account points_balance: type: number description: Points balance of the current account format: double signup_anniversary_day: type: string description: Sign-up anniversary day of the current account total_credits: type: number description: Total credits of the current account format: double total_debits: type: number description: Total debits of the current account format: double total_point_credits: type: number description: Total point credits of the current account format: double total_redeemable_visits: type: integer description: Total redeemable visits of the current account expired_membership_level: type: string description: Expired membership level (if any) of the current account x-nullable: true total_visits: type: integer description: Total number of loyalty visits initial_visits: type: integer description: Visits registered before migration unredeemed_cards: type: integer description: Number of unredeemed cards of the user membership_qualification_points: type: integer x-stoplight: id: o3fwt1pmd6lil description: 'The value of points earned toward progress across membership tiers. This is related to the migration strategy that allows businesses to "Consider Only Initial Points for Tier Migration". Currently, support for this parameter is limited to program type Points Unlock Redeemables, Membership Re-evaluation Strategy: Reset Based on Points Earned and Account Re-evaluation Strategy of Guest Inactivity.' Account-balance-details: type: object title: Account Balance Details (Object) x-stoplight: id: 581d141f4c275 properties: banked_currency: type: number format: float description: Value of the currency that a user has available. A "null" value indicates that the business does not support banking of points into currency. Use it only if the business opted for the Points Convert to Banked Currency program. checkins_on_current_card: type: integer description: "A card gets completed after a user does a configured number of check-ins. \nFor\ \ example, if a business configuration requires 7 check-ins to complete a card, and a user\ \ does only 3 check-ins, the value of this parameter will be 3. This is useful for the Visit-based\ \ program." current_membership_level_id: description: Unique ID of the current membership level of a user type: integer current_membership_level_expiring_on: type: string description: If a business has a rolling expiry of membership levels, a particular membership level will expire after a period that is configured in the Punchh platform. A "null" value indicates that the business does not have a rolling expiry of membership levels. enum: - YYYY-MM-DD format: date expiring_banked_currency: type: number format: float description: If a business has expiring banked currency configured in the Punchh platform, the banked currency will expire in a FIFO (first-in, first-out) pattern. This returns the value of the banked currency that will expire. A "null" value indicates that the business is not configured to support expiring banked currency. banked_currency_expiring_on: type: string description: If a business is configured to support expiring banked currency, this returns the date on which it will expire. A "null" value indicates that the business is not configured to support expiring banked currency. enum: - YYYY-MM-DD format: date pending_points: type: number format: float description: Points of a user that are in the pending state after a check-in. They are not added to the user's account before finalization. See [Pending Points Feature Overview](/docs/dev-portal-pos/ZG9jOjUwMjgzOTAz-pending-points-feature-overview) for details. redeemed_cards: type: integer description: The number of cards that a user has redeemed in the user's lifetime total_loyalty_visits: type: integer description: Total of the visits that a user has earned by doing loyalty check-ins and those visits that were migrated from an older loyalty program (if a business had an older loyalty program and wants to migrate its users to Punchh's loyalty program) x-nullable: true unredeemed_cards: type: integer description: Total unredeemed cards available to a user. If working with a Visit-based program, this value lets you know if the user has unredeemed cards or not. x-nullable: true current_membership_level_name: type: string description: Current membership level of the user x-nullable: true lifetime_points: type: number format: float description: Sum of all loyalty points earned by a user from the time the user signed up redeemable_points: type: number format: float description: 'The total of all loyalty points earned by a user that satisfy all of the following conditions: * approved * non-pending * unexpired. This is useful if working with the Points Unlock Redeemables program. This provides the available points for the guest to redeem.' unbanked_points: type: number format: float description: For a business that allows banking of points, this value represents the number of points the user has and has not banked yet. For example, if a business configuration requires 100 points to be banked to $10, and a user has accumulated 55 points, this value will be 55. When the user earns another 45 points, the user will be banked to $10 and this value will then become 0. membership_qualification_points: type: integer x-stoplight: id: ymt1v0qs8l7oj description: 'The value of points earned toward progress across membership tiers. This is related to the migration strategy that allows businesses to "Consider Only Initial Points for Tier Migration". Currently, support for this parameter is limited to program type Points Unlock Redeemables, Membership Re-evaluation Strategy: Reset Based on Points Earned and Account Re-evaluation Strategy of Guest Inactivity.' Account-history-attributes: type: array items: type: object properties: date: type: string description: Date/time when the event was created in the system, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time title: type: string description: Event title event_name: type: string description: Event name (Checkin, Redemption, etc.) event_value: type: string description: Event value (Visit, Point, or Item) description: type: string description: Description of reason for the event sub_value: description: Sub-value of the event type: string bar_column1: type: string description: Points details bar_column2: type: string description: Visit details bar_column3: type: string description: Item details points: type: integer description: Total number of points that were redeemed visits: type: - integer - 'null' description: Total number of visits that were redeemed rewards: type: number format: double description: Total number of rewards that were redeemed items: type: integer description: Total number of items that were redeemed pending_refresh: type: boolean description: If the event is related to check-in, whether the check-in has pending refresh or not expired: type: boolean description: Whether the event has expired or not disapproved: type: boolean description: Whether the event is disapproved or not level: type: 'null' event_details: type: object description: Details of the current event (see [this](/docs/dev-portal-mobile/a44caeddc8412-event-details-object)). store_number: type: - 'null' - string description: Store number or other external identifier set on the location event_expiry: type: string description: Expiry date for the event as configured in the Punchh platform channel: type: string description: Channel through which the event occurred (e.g., online_ordering, WiFi, POS, etc.) external_uid: type: string description: External UID received at the time of check-in membership_level: type: string description: Membership level for this event title: Account History Attributes (Object) x-stoplight: id: c64aed99d1fbd background-content: type: object properties: type: type: string description: 'The type of the background content. It can be an image or a color. ' url: type: string description: 'The URL of the image that will be used as the background ' alt_text: type: string description: 'Alternate text that appears if the app cannot render the background content of the message ' initial_frame: type: string description: The initial frame or first frame is what appears behind the play button before a user taps it to start playing the video. description: "This is the content that makes the background of the message.\n\n```\n{\n \"type\"\ : \"image\",\n \"url\": \"IMAGE_URL\",\n \"alt_text\": \"Black Background Image\",\n \ \ \"initial_frame\": \"\"\n}\n```" title: Background Content (Object) x-stoplight: id: 687af9f3ae9c4 checkin: type: object properties: created_at: type: string external_uid: type: string checkin_id: type: integer description: ID of the loyalty check-in made by the user pending_points: type: integer pending_refresh: type: boolean description: Whether check-in is pending refresh or not points_earned: type: integer description: Number of points earned in the loyalty check-in bar_code: type: string current_membership_level: type: - string - 'null' description: Membership level of the user first_checkin: type: - string - boolean description: Whether it is the first check-in at the business or not location_id: type: integer description: ID of the location associated with the loyalty check-in store_number: type: string description: The store number where the check-in occurred title: Check-in (Object) x-stoplight: id: 6048505debe09 Converted-Category-Balance: type: array items: type: object properties: category_id: type: integer description: Category ID name: type: string description: Name of the reward source_type: type: string description: Type of source used for conversion source_value: type: integer description: Threshold value at which points get converted converted_type: type: string description: This could be "currency", "fuel_discount", or "charity" depending on the Punchh platform configuration. converted_value: type: number description: Multiplier for the converted type format: float balance: type: integer description: Balance available for the user for this type of reward title: Converted Category Balances (Object) x-stoplight: id: 721549331be0c Coupons: type: array items: type: object properties: code: type: string description: Alphanumeric coupon code that a user must use to receive an offer image_url: type: string description: URL of the image of the reward that will be displayed in the app name: type: string description: Name of the coupon campaign through which the coupon was given to a user description: type: string description: Description of the offer that will be available to a user after using the coupon code x-nullable: true start_date: type: string description: Coupon start date enum: - YYYY-MM-DD format: date x-nullable: true end_date: type: string description: Coupon expiration date enum: - YYYY-MM-DD format: date title: Coupons (Object) x-stoplight: id: 784153ff94ed5 cta: type: array items: type: object properties: type: type: string description: 'Three possible values can be returned to the mobile client: - web_link: The cta button prompts the user to open the link in a web browser available on the mobile client. - deep_link: The cta button takes the user to a particular deep link specified in the app. - drill_down: The cta button opens the detailed view of the rich message received by the app.' link: type: string description: The URL to which the user will be directed, depending on the type of the cta label: type: string description: The text that appears on the cta button in the app cta_type: type: string description: 'More than one cta object can be returned to the app. The cta_type can have two possible values: primary and secondary. The primary cta is higher priority and is the main cta button. The secondary cta can be something like a terms and conditions link that can be rendered appropriately in the app.' title: CTA (Object) x-stoplight: id: 792f98f6893c2 deals: type: array title: Deals (Object) x-stoplight: id: de3191c1d2f29 items: type: object properties: applicable_as_loyalty_redemption: type: boolean description: Enables redeemables to be allowed for loyalty reward redemption as well redeemable_properties: type: string description: Properties such as "Merchandise", "Food Item", etc. can be added to a particular redeemable. discount_amount: type: integer description: Discount amount associated with a deal discount_channel: type: string description: 'Possible values are: - online_only - online orders - offline_only - POS - all - both' expire_redemption_code_with_reward_end_date: type: boolean description: Whether the redemption code expires with the expiry of the reward id: type: integer description: Unique ID of the deal in the system image: type: string description: URL of the image displayed in the app to depict the redeemable points: type: integer description: Number of points required to redeem a particular redeemable redeemable_id: type: integer description: Unique ID that identifies a redeemable in the system redemption_expiry: type: integer description: Expiry of the redemption thumb_image: type: string description: URL of the thumbnail image displayed in the app to depict the redeemable meta_data: type: string description: Metadata that can be added to a redeemable. This will be returned only if it is configured in the Punchh platform. The maximum length is 255 characters. redeemable_uuid: type: string description: UUID assigned to the redeemable name: type: string description: Name of the redeemable description: type: string description: A description of the redeemable that appears in the app. This can be used to persuade users to redeem. start_time: type: string x-stoplight: id: 2ohakgika5dxk format: date-time description: Activation date and time of the redeemable. A redeemable cannot be active before this date. hero-content: type: object description: "This is the first visual content that a user encounters when the user views a rich\ \ message. This can be an image or a video.\n\n```\n{\n \"type\": \"image\",\n \"url\":\ \ \"IMAGE_URL_GOES_HERE\",\n \"alt_text\": \"Fries\",\n \"initial_frame\": \"\"\n}\n```\n" properties: type: type: string description: 'Hero content can be an image or a video. ' url: type: string description: 'The URL of the image/video that will be used as the hero content in a rich message ' alt_text: type: string description: 'Alternate text that appears if the app cannot render the hero content of the message ' initial_frame: type: string description: The initial frame or first frame is what appears behind the play button before a user taps it to start playing the video. title: Hero Content (Object) x-stoplight: id: 9c1b89b88238d menu_items: type: array items: type: object properties: item_name: type: string description: 'Name of the menu item ' item_qty: type: integer description: Quantity ordered by the customer. If the item is a modifier (such as extra cheese on a pizza base item), make sure the quantity reflects the total number of base items included. For example, if you have a pizza base item with a certain item ID and a quantity of two, and the pizzas each have an extra cheese modifier added to them, then the modifier quantity should be two to account for the modifier across both pizzas. This applies only to base items of the same ID. If different base items include the same modifier, you do not need to sum the modifiers. item_amount: type: number description: 'The total price of the line item or the amount of the discount that you applied to an item. In case of multiple quantities, this means the sum total of all item amounts. Always represent this value as a positive number, even when the item is a discount. ' menu_item_type: type: string description: "The classification of the item. Choose from the following types based on the\ \ item:\n\nM - Menu item ( + or - ) \n\nD - Discount (negative). Either internal or Punchh\ \ will always evaluate lines as ( - ) regardless of the sign assigned in the API call\n\n\ S - Service item. Any item representing money received that is not a sale. For example,\ \ service charges, delivery fees, tips, purchase of gift cards/certificates, etc. \n\nT\ \ - Tax item. Taxes of all sorts \n\nP - Payment item. Visa, MasterCard, cash, gift card/certificate\ \ (when used to pay for the order)" menu_item_id: type: string description: Unique identifier for the item menu_family: type: string description: The family that the item belongs to. The family is the subcategory for the item. Even though the parameter is required, you can pass it in the request with a blank value. You can leave this blank if the item does not belong to a family. menu_major_group: type: string description: 'The major group that the item belongs to. The major group is the parent category for the item. Even though the parameter is required, you can pass it in the request with a blank value. You can leave this blank if the item does not belong to a major group. ' serial_number: type: string description: A serialized number that differentiates distinct menu items on a receipt. The purpose of this field is to identify which items on the receipt are base items and which items are modifiers to the base items. For example, a main menu item (such as pizza) may have serial number "1.0", and the associated modifiers (such as "extra cheese", "olives", and "jalapenos") may have serial numbers "1.1", "1.2", and "1.3" respectively. Serialization is limited to one decimal point, so you can only modify the base item. You cannot modify a modifier with 1.x.x, and so on. required: - item_name - item_qty - item_amount - menu_item_type - menu_item_id - menu_family - menu_major_group - serial_number title: Menu Items (Object) x-stoplight: id: e8647930d00a4 Messages: type: object description: 'The `messages` object is returned in response to the Messages API (see the details below). ' properties: messages: type: array description: 'The `messages` object is returned in response to the Messages API: ' items: type: object properties: background_content: $ref: '#/components/schemas/background-content' body: type: string description: 'The text content of a rich message ' cta: type: array description: 'The short for Call-To-Action is a device designed to prompt an immediate response from a user. Refer to the `cta` object for details.' items: $ref: '#/components/schemas/cta' dismissable: type: boolean description: 'This boolean value decides whether guests can dismiss a message or not. When a guest dismisses a message, it should not be rendered in the app. ' hero_content: $ref: '#/components/schemas/hero-content' launch_time: type: string description: 'Date/time, in ISO 8601 format, when the notification should be rendered by the application client. This a useful field that can enable a business to create messages that can be sent to the mobile client in advance, and they appear in the app later when the launch time comes. If a rich message is triggered from a campaign, from a notification template as a result of user action, as a result of test notification, or if the Launch Time and Take Down Time fields are left blank in a business announcement, the values for launch_time and take_down_time will be null.' message_type: type: string description: 'There are two types of rich messages returned in response: 1. user_specific: Rich messages that have a user context. These include rich messages created based on campaigns or user actions. 2. business_wide: Rich messages that are created as business announcements in the system.' rank: type: integer description: Every message should have a rank. This marks the importance of a message. There may be a case when a more important message moves down the display list in the app as new messages are delivered to the mobile client. To keep important messages at the top of the display list, they should be given a higher number just as is the case with z-index. If two messages have the same rank, the app will determine the display order based on the launch_time. style_url: type: string description: 'Link to the style sheet file for the style that will be applied to the message. The mobile client can download the style file, which can then be used to render the rich message in the app. ' subtitle: type: string description: 'A subordinate title providing additional information about the content ' tags: type: array description: 'Tags provide additional details about a message. A simple example could be the type (such as campaign, system_notification, etc.) that may help the app make decisions about the rendering of the message. ' items: type: string take_down_time: type: string description: 'Date/time, in ISO 8601 format, when the mobile client should stop rendering the rich message in the app. If a rich message is triggered from a campaign, from a notification template as a result of user action, as a result of test notification, or if the Launch Time and Take Down Time fields are left blank in a business announcement, the values for launch_time and take_down_time will be null.' title: type: string description: 'A suitable title for the rich message. A well-crafted title increases the chances that a user will view a message. ' message_id: type: integer description: 'Unique ID of the message sent to the user ' title: Messages (Object) x-stoplight: id: dae9f70f9e7f1 User-object-mobile: type: object description: The `user` object includes the details of the users who are registered on a particular business. title: Mobile User (Object) x-stoplight: id: 03594cfe397ef properties: address: type: string description: Address of the user avatar_remote_url: type: string description: URL of the user's profile image uploaded to an online file storage system. This will be used for users who signed up using email. x-nullable: true birthday: type: string description: Date of birth of the user, in YYYY-MM-DD format enum: - YYYY-MM-DD format: date-time communicable_email: type: string description: The email address used for communication with the user city: type: string description: City where the user lives created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format email: type: string description: Unique email address used to identify the user email_verified: type: boolean description: Whether the email address of the user has been verified or not facebook_signup: type: boolean description: Indicates whether the user signed up using Facebook. This parameter returns true the first time a user signs up using Facebook. For all subsequent logins, it returns a false value. favourite_locations: type: string description: List of the user's favorite locations favourite_store_numbers: type: string description: List of store numbers of the user's favorite locations fb_uid: type: string description: Facebook ID that identifies the user x-nullable: true first_name: type: string description: First name of the user gender: type: string description: Gender of the user last_name: type: string description: Last name of the user marketing_email_subscription: type: boolean description: Whether the user has subscribed to receive marketing emails or not marketing_pn_subscription: type: boolean description: Whether the user has subscribed to marketing push-notifications or not migrate_status: type: boolean description: Whether the user has a migrate status or not passcode_configured_for_giftcards: type: boolean description: Whether the user has configured a passcode for gift cards or not phone: type: integer description: Phone number of the user profile_field_answers: type: object description: Answers given by the user while filling out the user profile. referral_code: type: string description: Referral code of the user referral_path: type: string description: Referral URL of the user secondary_email: type: string description: The secondary email address of the user is configured when a user signs up with Facebook but does not share the email address. The app asks for an alternate email address, which is kept as the `secondary_email`. state: type: string description: State where the user lives superuser: type: boolean description: Whether multiple check-ins are allowed for a user. This is used mostly for testing purposes by developers. terms_and_conditions: type: boolean description: Whether the terms and conditions of a business have been accepted by a user or not title: type: string description: Salutation as selected by the user x-nullable: true updated_at: type: string description: Date/time when user was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time user_as_barcode: type: string description: Barcode that identifies the user user_as_qrcode: type: string description: QR code that identifies the user user_code: type: string description: A unique ID that identifies the user. This smaller code can be converted to a QR code in the app and scanned at some POS systems that do not support longer codes. Alternatively, a user could give this to the POS operator if the POS does not have a scanner. user_id: type: integer description: ID that identifies the user user_relations: $ref: '#/components/schemas/user-relations' zip_code: type: string description: Zip code where the user lives anniversary: type: string description: Anniversary date of the user, in YYYY-MM-DD format verification_mode: description: Mode of verification (available only for a user in awaiting migration state) x-nullable: true apple_signup: type: boolean description: Whether the user has an Apple sign-up or not. This will return true for the first time sign-up. apple_uid: type: string description: Unique ID generated by Apple has_generated_fb_email: type: boolean description: Whether the user has generated a Facebook email or not sms_subscription: type: boolean description: Whether the user has subscribed to SMS services or not age_verified_status: type: boolean x-stoplight: id: y7uqfq1lsr35c description: 'Whether or not the user has undergone age verification by Koupon Media. Possible values: true, false. The value is set to true if the user''s age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs 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. ' Notifications: type: array description: Returns the details of the notifications received by a user. A maximum of 10 notifications will be fetched. items: type: object properties: id: type: integer description: ID of the notification kind: type: string description: 'Type of notification. There are three types of notifications that a user can receive: ''system'', ''campaign'', and ''news''.' message: type: string description: Message sent to the user in the notification read_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time x-nullable: true created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time title: Notifications (Object) x-stoplight: id: ba4734ac30a93 profile_field_answers: type: object description: Answers given by the user while filling in the user profile. The user submits answers to profile field questions that are configured in the Punchh platform. A total of 25 answers can be submitted. The keys range from 'upf0' to 'upf24'. If questions have multiple answers, the values should be separated by a | character (pipe). title: Profile Field Answers (Object) properties: upf0: type: string description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform. upf1: type: string description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform. upf2: type: string description: Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform. x-stoplight: id: 232889e28c1c8 Redeemables-Attributes: type: array items: type: object properties: applicable_as_loyalty_redemption: type: boolean description: Applicable on loyalty redeemable_properties: type: string description: Comma-separated values that provide additional details about a redeemable. For example, a redeemable could be "Food Item" or "Merchandise", etc. These can be configured for a business in the Punchh platform and attached to a redeemable. If no value is attached to a redeemable, a blank field will be returned. discount_amount: type: integer description: Amount of discount on the reward discount_channel: type: string description: 'Can accept any one of the following values: - all - discountable everywhere - online_only - online orders only - offline_only - in store only' expire_redemption_code_with_reward_end_date: type: - boolean - 'null' description: Whether the redemption code expires with the expiry of the reward id: type: integer description: Identification of the reward image: type: string description: Image of the redeemable item points: type: integer description: Total number of points required for redemption redeemable_id: type: integer description: Identification of the redeemable item redemption_expiry: type: integer description: Expiry of the redemption, in minutes thumb_image: type: string description: Thumbnail image of the redeemable item name: type: string description: Name of the redeemable item description: type: string description: Description of the redeemable item title: Redeemables Attributes (Object) x-stoplight: id: 173597e963ebd Rewards-Attribute: type: array items: type: object properties: business_id: type: integer description: Identification of the business end_date: type: string description: Date after which the reward will not be allowed on redemption, in YYYY-MM-DD format enum: - YYYY-MM-DD format: date end_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Timestamp with time zone gaming_level_id: type: string description: Gaming level that the user has reached gifted_for_type: type: string description: 'The reward can be gifted for the following types: - Admin reward - Offered by the administrator to a user - Campaign - Offered to a user under a campaign triggered by a business - Checkin - When a user makes a check-in - FeedbackReply - Feedback provided by a user - MassGifting - If a user is among the population of users that received rewards - Referral - Referral of one user by another user - ScratchPlay - Mobile game' gift_reason: type: string description: Reward given for activity performed by a user id: type: integer description: ID of reward format: int64 location_ids: type: array description: Location IDs are interchangeable with external store numbers. items: type: integer read_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Time when the user acknowledged the reward redeemable_id: type: integer description: ID of the redeemable item reward_properties: description: Properties of the reward x-nullable: true start_date: type: string enum: - YYYY-MM-DD format: date description: Date from which the reward is applicable, in YYYY-MM-DD format start_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Tmestamp with time zone external_store_numbers: type: array description: External store numbers are interchangeable with location IDs. items: type: integer type: type: string description: This will be either redeemable or reward. The Create Online Redemption API request depends on what is returned in this field. title: Rewards Attributes (Object) x-stoplight: id: b56f79b98e3cd user-object: type: object title: User (Object) x-stoplight: id: 3b4442b722f1f properties: address_line1: type: string description: 'Address information (part 1) of the user ' anniversary: type: string enum: - YYYY-MM-DD format: date description: Anniversary of the user in YYYY-MM-DD format. This field gets updated in the database only if the user did not set it at time of sign-up. avatar_remote_url: type: string description: Avatar URL of the user profile image birthday: type: string enum: - YYYY-MM-DD format: date description: Birthday of the user, in YYYY-MM-DD format. This field gets updated in the database only if the user did not set it at time of sign-up. city: type: string description: 'City where the user lives ' created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user was created in the system, in ISO 8601 format email: type: string description: Email address of the user email_verified: type: boolean description: Whether the email address is verified or not fb_uid: type: integer description: Unique Facebook ID of the user first_name: type: string description: First name of the user gender: type: string description: Gender of the user id: type: integer description: Unique ID of the user last_name: type: string description: Last name of the user state: type: string description: State where the user lives updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user was updated in the system, in ISO 8601 format zip_code: type: string description: Zip code of the user allow_multiple: type: boolean description: Whether multiple check-ins are allowed for the user or not 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). favourite_locations: type: string description: List of the user's favorite locations favourite_store_numbers: type: string description: List of store numbers of the user's favorite locations marketing_email_subscription: type: boolean description: Whether the user has subscribed to receive marketing emails or not marketing_pn_subscription: type: boolean description: Whether the user has subscribed to receive marketing push notifications or not passcode_configured: type: boolean description: Whether the passcode has been configured or not profile_field_answers: $ref: '#/components/schemas/profile_field_answers' referral_code: type: string description: The user's referral code. The user can share this referral code to refer others 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. referral_path: type: string description: URL that points to the referred path secondary_email: type: string description: Secondary email address of the user terms_and_conditions: type: boolean description: Whether the user has agreed to the terms and conditions to use the app as per the configuration title: type: string description: Title used for the user (e.g., Mr., Mrs., etc.) user_as_barcode: type: integer description: Unique user ID in barcode format user_as_qrcode: type: string description: Unique user ID in QR code format user_code: type: string user_id: type: integer description: Unique user ID user_relations: $ref: '#/components/schemas/user-relations' wants_menu_notifications: type: boolean description: Whether the user wants to receive menu notifications or not work_zip_code: description: 'Zip code of the user''s office ' x-nullable: true mindbody_client_id: x-nullable: true preferred_locale: type: string description: Preferred locale of the user phone: type: string description: Phone number of the user migrate_status: type: boolean description: Whether the user has been migrated or not email_unsubscribe: type: string description: Unsubscribed email address of the user allow_push_notifications: type: boolean description: Whether the user has allowed push notifications or not facebook_signup: type: boolean description: Indicates whether the user signed up using Facebook. This parameter returns true the first time a user signs up using Facebook. For all subsequent logins, it returns a false value. communicable_email: type: string description: Email address where emails should be sent access_token: type: string description: Security token that identifies the user x-nullable: true expiration_date: type: string enum: - YYYY-MM-DD format: date description: This value will be returned only if "Account re-evaluation strategy" is set to Guest Inactivity. All other cases return a NULL value. x-nullable: true user_joined_at: type: string x-stoplight: id: sl1218jvmndoj description: Sign-up anniversary date of the user, in YYYY-MM-DDThh:mm:ssZ format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time sms_subscription: type: boolean description: Whether the user has subscribed to SMS services or not age_verified_status: type: boolean x-stoplight: id: mynywehbcs39p description: 'Whether or not the user has undergone age verification by Koupon Media. Possible Values: true, false. The value is set to true if the user''s age is verified by Koupon Media; otherwise, it is set to false. The response returns this parameter in sign-in, sign-up, and user update APIs 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 user-input-object: type: object title: User Input (Object) x-examples: application/json: address_line1: ADDRESS_GOES_HERE anniversary: null avatar_remote_url: URL_GOES_HERE birthday: '1993-01-01' city: Columbus email: test@example.com first_name: FIRST_NAME_GOES_HERE age_verified: true privacy_policy: true gender: female last_name: LAST_NAME_GOES_HERE state: Ohio zip_code: '43016' allow_multiple: true favourite_locations: '' marketing_email_subscription: true marketing_pn_subscription: true profile_field_answers: upf0: Coffee|Tea|Lemonade upf1: Pasta|Pizza|Hamburger upf2: Movies|Music|Sports secondary_email: test@example.com terms_and_conditions: true title: '' user_relations: - relation: spouse name: SPOUSE_NAME_GOES_HERE birthday: '1999-01-01' work_zip_code: '' preferred_locale: '' phone: '1111111111' unsubscribed: true allow_push_notifications: true apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE external_source: customer_id external_source_id: '11111111111111111111' x-stoplight: id: 2f9bb36917e65 properties: address_line1: type: string description: Address information (part 1) of the user anniversary: type: string description: Anniversary of the user, in YYYY-MM-DD format. This field gets updated in the database only if the user did not set it at time of sign-up. avatar_remote_url: type: string description: Avatar URL of the user profile image birthday: type: string description: Birthday of the user, in YYYY-MM-DD format. This field gets updated in the database only if the user did not set it initially during sign-up. Due to fraud protections, guests are permitted to update their birthdays only once. Subsequent attempts to modify the birthday parameter using the API will fail. In such a case, the API returns a 200 response, but the birthday is not updated. enum: - YYYY-MM-DD city: type: string description: 'City where the user lives ' email: type: string description: Email address of the user first_name: type: string description: First name of the user age_verified: type: boolean description: Whether age is verified or not privacy_policy: type: boolean gender: type: string description: Gender of the user. Valid values are "male", "female", or "declined". last_name: type: string description: Last name of the user state: type: string description: State where the user lives zip_code: type: string description: Zip code where the user lives allow_multiple: type: boolean description: Whether multiple check-ins are allowed for the user or not favourite_locations: type: string description: Favorite locations of the user (comma-separated for multiple locations) 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 profile_field_answers: $ref: '#/components/schemas/profile_field_answers' secondary_email: type: string description: Secondary email address of the user terms_and_conditions: type: boolean description: Whether the user has agreed to the terms and conditions to use the app as per the configuration title: type: string description: Title of the user. Possible values are Mr., Mrs., Miss, Ms., and Dr. user_relations: $ref: '#/components/schemas/user-relations' work_zip_code: type: string description: Zip code of the user's office preferred_locale: type: string description: Preferred locale of the user phone: type: string description: Phone number of the user unsubscribed: type: boolean description: Whether the user has unsubscribed from marketing email notifications allow_push_notifications: type: boolean description: Whether the user has allowed push notifications or not apn_token: type: string description: Apple Push Notification (APN) token gcm_token: type: string description: Google Cloud Messaging (GCM) or FCM token external_source: type: string 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. This is a required parameter if you want to update the access token for an external IDP user. 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). This is a required parameter if you want to update the access token for an external IDP user. age_verified_status: type: boolean x-stoplight: id: fnmox22klesc2 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. ' user-relation-attribute: type: object title: User Relation Attributes (Object) x-stoplight: id: 1d89eb837fe7f description: The object contains information about the relationship details of a user, for example, spouse and kid information. If the user account does not have relationship details, the API returns an empty object in the response. properties: relation: type: string description: Relation to the user. Valid values are "spouse" and "kid". name: type: string description: Name of the relative birthday: type: string enum: - YYYY-MM-DD format: date description: Birthday of the relative created_at: type: string description: Date/time when the user’s relationship details were added to the Punchh system, in ISO 8601 format format: date-time examples: - '2023-08-18T12:32:13Z' updated_at: type: string format: date-time description: Date/time when the user’s relationship details were updated in the Punchh system, in ISO 8601 format examples: - '2023-08-18T12:32:13Z' user-relations: title: User Relations (Array Object) x-stoplight: id: ut0ic50qnqmhq type: array items: x-stoplight: id: s8m992rimfngd type: object properties: id: type: integer x-stoplight: id: hwhbkrukhoown description: Unique ID of the relationship name: type: string x-stoplight: id: 2fmpih7siw5sc description: Name of the relative relation: type: string x-stoplight: id: 7hqerbd50q2gx description: Relation to the user. Valid values are "spouse" and "kid". birthday: type: string x-stoplight: id: knsdt60v0v4ef format: date enum: - YYYY-MM-DD description: Birthday of the relative description: The object contains information about the relationship details of a user, for example, spouse and kid information. If the user account does not have relationship details, the API returns an empty user_relations object in the response. parameters: Signature: schema: type: string default: SIGNATURE_GOES_HERE in: header name: x-pch-digest description: The [signature](/docs/dev-portal-online-ordering/additional-topics/x-pch-digest-sha-1) for the API call required: true content type: schema: type: string default: application/json in: header name: Content-Type description: Set this header to **application/json**. required: true Accept: schema: type: string default: application/json in: header name: Accept description: Advertises which content types the client is able to understand required: true accept language: schema: type: string default: en in: header name: Accept-Language description: Set to the language you are using. Authentication Token: schema: type: string default: AUTHENTICATION_TOKEN_GOES_HERE in: query name: authentication_token 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: schema: type: string default: CLIENT_GOES_HERE in: query name: client description: Client key of the business User-Agent: schema: type: string default: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type name: User-Agent in: header required: true description: For details, see [User Agent](/docs/dev-portal-online-ordering/additional-topics/user-agent). Authorization: schema: type: string default: Bearer ACCESS_TOKEN_GOES_HERE name: Authorization in: header required: true description: 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`. x-ext-urls: {}