info: title: Mobile API version: '1.0' contact: name: Punchh Dev Support url: https://developers.punchh.com description: 'Punchh provides a robust platform for offering loyalty programs to customers. When a business integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty programs for enrolled customers, primarily via business-branded mobile apps and websites tailored by Punchh. To establish integration with the Punchh APIs, you need to understand how they are invoked and what responses are returned by the Punchh server. You can call APIs using any suitable API test client, such as Postman. Thus, the response to every API call made in Postman under a chosen environment (in app and/or platform) is reflected in the app and/or platform.' paths: /api2/mobile/users/login: post: parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' responses: '200': description: '' content: application/json: schema: type: object properties: access_token: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' 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: '' anniversary: '2013-02-16' avatar_remote_url: null birthday: '1999-01-01' city: '' communicable_email: test@example.com created_at: '2019-01-11T09:08:25Z' email: test@example.com email_verified: false facebook_signup: null apple_signup: null apple_uid: null favourite_location_ids: 306082,333070,304374 favourite_store_numbers: 12345,0604,1234 fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: '' has_generated_fb_email: false last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: test1: Option 1 referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: '' state: '' superuser: false terms_and_conditions: true title: '' updated_at: '2020-04-29T04:18:24Z' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 preferred_locale: en user_relations: [] zip_code: null verification_mode: null sms_subscription: false apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE user_joined_at: '2019-01-11T09:08:25Z' '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: Bad Request (blank email field): value: "{\n \"errors\": {\n \"missing_required_param\": [\n \"Required parameter\ \ missing or the value is empty: email\"\n ]\n }\n}" Bad Request (invalid language): value: "{ \n \"errors\":{ \n \"invalid_language\":[ \n \"Unknown/Invalid\ \ locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n\ \ ]\n }\n}" Bad Request (missing parameter): value: "{ \n \"errors\":{ \n \"missing_required_param\":[ \n \"Required\ \ parameter missing or the value is empty: client\"\n ]\n }\n}" '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '412': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: application/json; charset=utf-8: value: errors: invalid_signature: - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_email_password: type: array items: type: string examples: default: value: errors: invalid_email_password: - Sorry, Invalid Email/Password. summary: Sign in description: 'Logs a user into the app of a business and returns the user''s information in the response ' operationId: mobile_signin tags: - Users x-stoplight: id: c1be403d96bc5 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: email: type: string description: Email address of the user password: type: string description: Password of the user apn_token: type: string description: Apple push-notification token that allows push notifications to be received on the registered device of the user gcm_token: type: string description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user required: - client examples: default: value: client: CLIENT_GOES_HERE user: email: test@example.com password: PASSWORD_GOES_HERE /api2/mobile/single_scan_tokens: post: parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Authorization' summary: Generate Single Scan Code or Short Code description: "This API facilitates the single-scan flow functionality, allowing a user to generate\ \ a single-scan code from the mobile app for making a payment, redeeming a discount, adding a\ \ tip, or any combination of these in a single transaction at the POS. The API returns a single\ \ scan code containing a UUID string in the response. \n\nFor more information, see [Single Scan\ \ Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow).\n\n**Note**: This mobile API endpoint\ \ (`POST {server-name}/api2/mobile/single_scan_tokens`) is the same as the mobile API endpoint\ \ used to [generate a one-time passcode (OTP) for use with Redemptions 2.0](/docs/dev-portal-mobile/apis/mobile-redemptions-2-0-new-api/post/api2/mobile/single_scan_tokens).\ \ When using this API with Redemptions 2.0, the following offers parameters must NOT be included\ \ with the request body:\n- `reward_id`\n- `redeemable_id`\n- `banked_reward_amount`\n- `coupon`\n\ - `redeemable_card_count`\n- `subscription_id`\n\n### Loyalty Short Code Flow\n\nThis API also\ \ supports the loyalty short code flow for drive-thru identification and payment. The loyalty\ \ identification at drive-thru, single scan flow and drive-thru payment using short code payment\ \ (using SSF) must be enabled for the business to allow payments using the short code.\n\nThe\ \ API accepts two additional parameters in the request body: a boolean parameter, `short_code`,\ \ and `location_id` to generate a short code. \n\nWhen the `short_code` parameter is set to `true`,\ \ the API generates a short alphanumeric code along with a single scan code. The single scan code\ \ is not returned in the API response for the loyalty short code flow. It is stored in the Punchh\ \ backend and associated with the short code.\n\nUsers can share the short code verbally at the\ \ drive-thru window for faster account look-up at the POS. \n\nIn addition to the short code,\ \ the API response also includes the `location_id` for which the short code is generated, `expiring_at`,\ \ which indicates when the short code expires, and `new_short_code_generated`, which indicates\ \ whether a new short code has been generated.\n\nWhen `short_code` is set to false, the API follows\ \ the legacy single scan token flow and returns only a single scan code for transactions.\n\n\ Contact your Punchh representative to update these Punchh platform configuration.\n\nWhen the\ \ POS calls the [User Look-up API](https://developers.partech.com/docs/dev-portal-pos/apis/pos-api/tag/point-of-sale/get/api/pos/users/search)\ \ with the short code, Punchh retrieves the single scan code associated with the short code to\ \ look up the user, the rewards, and the payment selected by the user when generating the short\ \ code. The User Look-up API includes the `single_scan_code` in the response, which the POS can\ \ use for further actions such as check-in, redemptions, and payments.\n\n**Configuration Resolution\ \ Logic**\n\nSingle scan code generation follows this configuration priority:\n1. Location-level\ \ single scan flow configuration.\n2. If not configured at location level, the business-level\ \ single scan flow configuration is evaluated.\n\n**When `short_code` = `true`:**\n- The system\ \ checks whether the short code and single scan flow are enabled for the location.\n- If not configured\ \ at the location level, the business-level configuration is evaluated.\n- If neither the location\ \ nor the business has the required short code and single scan flow configurations enabled, the\ \ API returns a 422 feature-disabled error. If the `location_id` value is invalid or missing in\ \ the request, the API returns a missing location ID error.\n\n**When `short_code` = `false`:**\n\ - The legacy single scan code flow is triggered and a `single_scan_code` is returned.\n- The token\ \ type is selected based on the location-level configuration (if present), otherwise business-level\ \ configuration is used." operationId: mobile_gen_ssc tags: - Single Scan Code responses: '200': description: OK content: application/json: schema: type: object properties: single_scan_code: type: string description: Single scan code of the user to be used in the single scan flow at the POS expires_in: type: string format: date-time description: Date/time when the single scan code expires and can no longer be used at the POS, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. created_at: type: string format: date-time description: Date/time when the single scan code was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. short_code: type: string description: Short alphanumeric code for drive-thru identification. Returned when the `short_code` request parameter is set to true. location_id: type: number description: ID of the location for which the short code is requested. Returned when the `short_code` request parameter is set to true. new_short_code_generated: type: boolean description: Indicates whether a new short code is generated for the single scan code. Returned when the `short_code` request parameter is true. When `new_short_code_generated` is true, a new short code is generated and assigned to the single scan code; when false, a previously active short code is reassigned to a new single scan code. Note that, in the loyalty short code flow, the single scan code is not returned in the API response. expiring_at: type: string format: date-time description: Date/time when the short code expires and can no longer be used at the drive-thru, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This parameter is returned when the `short_code` request parameter is set to true. examples: Response Example: value: single_scan_code: SINGLE_SCAN_CODE_GOES_HERE expires_in: '2022-06-08T10:19:52Z' created_at: '2022-06-08T10:14:52Z' Short Code Response: value: short_code: JII8 location_id: 12345 expiring_at: '2026-02-13T11:44:11+05:30' new_short_code_generated: true '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: 'Response Example: Bad Request (blank client field)': value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: 'Response Example: Unauthorized Request (Incorrect client value)': value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us Unauthorized (invalid or missing access token): value: errors: unauthorized: - An active access token must be used to query information about the current user. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Response Example (invalid payment_type value): value: errors: Invalid Payment Type Short code feature disabled for location: value: errors: This feature is currently turned off for this location. Please reach out to the Punchh Support team for more information. Missing location_id for short code: value: errors: While requesting for short code, Location Id is mandatory. x-stoplight: id: 1b70514f6ead9 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business payment_type: type: string description: Payment type selected by the user when generating the single scan code. Valid values are `GiftCard`, `CreditCard`, or `recurring`. The payment type is recurring when the user selects a saved payment card from the mobile application for payments. gift_card_uuid: type: string description: The user's gift card number. Required if the payment type is gift card. transaction_token: type: string description: Unique digital identifier/token of the user's credit card, or UUID of the saved payment card if the payment type is recurring. Required if the payment type is credit card or recurring. reward_id: type: string description: Unique ID of a reward, or a comma-separated list of reward IDs if multiple rewards are selected by the user for redemption redeemable_id: type: string description: Unique ID of a redeemable, or a comma-separated list of redeemable IDs if multiple redeemables are selected by the user for redemption subscription_id: type: string x-stoplight: id: jz57t3l1413j4 description: Unique ID of a subscription, or a comma-separated list of subscription IDs if multiple subscriptions are selected by the user for redemption banked_reward_amount: type: string description: Amount of banked currency selected by the user for redemption coupon: type: string description: User-specific dynamically generated unique coupon codes that the POS system automatically applies in a single scan, or a comma-separated list of unique coupons if multiple coupons are selected by the user for redemption redeemable_card_count: type: string description: Number of redeemable cards selected by the user for redemption tip: type: string description: Amount that the user selected as a tip short_code: type: boolean description: Indicates whether short code flow should be used. When set to `true`, the API follows the short code flow and returns a short code for drive-thru identification and payment. When set to `false`, the API follows the legacy single scan token generation flow and returns only a single scan code for transactions. Contact your Punchh representative to update this Punchh platform configuration. location_id: type: number description: ID of the location for which the short code is requested. Required when `short_code` is `true` for short code and single scan code generation. required: - client examples: Credit Card: value: client: CLIENT_GOES_HERE payment_type: CreditCard transaction_token: TRANSACTION_TOKEN_GOES_HERE redeemable_id: REDEEMABLE_ID_GOES_HERE reward_id: REWARD_ID_GOES_HERE subscription_id: SUBSCRIPTION_ID_GOES_HERE coupon: COUPON_CODE_GOES_HERE tip: '1' Gift Card: value: client: CLIENT_GOES_HERE payment_type: GiftCard gift_card_uuid: GIFT_CARD_UUID_GOES_HERE reward_id: REWARD_ID_GOES_HERE coupon: COUPON_CODE_GOES_HERE redeemable_card_count: '2' tip: '1' Recurring: value: client: CLIENT_GOES_HERE payment_type: recurring transaction_token: SAVED_CARD_UUID_GOES_HERE reward_id: REWARD_ID_GOES_HERE Short Code (Drive-Thru): value: client: CLIENT_GOES_HERE payment_type: GiftCard gift_card_uuid: GIFT_CARD_UUID_GOES_HERE reward_id: REWARD_ID_GOES_HERE short_code: true location_id: 12345 parameters: [] /api2/mobile/payment_cards: post: parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' summary: Create a Payment Card description: Creates and saves a payment card for a user. This API is triggered when the user saves the payment card on the mobile application. operationId: create_api2-mobile-payment_cards tags: - Payment Cards responses: '200': description: Payment Card Added content: application/json: schema: type: object properties: uuid: type: string description: Saved payment card UUID nickname: type: string description: Saved payment card nickname, as set by the user preferred: type: boolean description: This value determines whether this saved payment card will be selected as the default card or not when the user makes a payment through the mobile application. If the value is set to true, this card will be selected as the default card for payments. Valid values are true or false. card_details: type: object description: User's saved payment card details properties: name_on_card: type: string description: Cardholder name card_type: type: string description: Saved payment card type (e.g., Visa, Mastercard, Amex, etc.) cc_4: type: string description: Last 4 digits of the saved payment card expiry_month: type: string description: Expiration month of the saved payment card expiry_year: type: string description: Expiration year of the saved payment card examples: default: value: uuid: nickname: preferred: true card_details: name_on_card: cc_4: '4242' card_type: Visa expiry_month: '02' expiry_year: '28' '400': description: Bad Request (missing or blank required parameter) content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: Bad Request (missing or blank required parameter): value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized Request (incorrect client value) content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Unauthorized Request (incorrect client value): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Payment gateway error: value: errors: Invalid Customer Key transaction_token not valid: value: errors: Invalid Payment token User not authenticated: value: errors: Unauthenticated User Invalid zip code: value: errors: Invalid Zip Code value Missing zip code: value: errors: Zip Code required for this card type (Amex) Invalid country: value: errors: Invalid country error Payment adapter not supported: value: errors: This payment adapter is currently not supported or you might have passed the incorrect payment adapter. x-stoplight: id: 86d781cf0d5d7 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business transaction_token: type: string description: Unique digital identifier/token of the user's payment card provided by the payment processor adapter_code: type: string description: Name of the payment processor / payment gateway. Valid value is par_payment. preferred: type: boolean description: This value determines whether this card will be selected as the default card or not when the user makes a payment through the mobile application. If the value is set to true, this card will be selected as the default card for payments. Valid values are true or false. nickname: type: string description: Payment card nickname, as set by the user billing_info: type: object description: Billing information of the cardholder properties: name: type: string description: Cardholder name. country: type: string description: Country as specified by the cardholder in the billing address. Valid values are USA and CAN. zip_code: type: string description: Zip code as specified by the cardholder in the billing address. Required when the card to be added is of type Amex. required: - client - transaction_token - adapter_code examples: default: value: client: transaction_token: adapter_code: preferred: true nickname: NICKNAME_GOES_HERE billing_info: name: CUSTOMER_NAME_GOES_HERE country: USA zip_code: ZIP_CODE_GOES_HERE parameters: [] get: summary: Fetch All Saved Payment Cards operationId: get-api2-mobile-payment_cards responses: '200': description: OK headers: {} content: application/json: schema: type: array description: Array of payment cards in the user’s account, if available items: type: object properties: uuid: type: string description: Saved payment card UUID nickname: type: string description: Saved payment card nickname, as set by the user card_details: type: object description: User's saved payment card details properties: name_on_card: type: string description: Cardholder name card_type: type: string description: Saved payment card type (e.g., Visa, Mastercard, Amex, etc.) cc_4: type: string description: Last 4 digits of the saved payment card ' expiry_month': type: string description: Expiration month of the saved payment card ' expiry_year': type: string description: Expiration year of the saved payment card preferred: type: boolean description: This value determines whether this saved payment card will be selected as the default card or not when the user makes a payment through the mobile application. If the value is set to true, this card will be selected as the default card for payments. Valid values are true or false. examples: default: value: - uuid: nickname: card_details: name_on_card: cc_4: '4242' card_type: Visa expiry_month: '02' expiry_year: '28' preferred: true - uuid: nickname: card_details: name_on_card: cc_4: '1111' card_type: Visa expiry_month: '06' expiry_year: '29' preferred: true '400': description: Bad Request (missing or blank required parameter) content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: Bad Request (missing or blank required parameter): value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized Request (incorrect client value) content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Unauthorized Request (Incorrect client value): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Invalid passcode: value: errors: Invalid Passcode Payment gateway error: value: errors: Invalid Customer Key User not authenticated: value: errors: Unauthenticated User description: Enables a user to fetch all saved payment cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' tags: - Payment Cards x-stoplight: id: 7e449f57a8e52 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business adapter_code: type: string description: Name of the payment processor / payment gateway. Valid value is par_payment. passcode: type: string description: Passcode is a secondary authentication PIN that must be passed if it is enabled for a business. The passcode can be enabled or disabled from the Punchh platform. required: - client - adapter_code examples: default: value: client: adapter_code: passcode: description: '' /api2/mobile/payment_cards/{payment_card_uuid}: parameters: - schema: type: string name: payment_card_uuid in: path required: true description: Unique ID of the saved payment card that Punchh generates when creating/saving this card in the system. See [Create a Payment Card](/docs/dev-portal-mobile/apis/mobile-api/tag/payment-cards/post/api2/mobile/payment_cards) put: summary: Update a Saved Payment Card operationId: put-api2-mobile-payment_cards responses: '200': description: Payment Card Updated content: application/json: schema: type: object properties: uuid: type: string description: Saved payment card UUID nickname: type: string description: Saved payment card nickname, as set by the user card_details: type: object description: User's saved payment card details properties: name_on_card: type: string description: Cardholder name card_type: type: string description: Saved payment card type (e.g., Visa, Mastercard, Amex, etc.) cc_4: type: string description: Last 4 digits of the saved payment card expiry_month: type: string description: Expiration month of the saved payment card expiry_year: type: string description: Expiration year of the saved payment card preferred: type: boolean description: This value determines whether this saved payment card will be selected as the default card or not when the user makes a payment through the mobile application. If the value is set to true, this card will be selected as the default card for payments. Valid values are true or false. examples: 'application/json:': value: uuid: nickname: card_details: name_on_card: cc_4: '4242' card_type: Visa expiry_month: '02' expiry_year: '28' preferred: true '400': description: Bad Request (missing or blank required parameter) content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: Bad Request (missing or blank required parameter): value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized Request (incorrect client value) content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Unauthorized Request (Incorrect client value): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Payment gateway error: value: errors: Invalid Customer Key User not authenticated: value: errors: Unauthenticated User tags: - Payment Cards description: Enables a user to update the nickname and preferred status of a saved payment card parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' x-stoplight: id: 308acea94fbc8 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business nickname: type: string description: Saved payment card nickname as set by the user preferred: type: boolean description: This value determines whether this card will be selected as the default card or not when the user makes a payment through the mobile application. If the value is set to true, this card will be selected as the default card for payments. Valid values are true or false. required: - client examples: default: value: client: nickname: preferred: true delete: summary: Delete a Saved Payment Card operationId: delete-api2-mobile-payment_cards responses: '200': description: Payment Card Deleted content: application/json: schema: type: object properties: message: type: string description: Success or failure message for removing the payment card from the mobile application as returned in the response status: type: string description: Status of the payment card deletion operation. Valid values are success or failure. examples: 'application/json:': value: message: Payment card has been deleted successfully. status: success '400': description: Bad Request (missing or blank required parameter) content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: Bad Request (missing or blank required parameter): value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized Request (incorrect client value) content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Unauthorized Request (Incorrect client value): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Payment card not found: value: errors: Payment card not found. Invalid passcode: value: errors: Invalid Passcode Payment gateway error: value: errors: Invalid Customer Key User not authenticated: value: errors: Unauthenticated User description: Enables a user to delete a selected payment card from the mobile application parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' tags: - Payment Cards x-stoplight: id: 148b28fc3bbfe requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business passcode: type: string description: Passcode is a secondary authentication PIN that must be passed if it is enabled for a business. The passcode can be enabled or disabled from the Punchh platform. required: - client examples: 'application/json:': value: client: passcode: /api2/mobile/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: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null refresh_token: REFRESH_TOKEN_GOES_HERE scopes: - wifi user: address: ADDRESS_GOES_HERE avatar_remote_url: null birthday: '1999-01-01' communicable_email: test@example.com city: Mountain View created_at: '2016-03-16T11:40:07+00:00' email: test@example.com email_verified: false facebook_signup: true favourite_location_ids: '304155' favourite_store_numbers: '1023' fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE gender: male last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com state: California superuser: false terms_and_conditions: false title: null updated_at: '2016-03-16T11:40:08+00:00' user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 user_relations: [] zip_code: '30201' anniversary: '2013-07-13' verification_mode: null apple_signup: null apple_uid: null has_generated_fb_email: false sms_subscription: true apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE age_verified_status: true user_joined_at: '2016-03-16T11:40:07+00:00' '412': description: '' content: application/json: schema: type: object properties: message: type: string code: type: integer examples: default: value: message: Sending invalid Signature code: 412 '422': description: '' content: application/json: schema: type: object properties: message: type: string code: type: integer examples: default: value: message: Sending invalid Entity code: 422 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. ' tags: - Users operationId: mobile_connect_with_facebook parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: a6f1c0055e695 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: facebook_access_token: type: string description: Access token received from Facebook apn_token: type: string description: Apple push-notification token that allows push notifications to be received on the registered device of the user gcm_token: type: string description: Google Cloud Manager (GCM) token that allows push notifications to be received on the registered device of the user signup_channel: type: string description: Sign-up channel for user registration. Possible values are `WebFacebook` or `MobileFacebook`. age_verified_status: type: boolean x-stoplight: id: zuuvbxdbfmpyx 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: - facebook_access_token required: - client examples: default: value: client: CLIENT_GOES_HERE user: facebook_access_token: ACCESS_TOKEN_GOES_HERE apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE signup_channel: MobileFacebook age_verified_status: true description: '' /api2/mobile/apple_registrations: 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: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' 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: '2019-09-05T03:39:10-07:00' email: test@example.com email_verified: false facebook_signup: null apple_signup: null apple_uid: APPLE_UID_GOES_HERE favourite_location_ids: '315783' favourite_store_numbers: '' fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE gender: Male has_generated_fb_email: false last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true 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: '2019-09-17T04:35:56-07:00' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 preferred_locale: en user_relations: [] zip_code: null verification_mode: null sms_subscription: false apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE age_verified_status: true user_joined_at: '2019-09-05T03:39:10-07:00' summary: Log in With Apple description: 'A user can sign in with Apple using a random email ID generated by Apple. ## Session Behavior After Users Revoke App Access From their Apple ID When a user authenticates using Apple Sign-In, Punchh generates its own access token that is independent of Apple''s authorization. If the user later revokes the app''s access through their Apple ID settings (Settings > Apple ID > Password & Security > Apps Using Apple ID), the active Punchh session is not affected, and the user is not automatically logged out. This behavior occurs because Apple Sign-In is used only during the initial authentication process. Apple does not provide a callback or notification to Punchh when a user revokes access to the app. As a result, the user remains signed in until their Punchh session expires or they explicitly log out of the app. If the user logs out and subsequently attempts to sign in again using Apple Sign-In, Apple will prompt the user to reauthorize the app to use the their Apple ID for authentication before the sign-in process can be completed. ' operationId: mobile_login_with_apple tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: a39b0ccb639cb requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 8etz5eob70kcd description: OAuth client ID provided by the business user: type: object properties: first_name: type: string description: First name of the user last_name: type: string description: Last name of the user gender: type: string description: Gender of the user external_source: type: string description: External source name (e.g., "Apple", "Salesforce", or whatever the name of the user account source is) external_source_id: type: string description: ID of the customer in the mentioned external source name (provided in the `external_source` request parameter) 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: ms49bv8zek773 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_KEY_GOES_HERE user: first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE gender: Male external_source: SOURCE_GOES_HERE external_source_id: SOURCE_ID_GOES_HERE authorization_code: AUTHORIZATION_CODE_GOES_HERE age_verified_status: true description: '' /api2/mobile/users/logout: delete: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: default: value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required.' '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: access_token: type: string examples: default: value: errors: access_token: Invalid access_token or cannot be blank summary: Log out description: Logs a user out of the app of a business, ending the current user session operationId: mobile_logout tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: 2bcfa21492491 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Token issued to the user after logging into the app of the business gcm_token: type: string description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user required: - client examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE /api2/mobile/users/profile: get: responses: '200': description: '' content: application/json: schema: type: object properties: access_token: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null user: address: ADDRESS_GOES_HERE avatar_remote_url: null birthday: '1999-01-01' communicable_email: test@example.com city: Mountain View created_at: '2016-03-16T11:40:07+00:00' email: test@example.com email_verified: false facebook_signup: null favourite_location_ids: '304155' favourite_store_numbers: '1023' fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: male last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: favorite_sports: Football favourite: Arizona Cardinals favs: Air Force fava: Academy favb: Atlanta Hawks favd: Arizona Diamondbacks fave: England - Arsenal favf: Anaheim Ducks referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com state: California superuser: false terms_and_conditions: false title: null updated_at: '2016-03-21T08:02:44+00:00' user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 user_relations: - id: 111111111 relation: spouse name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE birthday: '1999-01-01' created_at: '2016-03-18T12:32:13+00:00' updated_at: '2016-03-18T12:32:13+00:00' zip_code: '30201' anniversary: '2013-07-13' verification_mode: null apple_signup: null apple_uid: null has_generated_fb_email: false sms_subscription: true apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE age_verified_status: true account_created_at: '2020-03-27T04:34:35-05:00' user_joined_at: '2016-03-16T11:40:07+00:00' summary: Fetch User Information description: Returns a user's details operationId: mobile_fetch_user_information tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' x-stoplight: id: fe0fd0660fed4 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE /api2/mobile/users: put: responses: '200': description: '' content: application/json: schema: type: object properties: access_token: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null user: address: '' avatar_remote_url: IMAGE_URL_GOES_HERE birthday: '1999-01-01' communicable_email: test@example.com city: '' created_at: '2015-11-02T18:14:32+00:00' email: test@example.com email_verified: false facebook_signup: null favourite_locations: '' favourite_store_numbers: '' fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE gender: male last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: upf0: Coffee|Tea|Lemonade upf1: Pasta|Pizza|Hamburger upf2: Movies|Music|Sports referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com state: Ohio superuser: false terms_and_conditions: false title: '' updated_at: '2016-05-09T12:27:52+00:00' user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 user_relations: [] zip_code: '70001' anniversary: null verification_mode: null apple_signup: null apple_uid: null has_generated_fb_email: false sms_subscription: true apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE age_verified_status: true user_joined_at: '2015-11-02T18:14:32+00:00' '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: email: type: array items: type: string examples: default: value: errors: email: - Email has already been taken summary: Update User Profile description: 'Updates a user''s profile details. Note: 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: mobile_update_user_profile tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: c9b928e35a6f3 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: first_name: type: string description: First name of the user last_name: type: string description: Last name 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. email: type: string description: Unique email address used to identify the user current_password: type: string x-stoplight: id: p36v959ub5xi6 description: Current password of the user’s account password: type: string description: New password of the user's account password_confirmation: type: string description: New password re-typed by the user for confirmation apn_token: type: string description: Apple push-notification token that allows push notifications to be received on the registered device of the user gcm_token: type: string description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user birthday: type: string enum: - YYYY-MM-DD format: date description: Date of birth 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. favourite_location_ids: type: string description: List of the user's favorite locations secondary_email: type: string description: Secondary email address of the user anniversary: type: string enum: - YYYY-MM-DD format: date description: Anniversary date of the user, in YYYY-MM-DD format zip_code: type: number description: Zip code where the user lives address: type: string description: Address of the user state: type: string description: State where the user lives phone: type: number description: Phone number of the user gender: type: string description: Gender of the user profile_field_answers: $ref: '#/components/schemas/profile_field_answers' invite_code: type: string description: Invitation code received by the user via e-mail or social media channels (e.g., WhatsApp, Facebook, etc.) city: type: string description: City where the user lives marketing_email_subscription: description: Whether the user has subscribed to receive marketing emails or not type: boolean marketing_pn_subscription: description: Whether the user has subscribed to marketing push notifications or not type: boolean title: type: string description: Salutation as selected by the user terms_and_conditions: type: boolean description: Whether the terms and conditions of a business have been accepted by the user or not 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 (provided in the `external_source` request parameter), 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: frlfsmbueypb5 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 examples: Update user profile: value: client: CLIENT_GOES_HERE user: first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE avatar_remote_url: URL_GOES_HERE email: test@example.com current_password: CURRENT_PASSWORD_GOES_HERE password: NEW_PASSWORD_GOES_HERE password_confirmation: NEW_PASSWORD_GOES_HERE apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE birthday: '' favourite_location_ids: '304155' secondary_email: test@example.com anniversary: '' zip_code: '70001' address: ADDRESS_GOES_HERE state: Ohio phone: '1111111111' gender: male profile_field_answers: upf0: Coffee|Tea|Lemonade upf1: Pasta|Pizza|Hamburger upf2: Movies|Music|Sports age_verified_status: true Update access token for an external IDP user: value: client: CLIENT_GOES_HERE user: first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE email: test@example.com password: PASSWORD_GOES_HERE password_confirmation: PASSWORD_GOES_HERE external_source: customer_id external_source_id: '11111111111111111111' description: '' 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: $ref: '#/components/schemas/access_token-Object' user: $ref: '#/components/schemas/User-object' examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null user: address: ADDRESS_GOES_HERE avatar_remote_url: null birthday: '1999-01-01' communicable_email: test@example.com city: Mountain View created_at: '2016-03-16T11:40:07+00:00' email: test@example.com email_verified: false facebook_signup: null favourite_locations: '304155' favourite_store_numbers: '1023' fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: male last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: {} referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: test@example.com state: California superuser: false terms_and_conditions: true title: null updated_at: '2016-03-16T11:40:08+00:00' user_as_barcode: '1111111' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 user_relations: [] zip_code: '30201' anniversary: '2013-07-13' verification_mode: null apple_signup: null apple_uid: null has_generated_fb_email: false sms_subscription: true apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE age_verified_status: true user_joined_at: '2016-03-16T11:40:07+00:00' '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: - Device already shared with maximum number of guests allowed. summary: Sign up / Register description: "Registers a user's profile on the app of a business\n\nNote: If the business is using\ \ referral code, the actual `first_name` and `last_name` of the guest must be passed because the\ \ referral code will be generated using the `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. \n\n### Using Referral Code As Invite Code in the Sign-up Process\n\nWhen a user\ \ signs up using the Sign up / Register 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.\n\nWhen a referred user signs up and enters the shared referral code in the mobile\ \ app, this `referral_code` must be passed in the `invite_code` request parameter when calling\ \ the Sign up / Register API." operationId: mobile_sign_up tags: - Users parameters: - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 2e67abf6f8e12 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: first_name: type: string description: First name of the user last_name: type: string description: Last name 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. email: type: string description: Unique email address used to identify the user password: type: string description: Password of the user's account (must be at least 8 characters in length) password_confirmation: type: string description: Password re-typed by the user for confirmation apn_token: type: string description: Apple push-notification token that allows push notifications to be received on the registered device of the user gcm_token: type: string description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user birthday: type: string enum: - YYYY-MM-DD format: date description: Date of birth of the user, in YYYY-MM-DD format favourite_location_ids: type: string description: List of the user's favorite locations secondary_email: type: string description: Secondary email address of the user anniversary: type: string enum: - YYYY-MM-DD format: date description: Anniversary date of the user, in YYYY-MM-DD format zip_code: type: number description: Zip code where the user lives address: type: string description: Address of the user state: type: string description: State where the user lives phone: type: number description: Phone number of the user gender: type: string description: Gender of the user send_compliance_sms: type: string 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. For more information, see [Implementing SMS Marketing](/docs/dev-portal-mobile/02814dcf572d5-implementing-sms-marketing). profile_field_answers: $ref: '#/components/schemas/profile_field_answers' invite_code: type: string description: 'The referral code of the user making the referral. The Sign up / Register API returns a referral code within the user object when a user signs up for the business loyalty program. When a referred user signs up and enters the shared referral code in the mobile app, this `referral_code` must be passed in the `invite_code` request parameter when calling the Sign up / Register API.' city: type: string description: City where the user lives marketing_email_subscription: description: Whether the user has subscribed to receive marketing emails or not type: boolean marketing_pn_subscription: description: Whether the user has subscribed to marketing push notifications or not type: boolean title: type: string description: Salutation as selected by the user terms_and_conditions: type: boolean description: Whether the terms and conditions of a business have been accepted by the user or not 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 (provided in the `external_source` request parameter), 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. signup_channel: type: string description: 'Use this field to overrride the default channel of "MobileEmail". The possible values are: `MobileEmail`, `MobileFacebook`, `POS`, `WebEmail`, `WebFacebook`, `eClub`, `OnlineOrder`, `Chatbot`, `Wifi`, `MobileApple` ' default: MobileEmail age_verified_status: type: boolean x-stoplight: id: m5z5p3rzlcda2 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 - email - password - password_confirmation examples: default: value: client: CLIENT_GOES_HERE user: email: test@example.com password: PASSWORD_GOES_HERE password_confirmation: PASSWORD_GOES_HERE first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE phone: 1111111111 apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE 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: male invite_code: INVITE_CODE_GOES_HERE terms_and_conditions: true external_source: SOURCE_GOES_HERE external_source_id: SOURCE_ID_GOES_HERE send_compliance_sms: 'true' signup_channel: Wifi age_verified_status: true description: '' delete: summary: Request for Account Deletion operationId: delete-api2-mobile-users responses: '200': description: OK content: application/json: schema: description: '' type: object properties: message: type: string minLength: 1 required: - message x-examples: example-1: message: Guest marked for deletion. Data will be automatically deleted within 7 days. examples: Success: value: message: Guest marked for deletion. Data will be automatically deleted within 7 days. '400': description: Bad Request content: application/json: schema: description: '' type: object properties: errors: type: object properties: client: type: string minLength: 1 required: - client required: - errors x-examples: example-1: errors: client: Required parameter missing or the value is empty. examples: Bad Request: value: errors: client: string '401': description: Unauthorized content: application/json: schema: description: '' type: object properties: errors: type: object properties: unauthorized: type: array required: - unauthorized required: - errors x-examples: example-1: errors: unauthorized: - An active access token must be used to query information about the current user. examples: Unauthorized / already deleted account: value: errors: unauthorized: - An active access token must be used to query information about the current user. '412': description: Precondition Failed content: application/json: schema: description: '' type: object properties: errors: type: object properties: invalid_signature: type: array required: - invalid_signature required: - errors x-examples: example-1: errors: invalid_signature: - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is examples: Invalid or signature missing: value: errors: invalid_signature: - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is '422': description: Unprocessable Entity content: application/json: schema: description: '' type: object properties: errors: type: object properties: guest_deletion: type: array required: - guest_deletion required: - errors x-examples: example-1: errors: guest_deletion: - Guest deletion is not configured examples: Gift card associated with the user: value: errors: gift_cards: - Gift card(s) found!. Please cashout/remove before deletion Guest deletion is not configured: value: errors: guest_deletion: - Guest deletion is not configured description: 'Marks the authenticated user''s account for deletion. The user account will be deleted within the days configured in the Punchh platform. In order for this API to work, configuration is needed on the Punchh platform. Note: The User-Agent header **must** contain one of these values in order to identify the device as a mobile device: "iOS", "iPhone", "iPone Simulator", "Android".' parameters: - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Authorization' tags: - Users x-stoplight: id: 1641b7778e8a6 requestBody: content: application/json: schema: type: object x-examples: example-1: client: CLIENT_GOES_HERE properties: client: type: string minLength: 1 description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/users/forgot_password: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: Bad Request (invalid language): value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. Bad Request (missing parameter): value: "{ \n \"errors\":{ \n \"email\":\"Required parameter missing or the value\ \ is empty.\"\n }\n}" '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. summary: Forgot Password description: Sends an email to a user with a reset password link. This API is invoked when a user initiates the forgot password flow on the app of a business. operationId: mobile_forgot_password tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 609f9496cf2fe requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: email: type: string description: Email address of the user required: - email required: - client examples: default: value: client: CLIENT_GOES_HERE user: email: test@example.com /api2/mobile/users/account_history: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: channel: type: string enum: - OnlineOrder - POS - Web - Mobile - Dashboard description: 'Identifies the source of a "Checkin" or "Redemption" event type. For example, "Mobile" in the case of a "Checkin" event indicates that the check-in was done by a user using the mobile app of the business. Possible values of the `channel` request parameter are: - OnlineOrder - POS - Web - Mobile - Dashboard' date: type: string enum: - YYYY-MM-DD format: date description: Date/time when the event was created in the system, in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format description: type: string description: A brief description of the event total_spend: type: string description: Amount that the user spent on the order. Will be returned if the event type is "Checkin". disapproved: type: boolean description: A particular event may be disapproved by the system or an admin for some reason. In this case, a value of true will be returned. Currently, only check-ins may be disapproved. event_details: $ref: '#/components/schemas/Event-details-object' event_value: type: string enum: - Reward - Checkin - Redemption - RewardCredit description: 'Value according to the event. - Checkin: Number of points/visits earned (e.g., "+20 points") - Reward: "+Item" - RewardCredit: Banked amount (e.g., "+$30.00") - Redemption: A redemption is requested by a user.' expired: type: boolean description: An event may expire. For example, a reward given to a user may expire if unredeemed. In this case, a value of true will be returned. pending_refresh: type: boolean description: Used only with a "Checkin" event. A value of true indicates that a check-in will go into a pending state until the time that the check is finally closed. store_number: type: string description: Identification of a particular store of a business in the system. The store numbers are provided by the business. sub_value: type: string description: Value of the points that are converted to banked currency. For example, if 100 points get converted to $10, the value of `sub_value` will be 100 points. menu_items: $ref: '#/components/schemas/response-menu-items' event_title: type: string description: Title of the event created by the system. For example, a "Points Earned" title is returned when a user earns points as the result of a check-in. This will respect the locale. event_type: type: string description: 'The event for which an entry was created. Possible values are: - Checkin - Reward - RewardCredit - Redemption' total_banked_currency: type: number format: double description: Total value of banked currency available to a user total_offers: type: integer description: Total number of offers that are available to a user total_points: type: integer description: Total number of points that are available to the user. This value increases when a check-in happens and decreases when points are converted to banked currency. total_visits: type: integer description: Total number of visits of the user until the event event_expiry: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Expiration date for the event as configured in the Punchh platform examples: default: value: - channel: null date: '2019-05-17T08:29:35-04:00' description: Dessert redeemed using redemption code 6384949 at TEST-Winghouse_Squirrel- Test No Report (Available) disapproved: false event_details: redemption_status: redeemable created_at: '2019-05-17T08:29:35-04:00' redeemable_id: 106 redeemable_name: Dessert redeemed_value: null redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: Redeem your Free Dessert with the purchase of an entree updated_at: '2019-05-17T08:29:35-04:00' redemption_id: 1765525 redemption_tracking_code: '6384949' expiring_at: '2019-05-18T08:29:35-04:00' event_value: (Item) expired: false pending_refresh: false store_number: '' sub_value: null event_title: Item Redeemed event_type: Redemption total_banked_currency: 10 total_offers: 1 total_points: 65 total_visits: null event_expiry: null - channel: null date: '2019-05-17T08:23:29-04:00' description: 'You were gifted: Dessert (Support Activity)' disapproved: false event_details: null event_value: +Item expired: false pending_refresh: false store_number: null sub_value: null event_title: Item Gifted event_type: Reward total_banked_currency: 10 total_offers: 1 total_points: 65 total_visits: null event_expiry: null - channel: null date: '2019-05-17T08:22:26-04:00' description: 100 points converted into $10.00 of banked rewards disapproved: false event_details: null event_value: +$10.00 expired: false pending_refresh: false store_number: null sub_value: (100 pts) event_title: Rewards Earned event_type: RewardCredit total_banked_currency: 10 total_offers: 0 total_points: 65 total_visits: null event_expiry: '2019-06-26T06:59:59Z' - channel: Mobile date: '2019-05-17T08:22:26-04:00' description: 165 points earned for your $165.24 purchase at TEST-Winghouse_Squirrel- Test No Report disapproved: false event_details: null event_value: +165 points expired: false pending_refresh: false store_number: '' sub_value: null event_title: Points Earned event_type: Checkin total_banked_currency: 0 total_offers: 0 total_points: 165 total_visits: null event_expiry: '2019-06-29' summary: User Account History description: Returns a user's account history details. This includes transactions such as check-in, redemption, etc. This does not include gift card related transactions. operationId: mobile_user_account_history tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f340773e6bef7 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business event_filter: type: string x-stoplight: id: hniphvocrlrml description: This parameter will work only if the business opted for subscription. enum: - reward - checkins - rewardcredit - redemption required: - client examples: default: value: client: CLIENT_GOES_HERE event_filter: reward /api2/mobile/user_relations/{id}: put: responses: '200': description: '' content: application/json: schema: type: object properties: id: type: integer description: Three-digit ID assigned to the person related to the user relation: type: string description: The relationship of the person with the user (spouse or kid) name: type: string description: Name of the person related to the user birthday: type: string description: Birthday of the person related to the user, in YYYY-MM-DD format enum: - YYYY-MM-DD format: date created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user relation was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user relation was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format examples: default: value: id: 775 relation: kid name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE birthday: '1999-01-01' created_at: '2016-03-28T03:14:12-05:00' updated_at: '2016-03-28T04:14:55-05:00' '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' '404': description: '' content: application/json: examples: default: value: errors: User Relation Not Found '422': description: '' content: application/json: examples: default: value: errors: relation: - Relation is not included in the list summary: Update User Relation description: Updates a user's existing relation (spouse or kid) in the system operationId: mobile_update_user_relation tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - schema: type: integer in: path name: id required: true description: Three-digit ID of the person related to the user - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 9fb124cb29aa1 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business relation: type: string enum: - kid - spouse description: The relationship of the person with the user (spouse or kid) name: type: string description: Name of the person related to the user birthday: type: string enum: - YYYY-MM-DD format: date description: Birthday of the person related to the user, in YYYY-MM-DD format required: - client examples: default: value: client: CLIENT_GOES_HERE relation: kid name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE birthday: '1999-01-01' delete: responses: '200': description: OK content: application/json: schema: description: '' type: object properties: message: type: string minLength: 1 required: - message x-examples: example-1: message: Guest marked for deletion. Data will be automatically deleted within 7 days. examples: Success: value: message: Guest marked for deletion. Data will be automatically deleted within 7 days. '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '404': description: '' content: application/json: examples: default: value: errors: User Relation Not Found '412': description: Precondition Failed content: application/json: schema: description: '' type: object properties: errors: type: object properties: invalid_signature: type: array required: - invalid_signature required: - errors x-examples: example-1: errors: invalid_signature: - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is examples: Signature Invalid/Missing: value: errors: invalid_signature: - Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is summary: Delete User Relation description: Deletes an existing relation (spouse or kid) of a user from the system operationId: user_delete_user_relation tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' x-stoplight: id: 061f38d2b2277 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: id in: path required: true description: Three-digit ID of the person related to the user /api2/mobile/user_relations: post: responses: '200': description: '' content: application/json: schema: type: object properties: id: type: integer description: Three-digit ID assigned to the person related to the user relation: type: string description: The relationship of the person with the user (spouse or kid) name: type: string description: Name of the person related to the user birthday: type: string description: Birthday of the person related to the user, in YYYY-MM-DD format enum: - YYYY-MM-DD format: date created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user relation was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the user relation was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format examples: default: value: id: 774 relation: spouse name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE birthday: '1999-01-01' created_at: '2016-03-28T06:48:07+00:00' updated_at: '2016-03-28T06:48:07+00:00' '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: relation: type: string examples: default: value: errors: relation: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' summary: Create User Relation description: "Creates a user relation in the system to indicate a user's relationship with another\ \ person. Valid relations that can be created are 'spouse' and 'kid'.\n\n " operationId: mobile_create_user_relation tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: b725c75ab96d5 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business relation: type: string enum: - spouse - kid format: spouse description: The relationship of the person with the user (spouse or kid) name: type: string description: Name of the person related to the user birthday: type: string enum: - YYYY-MM-DD format: date description: Birthday of the person related to the user, in YYYY-MM-DD format required: - client - relation - name - birthday examples: default: value: client: CLIENT_GOES_HERE relation: spouse name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE birthday: '1999-01-01' /api2/mobile/users/send_verification_email: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} summary: Send Verification Email description: Sends an account verification email to the email address provided by a user operationId: mobile_send_verification_email tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: bf432b4fd3e94 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/session_tokens: post: responses: '200': description: '' content: application/json: schema: type: object properties: token: type: string description: 'This is a short-lived token requested by the mobile app. Once received, this token is used at the POS to validate the user''s identity and, once validated, to process the check-in/redemption done from the POS. The time after which this token expires can be configured in the Punchh platform.' expiring_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time at which the session token will expire examples: default: value: token: TOKEN_GOES_HERE expiring_at: '2016-11-03T06:55:24-04:00' summary: Get User Session Token description: Returns a short-lived session token that can be used to look up a user via POS/kiosk (if supported) operationId: mobile_get_user_token tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: e82d9f629c2a4 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 75bb8ienqvvfa description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/async_users: patch: responses: '202': description: Blank Response content: application/json: schema: {} summary: Asynchronous User Update description: 'Updates the details of a user asynchronously. Note: 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: mobile_asynchronous_user_update tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: 35eb8ca0e7ee3 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user: type: object properties: first_name: type: string description: First name of the user last_name: type: string description: Last name 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. email: type: string description: Unique email address used to identify the user current_password: type: string description: Current password of the user's account. This parameter should be passed if the user needs to reset the account's password. password: type: string description: New password for the user's account password_confirmation: type: string description: New password re-typed by the user for confirmation apn_token: type: string description: Apple push-notification token that allows push notifications to be received on the registered device of the user gcm_token: type: string description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token that allows push notifications to be received on the registered device of the user birthday: type: string enum: - YYYY-MM-DD format: date description: Date of birth of the user. 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. favorite_location_ids: type: string description: List of the user's favorite locations secondary_email: type: string description: Secondary email address of the user anniversary: type: string enum: - YYYY-MM-DD format: date description: Anniversary date of the user. This field gets updated in the database only if the user did not set it initially during sign-up. zip_code: type: number description: Zip code where the user lives address: type: string description: Address of the user state: type: string description: State where the user lives phone: type: number description: Phone number of the user gender: type: string description: Gender of the user profile_field_answers: $ref: '#/components/schemas/profile_field_answers' required: - client examples: Request: value: client: CLIENT_GOES_HERE user: first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE avatar_remote_url: URL_GOES_HERE email: test@example.com current_password: PASSWORD_GOES_HERE password: PASSWORD_GOES_HERE password_confirmation: PASSWORD_GOES_HERE apn_token: APN_TOKEN_GOES_HERE gcm_token: GCM_TOKEN_GOES_HERE birthday: '' favourite_location_ids: '304155' secondary_email: test@example.com anniversary: '' zip_code: '70001' address: ADDRESS_GOES_HERE state: Ohio phone: '1111111111' gender: male profile_field_answers: upf0: Coffee|Tea|Lemonade upf1: Pasta|Pizza|Hamburger upf2: Movies|Music|Sports /api2/mobile/aws_s3_pre_signed_url: post: responses: '200': description: '' content: application/json: schema: type: object properties: url: type: string url_fields: type: object properties: key: type: string success_action_status: type: string policy: type: string x-amz-credential: type: string x-amz-algorithm: type: string x-amz-date: type: string x-amz-signature: type: string ? '' : type: string examples: default: value: url: URL_GOES_HERE url_fields: key: /Pictures/Sample Pictures/Chrysanthemum.jpg success_action_status: '201' policy: TOKEN_GOES_HERE x-amz-credential: CREDENTIAL_GOES_HERE x-amz-algorithm: ALGORITHM_GOES_HERE x-amz-date: 20190116T093110Z x-amz-signature: SIGNATURE_GOES_HERE '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: default: value: errors: unauthorized: - An active access token must be used to query information about the current user. summary: Image Upload to AWS description: Uploads an image file to an AWS server operationId: mobile_image_upload_to_aws tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 8e9b5ed7623dd requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business filename: type: string description: Name of the file that will be uploaded to AWS required: - client - filename examples: default: value: client: CLIENT_GOES_HERE filename: IMAGE_URL_GOES_HERE /api2/mobile/users/balance: get: summary: Fetch User Balance description: Displays user information regarding active redemptions, notifications, badges, balance, etc. operationId: mobile_fetch_user_balance tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' responses: '200': description: '' content: application/json: schema: type: object properties: active_redemptions: $ref: '#/components/schemas/redemption_details' challenge_badges: type: array items: type: object properties: badge_id: type: integer description: Challenge ID challenge_campaign_id: type: integer description: Campaign ID of the challenge published: type: boolean description: A value of true indicates that the challenge is available. public_url: type: string description: URL of the challenge challenge_campaign_status: type: string description: 'Possible values are: - **active** - The campaign is active. - **deactivated** - The campaign is inactive. - **expired** - The campaign’s end date is in the past.' coupons: $ref: '#/components/schemas/Coupons' messages: $ref: '#/components/schemas/UserBalanceMessages' notifications: $ref: '#/components/schemas/Notifications' rewards: $ref: '#/components/schemas/rewards' punch_cards: type: array items: type: object properties: progress: type: array items: type: object properties: completed_steps: type: integer description: Number of steps completed total_steps: type: integer description: Total number of steps that need to be completed to acquire a card name: type: string description: Name of the card description: type: 'null' description: Description of the card image_url: type: string description: Image of the card challenge_id: type: integer description: ID of the challenge icon_url: type: string description: Image icon of the card icon_completed_url: type: string description: Image icon that represents completion of the card start_date: type: string enum: - YYYY-MM-DD format: date description: Start date end_date: type: string enum: - YYYY-MM-DD format: date description: End date gift_reason: type: string description: Reason to give gifts to a user miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform challenge_reach: type: string x-nullable: true description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are: - universal_auto_enrolment - segment_auto_enrolment - null (when no reach strategy is defined)' challenge_status: type: string x-nullable: true description: 'Returns the details of availability of and enrollment of a guest into a specific challenge. Possible values are: * unavailable: This status will be returned for "segment_auto_enrolment" when a guest is NOT added to the "user_feature_enrolment" table. * enrolled: This status will be returned for:
a) "universal_auto_enrolment" in all cases since all signed-up guests are automatically enrolled for the challenge.
b) "segment_auto_enrolment" in cases when guests from the attached segment (to the challenge campaign) get added to the user_feature_enrolment table and are automatically enrolled for the challenge.
* null: For older default "Segment" type challenges, the status will always be null.' challenge_type: type: string description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are: - receipt_qualification - every_x_points - segment' occurrence: type: string description: 'Possible values are: - **single** - Shows when restarting the challenge button is OFF in the campaign - **multiple** - Shows when restarting the challenge button is ON in the campaign' past_completions: type: integer description: The number of times the user has previously completed the challenge campaign. challenge_expiring_at_tz: type: string x-stoplight: id: 42waxpsot8sfd description: Challenge expiry date and time based on the business time zone, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ preferred_charities: type: array items: type: object properties: user_donations: type: object properties: reward: type: object properties: user_donations: type: integer description: Amount that the user donated last_donated_item: type: 'null' description: Item that the user donated last_donation_time: type: 'null' description: Time at which the user donated name: type: string description: Name of the social cause campaign description: type: string description: Description of the charity social_cause_id: type: integer description: ID of the social cause campaign image_url: type: string description: Image of the campaign miscellaneous: type: string city: type: string description: City where the user lives state: type: string description: State where the user lives street: type: string description: Street where the user lives zip: type: string description: Zip code where the user lives phone_number: description: Phone number of the user x-nullable: true email: type: string description: Email address of the user address: type: string description: Address of the user converted_category_balances: $ref: '#/components/schemas/Converted-Category-Balance' account_balance: $ref: '#/components/schemas/account-balance-details' examples: default: value: converted_category_balances: - category_id: 1 name: Casey Cash source_type: points source_value: 250 min_source_value: 250 converted_type: currency converted_value: 1 balance: '42.36' - category_id: 2 name: Fuel source_type: points source_value: 250 min_source_value: 250 converted_type: fuel_discount converted_value: 0.05 balance: '0.50' - category_id: 4 name: Charity source_type: points source_value: 250 min_source_value: 250 converted_type: charity converted_value: 1 balance: '20.00' active_redemptions: [] challenge_badges: - badge_id: 121 challenge_campaign_id: 7 published: false public_url: URL_GOES_HERE challenge_campaign_status: active - badge_id: 877 challenge_campaign_id: 7 published: false public_url: URL_GOES_HERE challenge_campaign_status: active - badge_id: 8992 challenge_campaign_id: 124856 published: false public_url: URL_GOES_HERE challenge_campaign_status: deactivated coupons: - code: CPUNCHHC8KR0B3D image_url: IMAGE_URL_GOES_HERE name: Free Breadsticks description: '' start_date: '2019-05-15' end_date: null messages: [] notifications: [] rewards: - becomes_available_at: '2019-04-08T12:53:13-05:00' campaign_type: null created_at: '2019-04-08T12:53:13-05:00' description: TEST discount_channel: all discount_amount: null reward_image_url: IMAGE_URL_GOES_HERE name: $1 discount on test item read_at: null reward_properties: '' store_numbers: [] franchisee_id: null meta_data: '[{"item":"1010", "qty":"1","type":"food"}, {"item":"1011", "qty":"2","type":"drink"}]' redeemable_created_at: '2019-04-08T12:49:52-05:00' reward_id: 5 expiring_at: null expiring_at_tz: null redemption_details: null auto_select: true - becomes_available_at: '2019-05-29T08:11:40-05:00' campaign_type: deal created_at: '2019-05-29T08:11:40-05:00' description: '' discount_channel: all discount_amount: 0 reward_image_url: IMAGE_URL_GOES_HERE name: Base Redeemable read_at: null reward_properties: '' store_numbers: [] franchisee_id: null meta_data: '' redeemable_created_at: '2019-03-11T08:05:41-05:00' reward_id: 343 expiring_at: null expiring_at_tz: null redemption_details: null auto_select: true - becomes_available_at: '2020-12-01T14:58:03-06:00' campaign_type: null created_at: '2020-12-01T14:58:03-06:00' description: 'Enjoy a free coffee courtesy of Casey''s. ' discount_channel: all discount_amount: null reward_image_url: IMAGE_URL_GOES_HERE name: You've Earned a Free Coffee read_at: null reward_properties: '' store_numbers: [] franchisee_id: null meta_data: '[{ "item" : "Coffee Club", "qty" : 1, "type": "Beverages" }]' redeemable_created_at: '2019-09-04T16:41:21-05:00' reward_id: 9214 expiring_at: '2020-12-30T23:59:59-06:00' expiring_at_tz: '2020-12-30T23:59:59-06:00' redemption_details: null auto_select: true punch_cards: - progress: - completed_steps: 0 total_steps: 10 name: Punchh product qa test currency description: '' image_url: IMAGE_URL_GOES_HERE icon_url: IMAGE_URL_GOES_HERE icon_completed_url: IMAGE_URL_GOES_HERE start_date: '2022-03-09' end_date: '2022-03-12' gift_reason: Punchh product qa test currency miscellaneous: '' challenge_reach: segment_auto_enrolment challenge_status: unavailable challenge_type: every_x_points occurrence: single past_completions: 0 challenge_expiring_at_tz: '2022-03-12T00:00:00+05:30' challenge_id: 124872 - progress: - completed_steps: 0 total_steps: 5 name: Buy 5 Cheese Breadsticks description: Buy 5 Cheese Breadsticks image_url: IMAGE_URL_GOES_HERE icon_url: IMAGE_URL_GOES_HERE icon_completed_url: IMAGE_URL_GOES_HERE start_date: '2022-02-08' end_date: '2022-02-23' gift_reason: Buy 5 Cheese Breadsticks miscellaneous: '{"detailedDescription":"Earn 50 bonus points after you purchase five breadsticks. Your points will automatically be added to your account after completion. Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"fuel", "GiftPoints":"0.55", "challengeType":"Personal", "nounDescription" : "fuel"}' challenge_reach: segment_auto_enrolment challenge_status: enrolled challenge_type: receipt_qualification occurrence: single past_completions: 0 challenge_expiring_at_tz: '2022-02-23T00:00:00+05:30' challenge_id: 124875 - progress: - completed_steps: 0 total_steps: 3 name: Buy 4 Breadsticks! description: Get your 4th Breadstick free image_url: IMAGE_URL_GOES_HERE icon_url: IMAGE_URL_GOES_HERE icon_completed_url: IMAGE_URL_GOES_HERE start_date: '2022-02-08' end_date: '2022-02-25' gift_reason: Get your 4th Breadstick free miscellaneous: '{"detailedDescription":"Get your next cheese breadstick free after you purchase three breadsticks. . Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"offer", "GiftPoints":"50% off , Breadstick", "challengeType":"Personal","nounDescription" : "breadsticks"}' challenge_reach: segment_auto_enrolment challenge_status: enrolled challenge_type: receipt_qualification occurrence: multiple past_completions: 0 challenge_expiring_at_tz: '2022-02-25T00:00:00+05:30' challenge_id: 124876 preferred_charities: - user_donations: reward: user_donations: 0 last_donated_item: null last_donation_time: null currency: user_donations: 3 last_donated_item: 1 last_donation_time: '2019-07-10T05:28:31-05:00' name: Ankeney Southview Middle School description: This is a placeholder text social_cause_id: 13 image_url: IMAGE_URL_GOES_HERE miscellaneous: '' city: Ankeney state: IA street: Street zip: '50023' phone_number: '' email: '' address: 'ADDRESS_GOES_HERE ' account_balance: banked_currency: null 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: 0 redeemed_cards: null total_loyalty_visits: null unbanked_points: null unredeemed_cards: null current_membership_level_name: null lifetime_points: 117720 redeemable_points: 69324 membership_qualification_points: 500 '422': description: '' content: application/json: examples: default: value: {} x-stoplight: id: fb962621d8f10 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 5tuceicye86yb description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/conversions: post: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - 250 points converted into 2 '422': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: min_source_value: type: string examples: default: value: errors: - min_source_value: Source value should be more than 250.0. summary: Point Conversion description: Enables the conversion of a user's points to cash, fuel discounts, or charities based on the configuration or conversion rules set in the Punchh platform. operationId: mobile_point_conversion_API tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 2af7d8da43301 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: i2i3f0f5qqh2k description: OAuth client ID provided by the business conversion_rule_id: type: integer x-stoplight: id: xwh7ldne14zvb description: Conversion rule ID set per the Punchh platform configuration (returned for the `converted_category_balances` object as `category_id`) default: 1 converted_value: type: string x-stoplight: id: 27z7ksm2i4fqt description: Values of the cash, fuel discounts, or charities resuting from the points conversion default: 2 source_value: type: integer x-stoplight: id: regh5tf12f5z4 description: Number of the points that the user wants to convert to cash, fuel discounts, or charities default: 250 required: - client - conversion_rule_id - converted_value - source_value examples: default: value: client: CLIENT_GOES_HERE conversion_rule_id: 1 converted_value: '2' source_value: 250 /api2/mobile/deals: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: applicable_as_loyalty_redemption: type: boolean description: Enables redemables to be allowed for loyalty reward redemption as well redeemable_properties: type: array description: Properties such as “Merchandise”, “Food Item”, etc. can be added to a particular redeemable. items: type: string discount_amount: type: integer description: Discount amount associated with the deal discount_channel: type: string enum: - online_only - offline_only - all description: "Channels where the reward can be used. Possible values are: \n- \"\ online_only\" for online orders \n- \"offline_only” for POS\n- \"all” for both" expire_redemption_code_with_reward_end_date: type: boolean description: A value of true indicates that the redemption code will expire with the reward end date. 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: Value of points required to redeem a particular redeemable redeemable_id: type: integer description: Unique ID that identifies the redeemable in the system redemption_expiry: type: integer description: Expiry of the redemption thumb_image: type: string description: URL of the image displayed in the app to depict the redeemable meta_data: type: string description: Metadata of the redeemable 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. auto_select: type: boolean x-stoplight: id: kbf9px5ayohlv description: 'Whether the offer is enabled for auto-redemption or not. Possible values: true, false' start_time: type: string x-stoplight: id: vf165l5cthx2x format: date-time description: Activation date and time of the redeemable. A redeemable cannot be active before this date. 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: '' auto_select: true start_time: '2021-04-28T13:59:47+05:30' summary: List All Deals description: 'Returns all available deals for a user. The `page` and `per_page` request parameters determine the page(s) returned and the number of deals returned per page. If the `per_page` parameter is not sent, the API returns up to 10 deals in the response. ' operationId: mobile_list_all_deals tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: aaa03d2e343b3 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: w7yo61cubvs3o description: OAuth client ID provided by the business page: type: integer x-stoplight: id: 39czf279yiap7 default: 1 description: Page number. If `page` is specified, only that page will be returned using the value of `per_page` as the number of deals returned on that page. per_page: type: integer x-stoplight: id: cgez6jhtatngu default: 10 description: Number of deals per page. If `per_page` is not specified, the API defaults to 10 deals in response. required: - client examples: default: value: client: CLIENT_GOES_HERE page: 1 per_page: 20 post: responses: '200': description: Blank Response content: application/json: schema: type: object properties: {} summary: Save Selected Deal description: Adds the selected deal to a user's account operationId: mobile_save_selected_deal tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: da99d1bbd0010 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: f5mgzh67ohuoh description: OAuth client ID provided by the business redeemable_uuid: type: string x-stoplight: id: v4pr59q6jc5w2 description: Redeemable UUID of the deal to be saved by the user required: - client - redeemable_uuid examples: default: value: client: CLIENT_GOES_HERE redeemable_uuid: REDEEMABLE_UUID_GOES_HERE description: '' /api2/mobile/estimate_points: get: responses: '200': description: '' content: application/json: schema: type: object properties: estimated_points: type: integer description: Prediction of how many points can be earned before submitting the transaction examples: default: value: estimated_points: 100 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: mobile_estimate_points tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 4a866c8966734 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: lpcxiq0bjfzwv description: OAuth client ID provided by the business receipt_datetime: type: string description: Timestamp of the receipt, in YYYY-MM-DDTHH:mm:SSZ (ISO 8601) format menu_items: $ref: '#/components/schemas/menu-items' store_number: type: string description: Number of the store at which the check-in is made access_token: type: string x-stoplight: id: 523mt6z51an3f description: Access token of the user receipt_amount: type: string x-stoplight: id: 9qdk9xjn7out4 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: string x-stoplight: id: pi4k8geybcizp 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. required: - client - access_token - receipt_amount - subtotal amount examples: default: value: menu_items: - item_name: Brown rice item_qty: 1 item_amount: 7.86 menu_item_type: M menu_item_id: 3418 menu_family: '800' menu_major_group: '152' serial_number: '2.0' receipt_datetime: '2024-04-26T23:59:59-07:00' store_number: '20' access_token: ACCESS_TOKEN_GOES_HERE client: CLIENT_GOES_HERE receipt_amount: '7.86' subtotal amount: '7.86' /api2/mobile/balance_timelines: get: responses: '200': description: '' headers: {} content: application/json: schema: type: object properties: currency: type: array items: type: object properties: actual_earned_currency: type: number format: float description: Actual earned 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 conversation status: type: string description: 'Status of the entire conversion. Possible values are: `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 description: Actual earned 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 conversation status: type: string description: 'Status of the entire conversion. Possible values are: `partially_redeemed`, `unredeemed`, `honored`, `partially_redeemed_expired`, `unredeemed_expired`' client: type: string x-stoplight: id: ztffyyvjcsjy6 description: OAuth client ID provided by the business access_token: type: string x-stoplight: id: pytqoajmsrwty description: Access token of the user default: ACCESS_TOKEN_GOES_HERE required: - client - access_token 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 summary: Balance Timelines description: 'Gets the balance timelines of a user depending on currency or fuel discount or both Note: Depending on the configuration, different objects are returned in the response (currency, fuel_discount, etc.). Hence, the `fuel_discount` parameter is not returned in the response for businesses using only currency-based redemptions.' operationId: mobile_balance_timelines tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 07ca7a1288ef6 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: rqm2pw63vljbr description: OAuth client ID provided by the business access_token: type: string x-stoplight: id: jjarf7a4kccsh description: Access token of the user default: ACCESS_TOKEN_GOES_HERE required: - client - access_token examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE /api2/mobile/user_enrollments: post: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - Successfully registered '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: item_id: type: string examples: Required parameter missing: value: "{\n \"errors\": {\n \"item_id\": \"Required parameter missing or the\ \ value is empty.\"\n }\n}" '404': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - Feature does not exist. '417': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - User has already been enrolled for this feature. summary: User Enrollment description: Enrolls a user in a campaign (currently supported for social cause campaigns) operationId: mobile_user_enrollment tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: dae1df37a957b requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: x0pwcq77difm7 description: OAuth client ID provided by the business item_id: type: string x-stoplight: id: a69dve1qgiczf description: Campaign ID item_type: type: string x-stoplight: id: nyg3lf8sf2ni5 enum: - social_cause_campaign description: Type of campaign. The currently supported type is `social_cause_campaign`. required: - client - item_id - item_type examples: default: value: client: CLIENT_GOES_HERE item_id: '12' item_type: social_cause_campaign patch: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - Successfully deregistered '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: item_id: type: string examples: Item_id (required parameter missing): value: "{\n \"errors\": {\n \"item_id\": \"Required parameter missing or the value\ \ is empty.\"\n }\n}" Item_type (required parameter missing): value: "{\n \"errors\": {\n \"item_type\": \"Required parameter missing or\ \ the value is empty.\"\n }\n}" '404': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: Feature does not exist: value: "{\n \"errors\": [\n \"Feature does not exist.\"\n ]\n}" User not enrolled: value: "{\n \"errors\": [\n \"User not enrolled for this feature.\"\n ]\n\ }" summary: User Disenrollment description: Unregisters a user enrolled in a campaign (currently supported for social cause campaigns) operationId: mobile_user_disenrollment tags: - Users parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 3edf0bf622c77 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 9rl08pfb0g3io description: OAuth client ID provided by the business item_type: type: string x-stoplight: id: 498y6hhhvb6f9 description: Type of campaign. The currently supported type is `social_cause_campaign`. default: social_cause_campaign item_id: type: string x-stoplight: id: dmuy3bevuj4kf description: Campaign ID required: - client - item_type examples: default: value: client: CLIENT_GOES_HERE item_type: social_cause_campaign item_id: '2' description: '' /api2/mobile/loyalty_transfers/points: post: summary: Transfer Loyalty Points description: 'Enables a user to transfer loyalty points from their account to another user''s account by specifying the recipient''s email address or phone number and the number of points to transfer. The recipient must be an existing member in the loyalty system. The transfer is subject to the business''s configured transfer limits, including maximum transfer limits per account and daily receiving limits for the recipient. **Prerequisite**
Peer-to-peer points transfers must be enabled for the business. Contact your Punchh representative to update this Punchh platform configuration. ' operationId: mobile_loyalty_transfer_points tags: - Loyalty Transfers parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' responses: '200': description: OK content: application/json: schema: type: array items: type: string examples: default: value: - 1 transferred to Recipient Name '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string examples: Missing required parameter: value: error: 'Required parameter missing or the value is empty: points_to_transfer' Missing recipient email or identifier: value: "{\n \"errors\": {\n \"recipient_email\": \"Required parameter missing\ \ or the value is empty.\",\n \"recipient_email_or_recipient_identifier\":\ \ \"Required parameter missing or the value is empty\"\n }\n}" '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string examples: Unauthorized: value: error: You need to sign in or sign up before continuing. '422': description: Unprocessable Entity content: application/json: schema: type: array items: type: string examples: Insufficient balance: value: - Not enough reward balance available to redeem. Current Balance of 96 is less than 100 requested No user found for the provided email or phone number: value: - Recipient not found Receiver limit exceeded: value: - Receiver limit exceeded for points (max 5 in 30h) Duplicate phone numbers: value: - Something went wrong with the transfer. Please check your input and try again. Daily receiving limit reached: value: - This transfer cannot be completed because the receiving member has reached the daily receiving limit. Maximum transfer limit exceeded: value: - Your transfer cannot be completed because it exceeds the maximum transfer limit set for your account. Invalid password: value: - Invalid password. Please try again. Service unavailable: value: - This service is currently unavailable for your account. Please contact support. Password required: value: - Password is required for peer-to-peer transfer. requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Token issued to the user after logging into the app of the business recipient_email: type: string description: Email address of the recipient to whom the loyalty points will be transferred.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. recipient_identifier: type: string description: 'Accepts either an email address or a phone number to identify the recipient of the points transfer. `recipient_identifier` is the primary parameter used to identify the recipient. The system automatically detects whether the provided value is an email address or a phone number.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. * If a valid phone number or email matches a single guest account, the transfer proceeds. * If a phone number matches multiple guest accounts, the transfer is blocked, and an error is returned. To prevent duplicate phone number error, we recommend enabling phone number uniqueness for the business. Contact your Punchh representative to update this Punchh platform configuration. * If no matching guest is found for the provided email or phone number, a "recipient not found" error is returned.' points_to_transfer: type: number description: Number of loyalty points to transfer to the recipient password: type: string description: Password of the user initiating the transfer. Required for peer-to-peer transfer. required: - client - access_token - points_to_transfer - password examples: Using email: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_email: recipient@example.com recipient_identifier: recipient@example.com points_to_transfer: '1' password: PASSWORD_GOES_HERE Using phone number: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_identifier: '1111111111' points_to_transfer: '1' password: PASSWORD_GOES_HERE /api2/mobile/loyalty_transfers/currency: post: summary: Transfer Loyalty Currency description: 'Enables a user to transfer loyalty currency (banked reward balance) from their account to another user''s account by specifying the recipient''s email address or phone number and the amount to transfer. The recipient must be an existing member in the loyalty system. The transfer is subject to the business''s configured transfer limits, including maximum transfer limits per account and daily receiving limits for the recipient. **Prerequisite**
Peer-to-peer currency transfers must be enabled for the business. Contact your Punchh representative to update this Punchh platform configuration. ' operationId: mobile_loyalty_transfer_currency tags: - Loyalty Transfers parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' responses: '200': description: OK content: application/json: schema: type: array items: type: string examples: default: value: - $1.00 transferred to Recipient Name '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string examples: Missing required parameter: value: error: 'Required parameter missing or the value is empty: amount_to_transfer' Missing recipient email or identifier: value: "{\n \"errors\": {\n \"recipient_email\": \"Required parameter missing\ \ or the value is empty.\",\n \"recipient_email_or_recipient_identifier\":\ \ \"Required parameter missing or the value is empty\"\n }\n}" '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string examples: Unauthorized: value: error: You need to sign in or sign up before continuing. '422': description: Unprocessable Entity content: application/json: schema: type: array items: type: string examples: Insufficient balance: value: - Not enough reward balance available to redeem. Current Balance of $96.00 is less than $100.00 requested No user found for the provided email or phone number: value: - Recipient not found Receiver limit exceeded: value: - Receiver limit exceeded for currency (max 5 in 30h) Duplicate phone numbers: value: - Something went wrong with the transfer. Please check your input and try again. Daily receiving limit reached: value: - This transfer cannot be completed because the receiving member has reached the daily receiving limit. Maximum transfer limit exceeded: value: - Your transfer cannot be completed because it exceeds the maximum transfer limit set for your account. Invalid password: value: - Invalid password. Please try again. Service unavailable: value: - This service is currently unavailable for your account. Please contact support. Password required: value: - Password is required for peer-to-peer transfer. requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Token issued to the user after logging into the app of the business recipient_email: type: string description: Email address of the recipient to whom the loyalty currency will be transferred.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. recipient_identifier: type: string description: 'Accepts either an email address or a phone number to identify the recipient of the currency transfer. `recipient_identifier` is the primary parameter used to identify the recipient. The system automatically detects whether the provided value is an email address or a phone number.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. * If a valid phone number or email matches a single guest account, the transfer proceeds. * If a phone number matches multiple guest accounts, the transfer is blocked, and an error is returned. To prevent duplicate phone number error, we recommend enabling phone number uniqueness for the business. Contact your Punchh representative to update this Punchh platform configuration. * If no matching guest is found for the provided email or phone number, a "recipient not found" error is returned.' amount_to_transfer: type: number description: Amount of loyalty currency to transfer to the recipient password: type: string description: Password of the user initiating the transfer. Required for peer-to-peer transfer. required: - client - access_token - amount_to_transfer - password examples: Using email: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_email: recipient@example.com recipient_identifier: recipient@example.com amount_to_transfer: '1' password: PASSWORD_GOES_HERE Using phone number: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_identifier: '1111111111' amount_to_transfer: '1' password: PASSWORD_GOES_HERE /api2/mobile/loyalty_transfers/reward: post: summary: Transfer Loyalty Reward description: 'Enables a user to transfer a loyalty reward from their account to another user''s account by specifying the recipient''s email address or phone number and the reward ID to transfer. The recipient must be an existing member in the loyalty system. The transfer is subject to the business''s configured transfer limits, including maximum transfer limits per account and daily receiving limits for the recipient. **Prerequisite**
Peer-to-peer rewards transfers must be enabled for the business. Contact your Punchh representative to update this Punchh platform configuration. ' operationId: mobile_loyalty_transfer_reward tags: - Loyalty Transfers parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' responses: '200': description: OK content: application/json: schema: type: array items: type: string examples: default: value: - Base Redeemable transferred to Recipient Name '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string examples: Missing required parameter: value: error: 'Required parameter missing or the value is empty: reward_to_transfer' Missing recipient email or identifier: value: "{\n \"errors\": {\n \"recipient_email\": \"Required parameter missing\ \ or the value is empty.\",\n \"recipient_email_or_recipient_identifier\":\ \ \"Required parameter missing or the value is empty\"\n }\n}" '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string examples: Unauthorized: value: error: You need to sign in or sign up before continuing. '422': description: Unprocessable Entity content: application/json: schema: type: array items: type: string examples: Reward does not exist: value: - Reward doesn't exist or has already been redeemed. No user found for the provided email or phone number: value: - Recipient not found Receiver limit exceeded: value: - Receiver limit exceeded for rewards (max 5 in 30h) Duplicate phone numbers: value: - Something went wrong with the transfer. Please check your input and try again. Daily receiving limit reached: value: - This transfer cannot be completed because the receiving member has reached the daily receiving limit. Maximum transfer limit exceeded: value: - Your transfer cannot be completed because it exceeds the maximum transfer limit set for your account. Invalid password: value: - Invalid password. Please try again. Service unavailable: value: - This service is currently unavailable for your account. Please contact support. Password required: value: - Password is required for peer-to-peer transfer. x-stoplight: id: loyalty-transfers-reward requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Token issued to the user after logging into the app of the business recipient_email: type: string description: Email address of the recipient to whom the loyalty reward will be transferred.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. recipient_identifier: type: string description: 'Accepts either an email address or a phone number to identify the recipient of the reward transfer. `recipient_identifier` is the primary parameter used to identify the recipient. The system automatically detects whether the provided value is an email address or a phone number.

Note: Either `recipient_email` or `recipient_identifier` is required. When both `recipient_identifier` and `recipient_email` are provided, `recipient_identifier` takes precedence. * If a valid phone number or email matches a single guest account, the transfer proceeds. * If a phone number matches multiple guest accounts, the transfer is blocked, and an error is returned. To prevent duplicate phone number error, we recommend enabling phone number uniqueness for the business. Contact your Punchh representative to update this Punchh platform configuration. * If no matching guest is found for the provided email or phone number, a "recipient not found" error is returned.' reward_to_transfer: type: number description: ID of the reward to transfer to the recipient password: type: string description: Password of the user initiating the transfer. Required for peer-to-peer transfer. required: - client - access_token - reward_to_transfer - password examples: Using email: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_email: recipient@example.com recipient_identifier: recipient@example.com reward_to_transfer: '73786533580' password: PASSWORD_GOES_HERE Using phone number: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE recipient_identifier: '1111111111' reward_to_transfer: '73786533580' password: PASSWORD_GOES_HERE /api2/mobile/meta.json: get: responses: '200': description: '' content: application/json: schema: type: object properties: android_ga_code: type: string description: Android Google Analytics code of the program's Android app android_geocode_api_key: type: string description: Android geolocation key beacon_uuid: type: string description: Unique ID that identifies a beacon deployed at any location content_language: type: string description: The language used in the response. Example values are "en", "es", "es-CR", etc. earning_description: type: string description: Brief description of the earning program for the business facebook_sharing: type: boolean description: Determines whether users can share feedback on their Facebook account or not email_verification_enabled: type: boolean description: 'Whether a user needs to verify the user''s email address by using the link sent in the verification email or not The default value is "false".' ios_ga_code: type: string description: iOS Google Analytics code of the program's iOS app ios_geocode_api_key: type: string description: iOS geolocation key marketing_image_url: type: string description: Marketing image URL of the business or service marketing_info: type: string description: A descriptive/fun blurb about the program marketing_message: type: string description: This is the default message that is shown to a user when the user writes a review. It is also the default tagline that appears on a Facebook post. marketing_title: type: string description: Name of the business or service uber_client_id: type: string description: Unique ID that identifies Punchh as a consumer of Uber APIs promotional_coupons_enabled: type: boolean description: Whether promotional coupons are enabled for the business or not gift_cards_enabled: type: boolean description: Whether the app of the business has gift cards or not gift_card_minimum_transaction_amount: type: integer description: Minimum amount with which gift card transactions (e.g., purchase/reload) will be allowed max_gift_card_balance: type: number format: double description: "Maximum currency amount that can be on a gift card \n\nA value of 0\ \ (zero) indicates that there is no limit on the amount that can be on a gift card." social_cause_campaigns_enabled: type: boolean description: Whether social cause campaigns are enabled for the business or not default_map_search_radius: type: integer description: The radius within which the app searches for business locations with respect to the current location of a user facebook_signup_incentive_text: type: string description: Text displayed on the sign-up screen to inform a user about any rewards the user might get by signing up using Facebook require_passcode_for_gift_card: type: boolean description: A secondary authentication that, if enabled from the Punchh platform, is required for sharing and transferring gift cards support_email_address: type: string description: Support email address of a program faq_url: type: string description: URL of a program's frequently asked questions (FAQ) page instagram_page_url: type: string description: Instagram page URL allowing users to follow a business on Instagram order_now_url: type: string description: URL of the page from which a user can order. This opens in the Order tab of the app. order_url_for_sso: type: string description: SSO URL menus_url: type: string description: URL of the page where the program's menus are explained privacy_url: type: string description: URL of the page where a user can privately interact with a business or service terms_and_conditions_url: type: string description: URL of the page that explains the program's terms and conditions nutrition_url: type: string description: URL of the nutrition page catering_url: type: string description: URL of the catering page careers_url: type: string description: URL of the careers page facebook_page: type: string description: Facebook page of the business twitter_handle: type: string description: Twitter handle that allows a user to follow an app (e.g., `@business_name`) share_invite_code_message: type: string description: Invitation code message as configured in the Punchh platform share_invite_code_title: type: string description: Invitation code title as configured in the Punchh platform share_invite_code_description: type: string description: Invitation code description as configured in the Punchh platform app_disclaimer: type: string description: Disclaimer about the app and its usage game_disclaimer: type: string description: Disclaimer about the gaming module available in the app upgrade_disclaimer: type: string description: Disclaimer about account upgrade (if available) in the app challenges_disclaimer: type: string description: Disclaimer about the challenges module available in the app earning_disclaimer: type: string description: Disclaimer about the earning rules in the app olo_base_url: type: string description: Specific to a business using the Olo online ordering service. Base URL used for online ordering olo_api_key_ios: type: string description: Specific to a business using the Olo online ordering service. API key for iOS apps olo_api_key_android: type: string description: Specific to a business using the Olo online ordering service. API key for Android apps olo_provider_key: type: string description: Specific to a business using the Olo online ordering service. Provider key to use online ordering offered by Olo olo_group_order_invite_url: type: string description: Specific to a business using the Olo online ordering service. Olo supports group orders. This URL is used to invite multiple users to collaborate while placing an order. business_id: type: integer description: Unique ID that identifies the business business_name: type: string description: Name of the business checkin_evidenced_by: type: string description: Method of check-in used by a user (e.g., barcode, qr_code, receipt_image, etc.) guest_identity_code_type: type: string description: How a user is identified at the POS (the POS scanner type - e.g., barcode, qr_code, etc.) visits_per_card: type: integer description: Number of visits required for a single card completion card_redemption_value: type: integer description: What a user gets when redeeming a completed card migration_allowed: type: boolean description: Returns "true" if the migration flag is enabled for devices minimum_visit_amount: type: integer description: Minimum amount in selected currency required for a visit to be counted minimum_visit_hours: type: integer description: Minimum time duration between two consecutive visits of a user so that both visits are counted separately minimum_age_to_signup: type: integer description: Minimum age at which a user is allowed to sign up misc1: type: string description: Miscellaneous field used for app-specific needs. 1 of 4 fields misc2: type: string description: Miscellaneous field used for app-specific needs. 2 of 4 fields misc3: type: string description: Miscellaneous field used for app-specific needs. 3 of 4 fields misc4: type: string description: Miscellaneous field used for app-specific needs. 4 of 4 fields earning_unit: type: string description: What a user earns as the result of a check-in. Values can be points or visits. currency_earned: type: integer description: Value of points/visits earned as the result of a conversion as configured in the Punchh platform points_conversion_threshold: type: integer description: The threshold value at which a user's accumulated points get converted to banked rewards. For example, after accumulating 100 points, the points get converted to dollars. redemption_expiry_minutes: type: integer description: The time duration after which a redemption code generated by a user expires allow_rating_in_feedback: type: boolean description: "A value of \"true\" indicates that the app of the business supports\ \ ratings in feedback. Ratings can be either stars or emojis. \n\nThe default value\ \ is \"false\"." maximum_rating_in_feedback: type: integer description: Maximum rating that can be given by a user, as configured in the Punchh platform. The scale will be from 1 to this maximum value, which can vary from 3 to 10. checkins_earn: type: string description: What a user earns as the result of a check-in. Values returned are "points", "visits", and "points_and_visits". gift_card_designs: type: array description: 'Returns the different card designs configured in the Punchh platform ' items: type: object properties: backgroud_image_url: type: string description: URL of the image that will be displayed as the background of a gift card card_type: type: string description: 'Type assigned to a particular gift card design. Different types available are: - Physical gift card - Virtual gift card' name: type: string description: Name assigned to a particular gift card design design_id: type: integer description: Unique ID of a particular gift card design locations: $ref: '#/components/schemas/Locations' membership_levels: $ref: '#/components/schemas/Membership-Levels' redeemables: $ref: '#/components/schemas/redeemable' games: type: array items: type: object properties: game_viral_message: type: string description: The message for the game. It should be intuitive. name: type: string description: Name of the game images_on_card: type: integer description: Image on the card displayed for the game scratch_valid_codes: type: string game_type: type: string description: Game type (e.g., scratch_n_match, slot_machine, apples, etc.) requires_code_validation: type: boolean description: Whether games require a validation code to begin game_id: type: integer description: ID provided by Punchh that identifies the game in the business gaming_levels: type: array items: type: object properties: extra_punchhs: type: integer redeemable_id: x-nullable: true level: type: string profile_field_questions: $ref: '#/components/schemas/profile_field_questions-Object' banking_rules: $ref: '#/components/schemas/banking_rules-Object' base_redeemable: $ref: '#/components/schemas/base_redeemable-Object' payment_credential: $ref: '#/components/schemas/payment_credential' enable_gift_card_auto_reload: type: boolean description: Whether the Gift Card Auto Reload option is enabled for a business or not gift_card_auto_reload_threshold: type: number format: float description: Threshold amount below which a gift card becomes eligible for auto-reload gift_card_auto_reload_default: type: number format: float description: Default amount with which an eligible gift card will be auto-reloaded gift_card_auto_reload_disclaimer: type: string description: Disclaimer about gift card auto-reload subscriptions: $ref: '#/components/schemas/subscription' subscription_enabled: type: boolean description: Whether the subscription feature is enabled for the business or not subscriptions_payment_credential: $ref: '#/components/schemas/subscriptions_payment_credential' auto_select_strategy: type: string x-stoplight: id: eouuusnx6t4mk description: One or more categories of discount types chosen for automatically applying discounts. Possible values - offer, subscription. The auto-redemption strategy selected by the business can be consumed by the mobile app to identify the offers that will be auto-applicable. This enables guests to have visibility on their available offers, which can be automatically applied on their discount basket during a transaction if their discount basket qualifies for auto-applicable offers. Applicable to businesses using [Redemptions 2.0](/docs/dev-portal-mobile/apis/mobile-redemptions-2-0-new-api). allow_guest_to_raise_reactivation: type: boolean x-stoplight: id: rwy483ir9twrx description: Whether or not to allow a user with a deactivated account to request account reactivation directly from the mobile app. The value is set to true if guests are allowed to raise reactivation requests via mobile app and iFrame. Otherwise, the value is set to false. For more information, see [Reactivate User Profile](/docs/dev-portal-mobile/5f81f5f1ee065-reactivate-user-profile). enable_gift_card_purchase: type: boolean x-stoplight: id: 7pxa55dfyipnx description: Determines whether users can purchase a gift card using the business mobile app enable_gift_card_reload: type: boolean x-stoplight: id: 2653t9xtf44mo description: Determines whether users can add to the balance of an existing gift card using the business mobile app enable_gift_card_transfer: type: boolean x-stoplight: id: rcr0s41ktzkln description: Determines whether users can transfer the gift card balance amount (both full and partial) to another user using the business mobile app. enable_gift_card_gifting: type: boolean x-stoplight: id: tt3nj6x4bkc7x description: Determines whether the mobile app should allow users to gift a card to another user enable_gift_card_consolidation: type: boolean x-stoplight: id: 10iefs1fqx3j2 description: Determines whether users can transfer the entire balance of a gift card to another gift card using the business mobile app enable_gift_card_sharing: type: boolean x-stoplight: id: sq16wsc6729v5 description: Determines whether users can share a gift card with another user using the business mobile app create_empty_gift_cards: type: boolean x-stoplight: id: 3z5e2d0h7nao6 description: Determines whether users can create gift cards without any funds loaded onto them initially using the business mobile app show_gift_card_history: type: boolean x-stoplight: id: 2cxbwiefrynmh description: Determines whether the mobile app should show gift card history delete_gift_card_after_consolidation: type: boolean x-stoplight: id: ing457ommrg9t description: Determines whether the mobile app can automatically delete the empty gift card after card consolidation gift_card_default_amounts: $ref: '#/components/schemas/gift-card-default-amounts' preferred_gift_cards: type: array x-stoplight: id: otfzsn65uvwmr description: 'Types of gift cards supported by a business. Mobile apps can use this value to determine the gift cards the business supports. The gift cards supported by a business are configured in the Punchh platform. If no gift card types are configured in the Punchh platform, the array will be empty. Contact your Punchh representative to update this Punchh platform configuration. Possible values: * physical_gift_card: Physical gift cards issued by the business * virtual_gift_card: Digital gift cards issued by the business * physical_comp_card: Physical complimentary cards provided by the business * virtual_comp_card: Digital complimentary cards provided by the business * network_gift_card: Gift cards issued through a network of businesses' items: x-stoplight: id: nm4aklky8cx1h type: string multiple_redemptions_enabled: type: boolean x-stoplight: id: ix7ufqnza22up description: Indicates whether the multiple redemptions feature is enabled for the business. If set to true, the API returns the `multiple_redemptions` object in the response. multiple_redemptions: $ref: '#/components/schemas/multiple-redemptions' cancel_redemption: type: boolean x-stoplight: id: qrp2xkg22q8yk description: Indicates whether the user can revoke (cancel) the generated redemption code from the brand's app ios_guest_account_deactivation: type: boolean x-stoplight: id: v2hx8e1u9ndxw description: Indicates whether a business has enabled account deactivation for its iOS app users android_guest_account_deactivation: type: boolean x-stoplight: id: 27rh6m506kxpq description: Indicates whether a business has enabled account deactivation for its Android app users ios_guest_account_deletion: type: string x-stoplight: id: gr03hhm45pmj9 description: 'Guest account deletion type that a business has configured for its iOS app users. Possible values: none, direct, email' android_guest_account_deletion: type: string x-stoplight: id: 3rojrxcv51ui5 description: 'Guest account deletion type that a business has configured for its Android app users. Possible values: none, direct, email' guest_account_deletion_request_email: type: object x-stoplight: id: ci1ycws1wivl0 description: Specifies the configuration for sending an email notification to the business when a guest requests account deletion. This includes details like the recipient email, subject line, and message body. properties: to: type: string x-stoplight: id: avv881uklhuw4 description: Recipient email address where the account deletion request will be sent 'subject ': type: string x-stoplight: id: pg6klkt0cvdxp description: Subject line of the email. It can include placeholders like {{{program_name}}} that will be dynamically replaced with the actual program name. body: type: string x-stoplight: id: ke7rtjn05oyy1 description: Body of the email message. It can include dynamic placeholders like {{{email}}} for the guest's email and {{{program_name}}} for the loyalty program name. app_feedback_url: type: string x-stoplight: id: mcny5ckhel889 description: URL of the business where users can submit feedback related to the mobile app experience accessibility_url: type: string x-stoplight: id: 2umrzch3lohhc description: URL of the business that provides information or support related to accessibility features enable_advance_auth: type: boolean x-stoplight: id: ebvx17jwjxw6f description: Indicates whether Advanced Authentication is enabled for the business. Returns true if Advanced Authentication is enabled for the business; otherwise, false. program_type: type: string x-stoplight: id: wiphqrzhie1cy description: 'Provides information about the program type configured for the business in the Punchh platform. Possible values: * points_unlock_redeemables - Indicates the program is Points Unlock Redeemables based * points - Indicates program is points convert to rewards or currency * visit - Indicates the program is Visit-based * points_and_visits - Indicates the program is hybrid and includes both points and visits * none - Indicates no loyalty program See [Punchh Offers and Program Types](/docs/dev-portal-developer-resources/150fedd8daa77-punchh-offers-and-program-types#program-types). You must log in to the developer portal to access the topic.' points_conversion_type: type: string x-stoplight: id: rubjr2reovscp description: "Provides information about the conversion type configured for the business\ \ based on the program type selected for the business in the Punchh platform: Possible\ \ values: \n- staged - Applicable when `program_type` is points_unlock_redeemables\ \ or points. The staged value indicates that points are earned normally (check-ins,\ \ purchases, etc.), but when you redeem, the system does not deduct points immediately\ \ at the time of generating a redemption code or [SSF code](/docs/dev-portal-mobile/apis/mobile-api/tag/single-scan-code/post/api2/mobile/single_scan_tokens).\n\ - none - Applicable when `program_type` is points. The none value indicates points\ \ do not get converted into any entity, such as rewards or currency. \n- currency\ \ - Applicable when `program_type` is points. The currency value indicates that\ \ earned points are automatically converted to currency at predefined point thresholds.\n\ - rewards - Applicable when `program_type` is points. The rewards value indicates\ \ that earned points are automatically converted to rewards at predefined point\ \ thresholds.\nSee [Punchh Offers and Program Types](/docs/dev-portal-developer-resources/150fedd8daa77-punchh-offers-and-program-types#program-types).\ \ You must log in to the developer portal to access the topic." guest_lookup_type: type: string x-stoplight: id: f26i84yfecjcm description: An identifier in the mobile app and iFrame used for guest look-up at the POS. If the bar code is configured as the guest’s identity in the Punchh platform for the business, the mobile app and iFrame will only support phone number for guest look-up. Contact your Punchh representative for more information about this Punchh platform configuration. enable_guest_challenge_opt_in: type: boolean x-stoplight: id: jraehwtu9pz58 description: Indicates whether guests can opt in to challenge-based activities. When true, the opt-in button is shown on eligible challenge cards in the mobile app; when false, it is hidden. Contact your Punchh representative to update this configuration setting. enable_guest_challenge_opt_out: type: boolean x-stoplight: id: 0hslc3uxk730q description: Indicates whether guests can opt out of challenge-based activities. When true, the opt-out button is shown on eligible challenge cards in the mobile app; when false, it is hidden. Opt-in must be enabled for challenges in the Punchh platform if Opt-out functionality is required. Contact your Punchh representative to update this configuration setting. If an invalid combination is set (Opt-in disabled while Opt-out enabled), the mobile app hides both buttons. enable_loyalty_identification_at_drive_thru: type: boolean x-stoplight: id: j3apvz3uq7xib description: Indicates whether loyalty users can generate a 4-digit numeric/alphanumeric short code in the mobile app. The short code is used to look up the user’s account and retrieve their balance at the POS. See [Generate a Drive-Thru Short Code](https://developers.partech.com/docs/dev-portal-mobile/647b28e02d630-generate-a-drive-thru-short-code) drive_thru_location_level_strategy: type: boolean x-stoplight: id: dqjhyppyrpp8v description: Indicates whether the drive-thru short code should be generated from the location-level pool. When set to true, the mobile app must send a location_id when requesting a short code. This parameter is always set to true. See [Generate a Drive-Thru Short Code](https://developers.partech.com/docs/dev-portal-mobile/647b28e02d630-generate-a-drive-thru-short-code) enable_drive_thru_pay: type: boolean description: Indicates whether the short code can be used for drive-thru payments when the business supports the single scan flow. When set to true, the loyalty user can pay at the drive-thru using the short code. When set to false, the loyalty user can only earn points or rewards at the drive-thru using the short code, but cannot use it for payment. Contact your Punchh representative to update this Punchh platform configuration. enable_subscription_taxation_support: type: boolean x-stoplight: id: 7tdkirnwtjg67 description: Indicates whether tax handling for subscriptions is enabled. When set to true, the mobile app displays tax-related line items and calculates them accordingly. When set to false, it hides tax line items during subscription check-out. Contact your Punchh representative to update this Punchh platform configuration. enable_pargames_integration: type: boolean description: Indicates whether PAR Games is enabled for the brand. When 'true', the mobile app displays the PAR Games section in the bottom navigation bar or the More menu. When 'false', the section is hidden. Contact your Punchh representative to update this Punchh platform configuration. enable_save_points_for_swag: type: boolean description: 'Indicates whether the "Save Points for Swag" feature is enabled for the business. When ''true'', loyalty users can choose to save loyalty points for merchandise redemption instead of having them automatically converted into rewards or currency. When ''false'' (or not configured), the feature is unavailable and user-level "Save Points for Swag" preferences cannot be configured through the mobile app. Contact your Punchh representative to update this platform configuration. Once enabled, this feature cannot be disabled through the Punchh platform. If changes are required, CSMs must contact the engineering team. ' p2p_authentication_type: type: string x-stoplight: id: p2p-authentication-type description: 'Indicates the authentication type required for peer-to-peer (P2P) loyalty transfers. Possible values: * `none` - No additional authentication is required for P2P transfers. * `email_password_authentication` - The mobile app must prompt the user to enter their existing password before completing a P2P transfer. Contact your Punchh representative to update this Punchh platform configuration.' enable_points_transfer: type: boolean description: Indicates whether the peer-to-peer points transfer feature is enabled for the business. When set to true, users can transfer points to another user via the mobile app. Contact your Punchh representative to update this configuration. enable_currency_transfer: type: boolean description: Indicates whether the peer-to-peer currency transfer feature is enabled for the business. When set to true, users can transfer currency to another user via the mobile app. Contact your Punchh representative to update this configuration. enable_rewards_transfer: type: boolean description: Indicates whether the peer-to-peer rewards transfer feature is enabled for the business. When set to true, users can transfer rewards to another user via the mobile app. Contact your Punchh representative to update this configuration. membership_tier_boost: type: string description: "Indicates the current Membership Tier Boost status for the business.\ \ When enabled, allows business admins to grant members a temporary promotional\ \ tier upgrade through manual gifting, campaigns, or automated triggers. Possible\ \ values: \n* `enabled` - Tier Boost is active and admins can gift promotional tier\ \ status to members.\n* `disabled` - Default. Tier Boost is turned off and all currently\ \ active promotional gifts are revoked immediately upon save.\n* `disabled_keep_active`\ \ - Tier boost is turned off for new gifts but any currently active promotional\ \ gifts will continue until their expiry date).\n" enum: - enabled - disabled - disabled_keep_active enable_passkeys: type: boolean description: Indicates whether passkeys are enabled for the business. If false or absent, mobile/web app must not show any passkey-related UI. If true, mobile/web app may show passkey-related UI and must respect the `login_mode` parameter. Contact your Punchh representative to update this Punchh platform configuration. See [Passkey Authentication Guide](https://developers.partech.com/docs/identity-service/passkey-authentication#passkey-authentication-sign-in) login_mode: type: string enum: - preferred - optional default: preferred description: Controls whether passkey sign-in is presented as the preferred or an optional sign-in method. Only present when `enable_passkeys` is true. Defaults to "preferred" if no explicit mode is configured. Contact your Punchh representative to update this Punchh platform configuration. See [Passkey Authentication Guide](https://developers.partech.com/docs/identity-service/passkey-authentication#passkey-authentication-sign-in) enable_external_idp: type: boolean description: Indicates whether external identity provider (SAML/OIDC) login is enabled for this brand. If false or absent, mobile/web app should not show external IDP sign-in options. Contact your Punchh representative to update this Punchh platform configuration. See [Enterprise IDP Integration](https://developers.partech.com/docs/identity-service/apis/gis/tag/enterprise-idp-integration) gis: type: object description: Guest Identity Service (GIS) authentication configuration for this business. properties: enable_advance_auth: type: boolean description: Indicates whether advanced authentication is enabled. enable_basic_auth: type: boolean description: Indicates whether basic authentication (email and password) is enabled. enable_facebook_login: type: boolean description: Indicates whether Facebook sign-in is enabled. enable_google_login: type: boolean description: Indicates whether Google sign-in is enabled. enable_apple_login: type: boolean description: Indicates whether Apple sign-in is enabled. passkeys_enabled: type: boolean description: Corresponds to the root-level `enable_passkeys` response parameter. Always present, even when false. If this value differs from the root-level `enable_passkeys` response parameter, treat it as the source of truth. external_idp_enabled: type: boolean description: Corresponds to the root-level `enable_external_idp` response parameter. Always present, even when false. If this value differs from the root-level `enable_external_idp` response parameter, treat it as the source of truth. login_mode: type: string enum: - preferred - optional description: Corresponds to the root-level `login_mode` response parameter. Only present when passkeys are enabled. If this value differs from the root-level `login_mode` response parameter, treat it as the source of truth. examples: default: value: android_ga_code: CODE_GOES_HERE android_geocode_api_key: null program_type: points_unlock_redeemables points_conversion_type: staged guest_lookup_type: short_code beacon_uuid: UUID_GOES_HERE content_language: en earning_description: Receive a $10 credit every 100 points. facebook_sharing: true email_verification_enabled: false ios_ga_code: CODE_GOES_HERE ios_geocode_api_key: null marketing_image_url: IMAGE_URL_GOES_HERE marketing_info: Business Blurb to be posted on Facebook marketing_message: I'm earning rewards! marketing_title: Punchh Coffee Roasters uber_client_id: UBER_CLIENT_ID promotional_coupons_enabled: false gift_cards_enabled: false enable_gift_card_auto_reload: true gift_card_auto_reload_threshold: 50 gift_card_auto_reload_default: 50 gift_card_auto_reload_disclaimer: Gift Card Auto-reload disclaimer social_cause_campaigns_enabled: true default_map_search_radius: 100 facebook_signup_incentive_text: Earn 5 Free points gift_card_minimum_transaction_amount: 10 max_gift_card_balance: 350 require_passcode_for_gift_card: false support_email_address: test@example.com faq_url: '' instagram_page_url: INSTAGRAM order_now_url: URL_GOES_HERE order_url_for_sso: URL_GOES_HERE menus_url: MENU_URL privacy_url: '' terms_and_conditions_url: '' nutrition_url: '' catering_url: '' careers_url: '' facebook_page: FACEBOOK_PAGE_URL twitter_handle: '' share_invite_code_message: Use my code {{referral_code}} or click on {{referral_url}} to earn extra points. share_invite_code_title: Use my Invitation Code! share_invite_code_description: null app_disclaimer: Disclaimer about the app and its usage game_disclaimer: Disclaimer about the gaming module available in the app upgrade_disclaimer: Disclaimer about account upgrade in the app challenges_disclaimer: Disclaimer about the challenges module available in app earning_disclaimer: Earn one point for every $1 spent. olo_base_url: URL_GOES_HERE olo_api_key_ios: '1234567890' olo_api_key_android: '1234567890' olo_provider_key: '1234567890' olo_group_order_invite_url: URL_GOES_HERE business_id: 123 business_name: BUSINESS_NAME_GOES_HERE checkin_evidenced_by: barcode guest_identity_code_type: qrcode visits_per_card: 5 card_redemption_value: null migration_allowed: true minimum_visit_amount: 1 minimum_visit_hours: 4 minimum_age_to_signup: 13 misc1: Something useful misc2: '100' misc3: null misc4: '120.90' earning_unit: point currency_earned: 0 points_conversion_threshold: 0 redemption_expiry_minutes: 120 allow_rating_in_feedback: true maximum_rating_in_feedback: 5 checkins_earn: points gift_card_designs: - backgroud_image_url: IMAGE_URL_GOES_HERE card_type: virtual_gift_card name: Design One design_id: 11 - backgroud_image_url: IMAGE_URL_GOES_HERE card_type: physical_gift_card name: Design Two design_id: 12 locations: - address: ADDRESS_GOES_HERE brand: nil city: Ann Arbor country: United States external_store_id: '' latitude: '41.707145' location_id: 310956 loc_email: '' longitude: '-93.582188' name: Ann Arbor online_order_url: '' phone_number: '' post_code: ' 48104' state: Michigan store_number: ' 4' store_tags: Ordering store_times: - day: Mon start_time: nil end_time: nil - day: Tue start_time: nil end_time: nil - day: Wed start_time: nil end_time: nil - day: Thu start_time: nil end_time: nil - day: Fri start_time: nil end_time: nil - day: Sat start_time: nil end_time: nil - day: Sun start_time: nil end_time: nil time_zone: America/New_York updated_at: '2019-10-21T06:19:42-04:00' status: approved franchisee_id: 570 ncr_store_id: '' enable_weekly_redemption_report: false checkin_evidenced_by: image guest_identity_code_type: qrcode alternate_store_number: UK@8907 additional_url: - label: reservation - url: URL_GOES_HERE single_scan_type: single_scan_code hide_in_store_tipping: true hide_in_store_cc_payment: true hide_ssf_gift_card: true multiple_redemption_on_location: true guest_identification_type: restrict_pay_allow_lookup membership_levels: - background_image_url: '' points_multiplier: 1 membership_level_id: 34 name: Level 1 description: · Free Gift 1 (or any entrée of equal or lesser value) maximum_points: 1000 minimum_points: 0 currency_earned: 10 points_conversion_threshold: 1000 - background_image_url: '' points_multiplier: 1 membership_level_id: 35 name: Level 2 description: "· Receive $10 credit for every 1000 points earned\r\n· Unlock birthday\ \ offer\r\n· Unlock local offers" maximum_points: 3500 minimum_points: 1000 currency_earned: 10 points_conversion_threshold: 1000 - background_image_url: '' points_multiplier: 1 membership_level_id: 36 name: Level 3 description: "· Receive $10 credit for every 1000 points earned\r\n· Unlock local\ \ premium offers" maximum_points: 6000 minimum_points: 3500 currency_earned: 10 points_conversion_threshold: 1000 - background_image_url: '' points_multiplier: 1 membership_level_id: 38 name: Level 4 description: "· Receive $10 credit for every 1000 points earned.\r\n· Receive $50\ \ catering credit.\r\n· Each 1000 points earned enters you into a sweepstakes." maximum_points: 999999 minimum_points: 6000 currency_earned: 10 points_conversion_threshold: 1000 redeemables: - redeemable_image_url: IMAGE_URL_GOES_HERE redeemable_properties: null redeemable_id: 744 name: Unlock Redeemable at 100 Points description: This offer is to be given when user completes 100 points. In order to display this on the app, 'Should be available as loyalty points based redemption?' should be set. If this is not set for an offer, it will not be used on the reward screen. points_required_to_redeem: 100 meta_data: Tag1, Tag2, Tag3, Tag4, Tag5 - redeemable_image_url: IMAGE_URL_GOES_HERE redeemable_properties: null redeemable_id: 745 name: Unlock Redeemable at 200 Points description: This is the redeemable that gets unlocked at 200 points. When the redeemable is redeemed, it is actually the redemption of the reward balance itself. points_required_to_redeem: 200 meta_data: Tag1, Tag3, Tag4 games: - game_viral_message: '' name: Scratch N' Match images_on_card: 8 scratch_valid_codes: '' game_type: Scratch n Match requires_code_validation: false game_id: 5 gaming_levels: - extra_punchhs: 10 redeemable_id: null level: 10 Points - extra_punchhs: 20 redeemable_id: null level: 20 Points - extra_punchhs: 25 redeemable_id: null level: 25 Points - extra_punchhs: 30 redeemable_id: null level: 30 Points - extra_punchhs: 35 redeemable_id: null level: 35 Points - extra_punchhs: 40 redeemable_id: null level: 40 Points - extra_punchhs: 45 redeemable_id: null level: 45 Points - extra_punchhs: 50 redeemable_id: null level: 50 Points profile_field_questions: - answer_options: Coffee|Tea|Lemonade data_type: MCMA hint: The Menu Items that a guest likes. mandatory: true question: Beverages I like size: 3 upf: upf0 updatable: true - answer_options: '' data_type: MCMA hint: '' mandatory: false question: Movies I like size: 2 upf: upf1 updatable: true banking_rules: - banked_redeemable_id: '1474' banking_slab: 3000 points_conversion_threshold: 1000 currency_earned: '' - banked_redeemable_id: '1475' banking_slab: 8000 points_conversion_threshold: 2000 currency_earned: '' - banked_redeemable_id: '1476' banking_slab: 16000 points_conversion_threshold: 4000 currency_earned: '' - banked_redeemable_id: '1477' banking_slab: 30000 points_conversion_threshold: 5000 currency_earned: '' base_redeemable: name: Base Redeemable description: Descriptive text about the base redeemable image_url: IMAGE_URL_GOES_HERE redeemable_properties: null meta_data: Tag1, Tag2, Tag3, Tag4, Tag5 payment_credential: adapter_code: par_payment enable_recurring_payments: true enable_passcode_for_payment: true subscriptions: subscription_cancellation_reasons: - component_code: Price cancellation_reason_id: 1 cancellation_reason: It is expensive - component_code: 'Cancel ' cancellation_reason_id: 3 cancellation_reason: Reason - component_code: code cancellation_reason_id: 6 cancellation_reason: reason enable_cancellation_feedback: true cancellation_feedback_placeholder: Enter Additional Feedback If Any payment_disclaimer_text: This is payment disclaimer text. terms_and_conditions: These are terms and conditions. subscription_enabled: true subscriptions_payment_credential: adapter_code: par_payment enable_recurring_payments: false auto_select_strategy: subscription,offer allow_guest_to_raise_reactivation: true enable_gift_card_purchase: true enable_gift_card_reload: true enable_gift_card_transfer: true enable_gift_card_gifting: true enable_gift_card_consolidation: true enable_gift_card_sharing: true create_empty_gift_cards: true show_gift_card_history: true delete_gift_card_after_consolidation: true gift_card_default_amounts: gift_card_purchase_amounts_options: gift_card_purchase_amount_1: 0 gift_card_purchase_amount_2: 0 gift_card_purchase_amount_3: 20 gift_card_purchase_default_option: 20 gift_card_reload_amounts_options: gift_card_reload_amount_1: 3 gift_card_reload_amount_2: 3 gift_card_reload_amount_3: 3 gift_card_reload_default_option: 3 gift_card_auto_reload_amounts_options: gift_card_auto_reload_amount_1: 100 gift_card_auto_reload_amount_2: 2 gift_card_auto_reload_amount_3: 3 gift_card_auto_reload_default_option: 2 balance_threshold_amounts_options: balance_threshold_amount_1: 123 balance_threshold_amount_2: 1 balance_threshold_amount_3: 1 balance_threshold_default_option: 1 preferred_gift_cards: - physical_gift_card multiple_redemptions: exclude_interoperability_strategy_between: - offer|loyalty - loyalty|pre_purchased - promo_coupon|offer - pre_purchased|promo_coupon auto_unlock_duration: 100 discount_processing_strategy: date_of_expiry processing_priority_by_discount_type: - reward allow_multiple_redemption_on_item: true allow_qualifying_items_reused: true auto_redemption: true auto_redemption_discounts: - offer - subscription enable_auto_unlock: true enable_discount_locking: true max_redemptions_in_transaction: 20 processing_priority_by_acquisition_type: - code: offer priority: 1 multiplication_factor: 20 - code: loyalty priority: 2 multiplication_factor: 10 - code: promo_coupon priority: 3 multiplication_factor: 5 - code: pre_purchased priority: 4 multiplication_factor: 4 multiple_redemptions_enabled: true cancel_redemption: true ios_guest_account_deactivation: true android_guest_account_deactivation: true ios_guest_account_deletion: direct android_guest_account_deletion: email guest_account_deletion_request_email: - to: test@example.com - subject: '{{{program_name}}} - Account Deletion' - body: Please delete the account for {{{email}}} in the {{{program_name}}} program. app_feedback_url: URL_GOES_HERE accessibility_url: URL_GOES_HERE enable_advance_auth: true enable_guest_challenge_opt_in: true enable_guest_challenge_opt_out: true enable_loyalty_identification_at_drive_thru: true drive_thru_location_level_strategy: true enable_drive_thru_pay: true enable_subscription_taxation_support: true enable_pargames_integration: true enable_save_points_for_swag: true p2p_authentication_type: email_password_authentication enable_points_transfer: true enable_currency_transfer: false enable_rewards_transfer: false membership_tier_boost: disabled enable_passkeys: true login_mode: preferred enable_external_idp: false gis: enable_advance_auth: true enable_basic_auth: true enable_facebook_login: true enable_google_login: true enable_apple_login: false passkeys_enabled: true external_idp_enabled: false login_mode: preferred '401': description: '' content: application/json: schema: type: object properties: Error: type: object properties: message: type: string code: type: number summary: Program Meta description: 'Provides complete information about a business, including locations, redeemables, program type, related gift cards, etc. >Any update made to the configuration in the Punchh platform will be reflected in the response after 15 minutes, instead of in real time, in order to improve the response time.' operationId: mobile_program_meta_API tags: - Meta & Version parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 2617bed9b0e8e requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business exclude_locations: type: boolean x-stoplight: id: qtb58wgcww1p0 description: Include this parameter in the API call to exclude locations from the API response. Currently, if the exclude_locations parameter is present in the request body, the API will send the locations array as an empty array in the response body regardless of whether the value is true or false. For the API to return the locations for the business in the response body, the exclude_locations parameter must be omitted from the request body. default: true required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE /api2/mobile/version_notes: get: responses: '200': description: '' content: application/json: schema: type: object properties: note: type: object description: Message that can be shown to the user force_upgrade: type: boolean description: Whether to force the user to upgrade to this version or not. If a value of "true" is returned, the user will be forced to not use the app until it is updated to this version. notification_style: type: string enum: - local_notification - popup description: 'Possible values are: - "local_notification" - action taken that can be customized in the app - "popup" - can be displayed as an alert in the app' examples: default: value: note: This is the first version of the app!! force_upgrade: false notification_style: local_notification summary: Version Notes description: Returns the details of a particular version of the app of a business operationId: mobile_version_note tags: - Meta & Version parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/signature' x-stoplight: id: c2b5b5db47e9a requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business version: type: string description: App version os: type: string description: Operating system (either "android" or "ios") model: type: string description: "Model of the device that a user is using \n- iOS - https://cocoapods.org/?q=uidevice-hard\n\ - Android - https://developer.android.com/reference/android/os/Build.html" required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE version: VERSION_GOES_HERE os: ios model: MODEL_GOES_HERE /api2/mobile/verify_token: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} summary: Generate OTP Token description: Generates and mails the verification one-time password (OTP) token used in the secure migration flow. operationId: mobile_generate_otp_token tags: - Migration parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 05a8f4b86f7ab requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE put: responses: '200': description: '' content: application/json: schema: type: object properties: {} summary: Verify OTP Token description: Verifies the one-time password (OTP) token used in the secure migration flow operationId: mobile_verify_token tags: - Migration parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 35cecee8eabcd requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 9uvnpg62r5r3f description: OAuth client ID provided by the business token: type: string x-stoplight: id: sdc5r46bw90zt description: 'One-time password (OTP) token ' verification_mode: type: string x-stoplight: id: ekq3j8wk6nuet description: Can be either email address or phone number required: - client - token - verification_mode examples: default: value: client: CLIENT_GOES_HERE token: OTP_GOES_HERE verification_mode: '1111111111' /api2/mobile/deals/{redeemable_uuid}: get: responses: '200': description: '' content: application/json: schema: type: object properties: redeemable_properties: type: array description: Preperties of the redeemable items: type: string discount_amount: type: integer description: Discount amount for the reedemable discount_channel: type: string enum: - online_only - offline_only - all description: "Channels where the reward can be used. Possible values are:\n- \"online_only\"\ \ for online orders \n- \"offline_only” for POS\n- \"all” for both" expire_redemption_code_with_reward_end_date: type: boolean description: A value of true indicates that the redemption code will expire with the reward end date. id: type: integer description: ID of the deal image: type: string description: Image of the deal points: type: integer description: Value of points required to redeem a particular redeemable redeemable_id: type: integer description: Unique ID that identifies the redeemable in the system redemption_expiry: type: integer description: Expiry of the redemption thumb_image: type: string description: Thumb image of the redeemable meta_data: type: string description: Metadata of the redeemable 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: 861yjqs2hncsw format: date-time description: Activation date and time of the redeemable. A redeemable cannot be active before this date. 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-31T13:04:54-07:00' redeemable_uuid: ID_GOES_HERE start_time: '2019-06-28T13:59:47+05:30' summary: Get Deal Details description: Returns the details of a deal operationId: mobile_get_details_of_the_deal tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: redeemable_uuid required: true description: UUID of the redeemable - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 7840c33ec91ee requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: m2bphfxt3s43w description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE description: '' parameters: - schema: type: string name: redeemable_uuid in: path required: true /api2/mobile/social_causes: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: social_cause_id: type: integer description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform. name: type: string description: Name of a social cause campaign as defined by the business admin while creating the social cause campaign in the Punchh platform description: type: string description: Description of a social cause campaign as defined by the business admin image_url: type: string description: URL of the image that is attached to the social cause campaign by the business admin tags: type: array description: Tags configured in the Punchh platform items: type: object miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform city: type: string description: City state: type: string description: State street: type: string description: Street name zip: type: string description: Zip code phone: type: string description: Phone number email: type: string description: Email address address: type: string description: Address examples: default: value: - social_cause_id: 1 name: Test Campaign description: Test image_url: IMAGE_URL_GOES_HERE tags: [] miscellaneous: '' city: San Mateo state: CA street: ADDRESS_GOES_HERE zip: '94402' phone: '' email: '' address: ADDRESS_GOES_HERE summary: Get Social Cause Campaigns operationId: mobile_get_social_cause_campaigns tags: - Social Cause Campaign description: Returns the list of active social cause campaigns created in a business parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 8b1c5da01c00d requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: wgjca419ij8rv description: OAuth client ID provided by the business query: type: string x-stoplight: id: 77453k6m62txz description: Any field that can be used to search any charity with name, city, state, zip code, address, etc. page: type: string x-stoplight: id: z5bkmsqor2szi description: Returns data based on page number filtering per_page: type: string x-stoplight: id: xbj6o6ndggory description: Returns data based on per-page filtering required: - client - query - page - per_page examples: default: value: client: CLIENT_GOES_HERE query: name page: '' per_page: '' post: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: '0': type: string examples: Donate currency: value: - '0': $2.00 donated to Social Cause Campaign One. Donate reward: value: "[\n \"Sandwich donated to Social Cause Campaign One.\"\n]" Donate card: value: "[\n \"Redeemable Card donated to Social Cause Campaign One.\"\n]" Donate redeemable: value: "[\n \"Dessert! donated to Social Cause Campaign One.\"\n]" '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '404': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - Social Cause Campaign not found. '422': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: Invalid loyalty points: value: errors: - Not enough points to redeem Invalid redeemable ID: value: "{\n \"errors\": [\n \"Redeemable doesn't exist or not configured for loyalty\ \ points based redemption.\"\n ]\n}" Invalid donation type: value: "{\n \"errors\": [\n \"Invalid donation_type! Supported donation types are\ \ card, redeemable, reward, currency.\"\n ]\n}" invalid reward ID: value: "{\n \"errors\": [\n \"Reward doesn't exist or has already been redeemed.\"\ \n ]\n}" summary: Create Donation description: Creates a donation for a user based on the selected social cause campaign operationId: Mobile_Create_donation tags: - Social Cause Campaign parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 69e89aca862e9 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business social_cause_id: type: integer description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform. donation_type: type: string description: "Type of donation that a user wants to make. Currently, Punchh supports\ \ donation of the following objects: \n- currency: For businesses that supports banked\ \ currency \n- reward: Available rewards of a user\n- redeemable: Loyalty redeemables\ \ for a business that supports points unlock redeemables\n- card: Redeemable cards\ \ for visit-based businesses " item_to_donate: type: string description: "Provide the value that corresponds to the donation type: \n1. currency:\ \ Dollar amount that will be donated\n2. reward: ID of the reward that will be donated\ \ \n3. redeemable: ID of the redeemable that will be donated \n4.\ \ card: Pass the string `card` " required: - client - social_cause_id - donation_type - item_to_donate examples: default: value: client: CLIENT_GOES_HERE social_cause_id: '1901' donation_type: currency item_to_donate: 2 /api2/mobile/social_causes/{social_cause_id}: get: responses: '200': description: '' content: application/json: schema: type: object properties: social_cause_id: type: integer description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform. donations: type: object properties: reward: type: object properties: user_donations: type: integer description: Denotes all user donations of the social cause campaign charity_donations: type: integer description: Denotes all charity donations of the social cause campaign all_donations: type: integer description: Denotes all social cause donations for the business currency: type: object properties: user_donations: type: integer description: Denotes all user donations of the social cause campaign charity_donations: type: integer description: Denotes all charity donations of the social cause campaign all_donations: type: integer description: Denotes all social cause donations for the business name: type: string description: Name of the social cause campaign description: type: string description: Description of the social cause campaign image_url: type: string description: URL of the icon image miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform disclaimer: type: string description: Disclaimer of the social cause campaign city: type: string description: City state: type: string description: State street: type: string description: Street name zip: type: string description: Zip code phone_number: type: string description: Phone number email: type: string description: Email address address: type: string description: Address examples: Currency based: value: social_cause_id: 1 donations: reward: user_donations: 0 charity_donations: 0 all_donations: 0 currency: user_donations: 2 charity_donations: 2 all_donations: 2 name: Test Campaign description: Test image_url: IMAGE_URL_GOES_HERE miscellaneous: '' disclaimer: Updated value of charity donations & all donations will be reflected after 24 hours. city: San Mateo state: CA street: ADDRESS_GOES_HERE zip: '94402' phone_number: '' email: '' address: ADDRESS_GOES_HERE Redeemable based: value: "{\n \"donations\": {\n \"reward\": {\n \"user_donations\"\ : 0,\n \"charity_donations\": 0,\n \"all_donations\": 0\n \ \ },\n \"redeemable\": {\n \"user_donations\": 2,\n \ \ \"charity_donations\": 2,\n \"all_donations\": 2\n } \n \ \ },\n \"name\": \"test social for visit based\",\n \"description\": \"test\"\ ,\n \"social_cause_id\": 26882,\n \"image_url\": \"IMAGE_URL_GOES_HERE\"\n}{}" Card based: value: "{\n \"donations\": {\n \"reward\": {\n \"user_donations\"\ : 0,\n \"charity_donations\": 0,\n \"all_donations\": 0\n \ \ },\n \"card\": {\n \"user_donations\": 2,\n \"\ charity_donations\": 2,\n \"all_donations\": 2\n }\n },\n \ \ \"name\": \"test social for visit based\",\n \"description\": \"test\",\n \ \ \"social_cause_id\": 26882,\n \"image_url\": \"IMAGE_URL_GOES_HERE\"\n}" '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '404': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - Social Cause Campaign not found. summary: Social Cause Campaign Details description: Fetches donation details for a user based on the selected social cause campaign operationId: mobile_social_cause_campaign_details tags: - Social Cause Campaign parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/punchh-app-device-id' - schema: type: integer in: path name: social_cause_id required: true description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform. - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f7d4ac46778ae requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: i90qggqzh3qbq description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: social_cause_id in: path required: true /api2/mobile/invitations: get: summary: Get Invitations description: Returns the list of pending invitations of a user operationId: mobile_get_invitations tags: - Invitations parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: invitation_id: type: integer description: Unique ID of the invitation assigned by Punchh invitation_type: type: string description: Type of the invitation for gift card transfer. Invitation types can be "email", "phone", or "claim_token". invitation_date: type: string description: Date/time when the invitation was created enum: - YYYY-MM-DDThh:mm:ssZ format: date-time status: type: string description: Status of the invitation. The status can be "pending" or "cancelled". amount: type: integer description: Amount of the gift card for which the invitation is created gift_card: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: - invitation_id: 221 invitation_type: claim_token invitation_date: '2017-03-29T23:48:00+05:30' status: pending amount: 25 gift_card: card_background_image: IMAGE_URL_GOES_HERE design_id: 4 name: My First Card preferred: false usb_scannable_card_number: CARD_NUMBER_GOES_HERE users: - state: owner email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE avatar_remote_url: null fb_uid: FB_UID_GOES_HERE user_id: 111111111 gift_card_id: ID_GOES_HERE card_number: CARD_NUMBER_GOES_HERE created_at: '2016-12-08T20:18:41+05:30' epin: EPIN_GOES_HERE last_fetched_amount: 25 last_fetched_at: '2016-12-20T01:00:19+05:30' status: active updated_at: '2016-12-20T01:00:19+05:30' uuid: ID_GOES_HERE x-stoplight: id: eb521de5ed65f requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: y3t01icl1hr46 description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE description: '' post: responses: '200': description: '' content: application/json: schema: type: object properties: invitation_id: type: integer description: Unique ID of the invitation assigned by Punchh invitation_type: type: string description: Type of the invitation for gift card transfer. Invitation types can be "email", "phone", or "claim_token". invitation_date: type: string description: Date/time when the invitation was created enum: - YYYY-MM-DDThh:mm:ssZ format: date-time claim_token: type: string description: Claim token for the gift card that has to be transferred. This is generated by Punchh. status: type: string description: Status of the invitation. The status can be "pending" or "cancelled". amount: type: integer description: Amount of the gift card for which the invitation is created gift_card: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: invitation_id: 222 invitation_type: claim_token invitation_date: '2017-03-30T00:08:49+05:30' claim_token: TOKEN_GOES_HERE status: pending amount: 25 gift_card: card_background_image: IMAGE_URL_GOES_HERE design_id: 4 name: My first card preferred: false usb_scannable_card_number: CARD_NUMBER_GOES_HERE users: - state: owner email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE avatar_remote_url: null fb_uid: FB_UID_GOES_HERE user_id: 111111111 gift_card_id: ID_GOES_HERE card_number: CARD_NUMBER_GOES_HERE created_at: '2016-12-08T20:18:41+05:30' epin: EPIN_GOES_HERE last_fetched_amount: 25 last_fetched_at: '2016-12-20T01:00:19+05:30' status: active updated_at: '2016-12-20T01:00:19+05:30' uuid: ID_GOES_HERE summary: Create Gift Card Claim Token operationId: Mobile_Create_Gift_Card_Claim_Token tags: - Invitations description: Creates a claim token for a gift card that has to be transferred parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' x-stoplight: id: 38631116dcddd requestBody: content: application/json: schema: type: object properties: uuid: type: string description: UUID of the gift card for which the claim token needs to be created client: type: string x-stoplight: id: 76dopnrcgo5tt description: OAuth client ID provided by the business required: - uuid - client examples: default: value: uuid: ID_GOES_HERE client: CLIENT_GOES_HERE description: '' /api2/mobile/invitations/check_status: get: responses: '200': description: '' content: text/plain: examples: default: value: - This is a valid claim token and can be used in the app to claim the associated Gift Card. '400': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - This is a invalid/cancelled/used claim token summary: Check Status of the Claim Token description: Returns the status of a claim token to determine if the claim token is valid operationId: mobile_Check_Status_of_the_claim_token tags: - Invitations parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: d335302f42dc6 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 5etxbz9m5021r description: OAuth client ID provided by the business claim_token: type: string x-stoplight: id: fv8goz65r2zmn description: The claim token generated by the [Create Gift Card Claim Token](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1invitations/post) API required: - client - claim_token description: '' /api2/mobile/invitations/{id}: delete: responses: '200': description: '' content: text/plain: examples: default: value: "[\n \"Invitation to use this gift card has been successfully cancelled.\"\n\ ]" '422': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - Invitation to use this gift card can't be cancelled. summary: Delete an Invitation Claim Token description: Deletes the invitation ID and corresponding claim token to transfer a gift card operationId: Mobile_delete_an_invitation_claim_token tags: - Invitations parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - schema: type: string in: path name: id required: true description: 'Invitation ID that will be deleted ' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: eb9967812969f requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: jjh64onw64ath description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: id in: path required: true /api2/mobile/invitations/transfer: patch: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE design_id: 4 name: null preferred: false usb_scannable_card_number: CARD_NUMBER_GOES_HERE users: - state: owner email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE avatar_remote_url: null fb_uid: null user_id: 111111111 gift_card_id: ID_GOES_HERE card_number: CARD_NUMBER_GOES_HERE created_at: '2016-12-08T20:18:41+05:30' epin: EPIN_GOES_HERE last_fetched_amount: 25 last_fetched_at: '2016-12-20T01:00:19+05:30' status: active updated_at: '2016-12-20T01:00:19+05:30' uuid: ID_GOES_HERE '422': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: string examples: default: value: errors: - This gift card can't be transferred, Please contact support summary: Transfer a Gift Card Using Invitation Claim Token description: Transfers a gift card to a user using the corresponding claim token operationId: mobile_transfer_a_gift_card_using_invitation_claim_token tags: - Invitations parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 8ca4a75f4019b requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: ofimr4m4m3nep description: OAuth client ID provided by the business claim_token: type: string x-stoplight: id: hta6rt379xt9m description: The claim token generated by the [Create Gift Card Claim Token](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1invitations/post) API required: - client - claim_token examples: default: value: client: CLIENT_GOES_HERE claim_token: CLAIM_TOKEN_GOES_HERE /api2/mobile/passcodes/forgot_passcode: post: responses: '200': description: '' content: text/plain: examples: default: value: "[\n \"An email has been sent to your registered email address to reset your\ \ Passcode.\"\n]" summary: Forgot Passcode description: Sends an email to a user with a reset passcode link when the user taps the reset passcode button in the app of a business operationId: mobile_forgot_passcode tags: - Passcodes parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 7232d383da18c requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/passcodes: post: responses: '200': description: '' content: text/plain: examples: default: value: "[\n \"Passcode has been successfully created.\"\n]" summary: Create Passcode description: Creates a passcode for a user operationId: mobile_create_passcode tags: - Passcodes parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 082fbac988b5c requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: wrtzmt49f077a description: OAuth client ID provided by the business passcode: type: string x-stoplight: id: pama3knz7sbb0 description: Passcode to be set for the user default: 1234 required: - client - passcode examples: default: value: client: CLIENT_GOES_HERE passcode: '1234' /api2/mobile/coupons: post: responses: '200': description: '' content: application/json: schema: type: object properties: code: type: array items: type: string examples: default: value: code: - Congratulations, Promo Code Applied Successfully. '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: Bad Request (invalid language): value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. Bad Request (missing parameter): value: "{\n \"errors\": {\n \"code\": \"Required parameter missing or the\ \ value is empty.\"\n }\n}" Bad Request (missing email fields): value: "{ \n \"errors\":{ \n \"missing_required_param\":[ \n \"Required\ \ parameter missing or the value is empty: email\"\n ]\n }\n}" '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: Invalid client ID: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_email_password: type: array items: type: string examples: Invalid email or password: value: errors: invalid_email_password: - Sorry, Invalid Email/Password. summary: Apply Coupons description: Applies a coupon or promo code from the mobile app to gift a user the associated reward. The response from this API endpoint does not return the associated reward; however, you can use the [User Account History](/docs/dev-portal-mobile/b3A6NDQ5NTQ4MTY-user-account-history) API to view the reward gifted to the user. operationId: mobile_apply_coupons tags: - Coupons parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: dd3f9900f0b5b requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business code: type: string description: Coupon or promo code required: - client - code examples: default: value: client: CLIENT_GOES_HERE code: ABCD123 /api2/mobile/challenges: get: responses: '200': description: '' content: application/json: schema: type: object properties: challenges: type: array items: type: object properties: gift_reason: type: string description: Reason to give gifts to a user id: type: integer description: Challenge ID icon: type: string description: Image icon of the challenge icon_completed: type: string description: Image icon that represents completion of the challenge name: type: string description: Name of the challenge. The name is returned in the language specified in the Accept-Language request header, provided the challenge name has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language. start_date: type: string enum: - YYYY-MM-DD format: date description: Start date of the campaign end_date: type: string enum: - YYYY-MM-DD format: date description: End date of the campaign image_url: type: string description: URL of the image description: type: string description: Description of the challenge. The description is returned in the language specified in the Accept-Language request header, provided the challenge description has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the description is returned in French if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language. tasks: type: array description: Information about the name and steps involved items: type: object properties: name: type: string number_of_steps: type: integer miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform challenge_reach: type: string x-nullable: true description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are: - universal_auto_enrolment - segment_auto_enrolment - null (when no reach strategy is defined)' challenge_type: type: string description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are: - receipt_qualification - every_x_points - segment' occurrence: type: string description: 'Possibel values are: - **single** - Shows when restarting the challenge button is OFF in the campaign - **multiple** - Shows when restarting the challenge button is ON in the campaign' examples: default: value: challenges: - gift_reason: Punchh product qa test currency id: 124872 icon: IMAGE_URL_GOES_HERE icon_completed: IMAGE_URL_GOES_HERE name: Punchh product qa test currency start_date: null end_date: null image_url: IMAGE_URL_GOES_HERE description: '' tasks: - name: Punchh product qa test currency number_of_steps: 10 miscellaneous: '' challenge_reach: segment_auto_enrolment challenge_type: every_x_points occurrence: single - gift_reason: Punchh product qa test redeemable id: 124873 icon: IMAGE_URL_GOES_HERE icon_completed: IMAGE_URL_GOES_HERE name: Punchh product qa test redeemable start_date: null end_date: null image_url: IMAGE_URL_GOES_HERE description: '' tasks: - name: Punchh product qa test redeemable number_of_steps: 1 miscellaneous: '' challenge_reach: null challenge_type: segment occurrence: single - gift_reason: Buy 5 Cheese Breadsticks id: 124875 icon: IMAGE_URL_GOES_HERE icon_completed: IMAGE_URL_GOES_HERE name: Buy 5 Cheese Breadsticks start_date: '2020-11-30' end_date: '2021-03-31' image_url: IMAGE_URL_GOES_HERE description: Buy 5 Cheese Breadsticks tasks: - name: Buy 5 Cheese Breadsticks number_of_steps: 5 miscellaneous: '{"detailedDescription":"Earn 50 bonus points after you purchase five breadsticks. Your points will automatically be added to your account after completion. Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"fuel", "GiftPoints":"0.55", "challengeType":"Personal", "nounDescription" : "fuel"}' challenge_reach: segment_auto_enrolment challenge_type: receipt_qualification occurrence: single - gift_reason: Get your 4th Breadstick free id: 124876 icon: IMAGE_URL_GOES_HERE icon_completed: IMAGE_URL_GOES_HERE name: Buy 4 Breadsticks! start_date: '2020-11-30' end_date: '2021-02-10' image_url: IMAGE_URL_GOES_HERE description: Get your 4th Breadstick free tasks: - name: Buy 4 Breadsticks! number_of_steps: 3 miscellaneous: '{"detailedDescription":"Get your next cheese breadstick free after you purchase three breadsticks. . Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"offer", "GiftPoints":"50% off , Breadstick", "challengeType":"Personal","nounDescription" : "breadsticks"}' challenge_reach: segment_auto_enrolment challenge_type: receipt_qualification occurrence: multiple '401': description: Unauthorized content: application/json: schema: type: object properties: unauthorized: type: array items: type: string examples: Invalid or missing access token: value: unauthorized: - An active access token must be used to query information about the current user. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: object properties: disabled_feature: type: string examples: Challenges not enabled: value: errors: disabled_feature: Business does not have challenges enabled. summary: List Challenges description: 'Lists challenges available for a business. The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration. ' operationId: mobile_list_challenges tags: - Challenges parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - schema: type: string in: header name: Accept-Language description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese
The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address. Click the Alternate Languages drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under Marketing Automation > Campaign Management.' x-stoplight: id: 26fb9c55960f8 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: ng9tn0hdkmtqy description: OAuth client ID provided by the business required: - client /api2/mobile/challenges/{id}: get: responses: '200': description: '' content: application/json: schema: type: object properties: progress: type: array items: type: object properties: completed_steps: type: integer description: Number of steps a user has completed for a challenge total_steps: type: integer description: Number of total steps set for a challenge name: type: string description: Name of the challenge. The name is returned in the language specified in the Accept-Language request header, provided the challenge name has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language. description: type: string description: Description of the challenge. The description is returned in the language specified in the Accept-Language request header, provided the challenge description has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the description is returned in French if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language. image_url: type: string description: URL of the main banner image associated with the challenge campaign icon_url: type: string description: URL of the default icon image for the challenge icon_completed_url: type: string description: URL of the image icon that represents completion of the challenge start_date: type: string enum: - YYYY-MM-DD format: date description: Start date end_date: type: string enum: - YYYY-MM-DD format: date description: End date gift_reason: type: string description: Reason to give gifts to a user miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform challenge_id: type: integer description: Challenge ID challenge_reach: type: string x-nullable: true description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are: - universal_auto_enrolment - segment_auto_enrolment - null (when no reach strategy is defined)' challenge_status: type: string x-nullable: true description: 'Returns the details of availability of and enrollment of a guest into a specific challenge. Possible values are: * unavailable: This status will be returned for "segment_auto_enrolment" when a guest is NOT added to the "user_feature_enrolment" table. * enrolled: This status will be returned for:
a) "universal_auto_enrolment" in all cases since all signed-up guests are automatically enrolled for the challenge.
b) "segment_auto_enrolment" in cases when guests from the attached segment (to the challenge campaign) get added to the user_feature_enrolment table and are automatically enrolled for the challenge.
* null: For older default "Segment" type challenges, the status will always be null.' challenge_type: type: string description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are: - receipt_qualification - every_x_points - segment' occurrence: type: string description: 'Possible values are: - **single** - Shows when restarting the challenge button is OFF in the campaign - **multiple** - Shows when restarting the challenge button is ON in the campaign' past_completions: type: integer description: The number of times the user has previously completed the challenge campaign. enrollment_status: type: string x-stoplight: id: rllwa7oi3kkzk description: 'Indicates the user''s enrollment status in a challenge. Possible values: * active - The user is currently enrolled in the challenge. * expired - The user''s enrollment in the challenge has expired.' enrolled_on: type: string x-stoplight: id: cjcebn39q1977 format: date-time description: Date and time (in ISO 8601 format) when the user enrolled in the challenge enrollment_expires: type: string x-stoplight: id: 69ktllcf2cv1a description: Date and time (in ISO 8601 format) when the user's enrollment in the challenge expires format: date-time opted_in: type: boolean x-stoplight: id: pilkx64h3cv1y description: "Indicates whether the user has opted in to a challenge. Possible values:\n\ * true - The user has opted in. The mobile app should show the opt-out button on\ \ the challenge card if the opt-out feature is enabled for the business in the Punchh\ \ platform. \n* false - The user has not opted in. The mobile app should show the\ \ opt-in button on the challenge card if the opt-in feature is enabled for the business\ \ in the Punchh platform.\nContact your Punchh representative to update this configuration\ \ setting." examples: default: value: progress: - completed_steps: 0 total_steps: 15 name: Potato Cheese Bites Club description: Buy 10 get 1 free image_url: IMAGE_URL_GOES_HERE icon_url: IMAGE_URL_GOES_HERE icon_completed_url: IMAGE_URL_GOES_HERE start_date: '2019-06-24' end_date: '2022-12-31' gift_reason: New Challenge miscellaneous: '{"detailedDescription": "Welcome to Potato Cheese ites club - Buy 10 get 1 free", "challengeType":"Clubs","nounDescription" : "Potato Cheese Bites"}' challenge_reach: universal_auto_enrolment challenge_status: enrolled challenge_type: receipt_qualification occurrence: multiple past_completions: 0 challenge_id: 34 enrollment_status: active enrolled_on: '2025-01-10T05:00:00+05:30' enrollment_expires: '2025-04-10T05:00:00+05:30' opted_in: true '401': description: Unauthorized content: application/json: schema: type: object properties: unauthorized: type: array items: type: string examples: Invalid or missing access token: value: unauthorized: - An active access token must be used to query information about the current user. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: object properties: disabled_feature: type: string examples: Challenges not enabled: value: errors: disabled_feature: Business does not have challenges enabled. summary: Fetch Challenge Details description: Lists specific challenge details available for a business. The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration. operationId: mobile_Fetch_challenge_details tags: - Challenges parameters: - $ref: '#/components/parameters/signature' - schema: type: integer in: path name: id required: true description: Challenge ID - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - schema: type: string in: header name: Accept-Language description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese
The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address. Click the Alternate Languages drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under Marketing Automation > Campaign Management.' - $ref: '#/components/parameters/Authorization' x-stoplight: id: 71d1550be0f48 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: vw31qt20pos98 description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE parameters: - schema: type: string name: id in: path required: true /api2/mobile/users/challenges_listing: get: summary: List User Challenges operationId: mobile_list_user_challenges description: 'Returns all challenges associated with the logged-in user. Challenges are grouped into Available, Active, and Past categories, and include user-specific details such as enrollment status, progress, and relevant metadata required to render the challenges listing screen. This API supports pagination for efficient data handling. **Prerequisite**
The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration. **Challenge Categories** **Available Challenges:** All challenges available for opt-in when the opt-in feature is enabled. When the opt-in feature is disabled, all challenges are returned in the Active category. **Active Challenges:** All active challenges that the user has opted into, along with all challenges that do not require opt-in. When the opt-in feature is disabled, all challenges appear in this category. Note: All segment-based challenges are also included in this category. **Past Challenges:** All challenges whose end date has already passed, deactivated challenges, as well as challenges for which the user has already earned a badge.' tags: - Challenges parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - schema: type: string in: header name: Accept-Language description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese
The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address. Click the Alternate Languages drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under Marketing Automation > Campaign Management.' responses: '200': description: OK content: application/json: schema: type: object properties: count: type: object description: Object containing the count of challenges for the selected filter category. For example, if `filter`= active, the `count` object returns the count of active challenges. If no filter is specified, the counts for all challenge categories (`active_challenges`, `available_challenges`, `past_challenges`) are returned. properties: active_challenges: type: integer description: Total number of active challenges for the user. Returned when filter is "active" or when no filter is specified. The number of active challenges returned is determined by the per_page value. available_challenges: type: integer description: Total number of available challenges for the user. Returned when filter is "available" or when no filter is specified. The number of available challenges returned is determined by the per_page value. past_challenges: type: integer description: Total number of past challenges for the user. Returned when filter is "past" or when no filter is specified. The number of past challenges returned is determined by the per_page value. available_challenges: type: array description: All challenges available for opt-in when the opt-in feature is enabled. When the opt-in feature is disabled, this array is empty as all challenges are returned in the active_challenges array. items: $ref: '#/components/schemas/ChallengeListingItem' active_challenges: type: array description: 'All active challenges that the user has opted into, along with all challenges that do not require opt-in. When the opt-in feature is disabled, all challenges appear in this array. Note: All segment-based challenges are also included in this array.' items: $ref: '#/components/schemas/ChallengeListingItem' past_challenges: type: array description: All challenges whose end date has already passed, as well as non-global challenges for which the user has already earned a badge. items: $ref: '#/components/schemas/ChallengeListingItem' examples: Response Example: value: count: active_challenges: 12 available_challenges: [] active_challenges: - challenge_id: 16438 name: Buy 5 Cheese Breadsticks description: Buy 5 Cheese Breadsticks to earn bonus points image_url: IMAGE_URL_GOES_HERE icon_url: IMAGE_URL_GOES_HERE icon_completed_url: IMAGE_URL_GOES_HERE start_date: '2025-01-01' end_date: '2025-12-31' challenge_starting_at_tz: '2025-01-01T00:00:00+05:30' challenge_expiring_at_tz: '2025-12-31T23:59:59+05:30' challenge_reach: universal_auto_enrolment challenge_status: enrolled challenge_type: receipt_qualification occurrence: single past_completions: 1 opted_in: true opted_out: false explicit_opt_in: true gift_reason: Buy 5 Cheese Breadsticks miscellaneous: '{"detailedDescription":"Earn 50 bonus points after you purchase five breadsticks."}' progress: - completed_steps: 0 total_steps: 1 past_challenges: [] '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: filter: type: string examples: Invalid filter value: value: errors: filter: 'Invalid filter value. Valid values are: active, available, past' '401': description: Unauthorized content: application/json: schema: type: object properties: unauthorized: type: array items: type: string examples: Invalid or missing access token: value: unauthorized: - An active access token must be used to query information about the current user. '412': description: Precondition Failed content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: Invalid Signature: value: errors: invalid_signature: - Signature doesn't match. For information about generating the x-pch-digest header, see https://developers.punchh.com. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: object properties: disabled_feature: type: string examples: Challenges not enabled: value: errors: disabled_feature: Business does not have challenges enabled. x-stoplight: id: challenges-listing-get requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business page: type: integer description: Page number for pagination per_page: type: integer description: Number of challenges to return per page filter: type: string description: 'Filters the response to return only challenges of a specific category. Possible values are: - available: Returns only available challenges - active: Returns only active challenges - past: Returns only past challenges If not provided, all categories are returned.' enum: - available - active - past required: - client examples: default: value: client: CLIENT_GOES_HERE page: 1 per_page: 10 filter: active /api2/mobile/survey_details: get: responses: '200': description: '' content: application/json: schema: type: object properties: id: type: integer description: Unique ID of the survey survey_url: type: string description: URL of the survey sent to a user examples: default: value: id: 123456 survey_url: URL_GOES_HERE '422': description: '' content: application/json: schema: type: array items: type: string text/plain: examples: default: value: "[\n \"Can't find any survey associated with this user.\"\n]" description: Returns the URL of a user's available survey summary: Fetch User Survey operationId: mobile_fetch_user_survey tags: - Surveys parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - schema: type: string default: Etc/UTC in: header name: Accept-Timezone - $ref: '#/components/parameters/User-Agent' x-stoplight: id: afeef44b8e644 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business user_survey_id: type: integer description: ID of the survey required: - client - user_survey_id examples: default: value: client: CLIENT_GOES_HERE user_survey_id: 123456 /api2/mobile/secure_tokens/{service}: get: responses: '200': description: '' content: application/json: schema: type: object properties: token: type: string description: A user-based token that can be used for different services, such as gift cards, online ordering, etc. examples: default: value: token: TOKEN_GOES_HERE summary: Fetch Client Token description: 'Returns a secure client token that can be used for different services, such as gift cards, online ordering, etc. ' operationId: mobile_fetch_client_token tags: - Payments parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: service required: true description: The service for which the secure token will be generated (e.g., ordering, braintree) - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f51140e63501c requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: service in: path required: true /api2/mobile/gift_cards/purchase: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: false name: null last_fetched_amount: 10 last_fetched_at: '2016-05-12T03:54:45-06:00' status: active updated_at: '2016-05-12T03:54:45-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE summary: Purchase Gift Card description: Enables a user to purchase a gift card using the app of a business operationId: mobile_purchase_gift_card tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 79eab19c99597 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business design_id: type: string description: ID of a particular gift card design selected by the user while purchasing a gift card amount: type: string description: Amount with which the user wants to purchase a gift card. The minimum value can be configured in the Punchh platform. payment_type: type: string description: This parameter is required when a user makes a payment via saved cards. Send "recurring" as the value of this parameter. transaction_token: type: string description: Unique digital identifier/token of the user's payment card, or the UUID of the saved payment card if the value of `payment_type` is "recurring". The transaction token is issued by a payment processor used by a business. cardholder_name: type: string description: Name of the person who owns the payment card used to purchase a gift card. Not needed for Apple Pay / Android Wallet exp_date: type: string description: Expiration date of the payment card used by the user. Not needed for Apple Pay / Android Wallet type: type: string description: Type of payment card used by the user (e.g., Visa, Mastercard, etc.). Not needed for Apple Pay / Android Wallet postal_code: type: string description: Zip code as specified by the cardholder in the billing address examples: Purchase gift card via credit card: value: client: CLIENT_GOES_HERE design_id: 13 amount: '10' transaction_token: TOKEN_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 419 type: VISA postal_code: 10004 'Purchase gift card via saved payment card ': value: client: CLIENT_GOES_HERE design_id: 13 amount: '10' payment_type: recurring transaction_token: SAVED_CARD_UUID_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 419 type: VISA postal_code: 10004 /api2/mobile/gift_cards/{uuid}/reload: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: false name: My first card last_fetched_amount: 42 last_fetched_at: '2016-05-12T04:44:01-06:00' status: active type: null updated_at: '2016-05-12T04:44:01-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE summary: Reload Gift Card description: Enables a user to add to the balance of an existing gift card using the app of a business operationId: mobile_reload_gift_card tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card issued by and maintained in the Punchh system - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: b1ac0c8bdfd2e requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business amount: type: string description: Amount with which the user wants to purchase a gift card. The minimum value can be configured in the Punchh platform. payment_type: type: string description: This parameter is required when a user makes a payment via saved cards. Send "recurring" as the value of this parameter. transaction_token: type: string description: Unique digital identifier/token of the user's payment card, or the UUID of the saved payment card if the value of `payment_type` is "recurring". The transaction token is issued by a payment processor used by a business. cardholder_name: type: string description: Name of the person who owns the payment card used to purchase a gift card. Not needed for Apple Pay / Android Wallet exp_date: type: string description: Expiration date of the payment card used by the user. Not needed for Apple Pay / Android Wallet type: type: string description: Type payment card used by the user (e.g., Visa, Mastercard, etc.). Not needed for Apple Pay / Android Wallet postal_code: type: string description: Zip code as specified by the cardholder in the billing address examples: Reload a gift card via credit card: value: client: CLIENT_GOES_HERE design_id: 13 amount: '10' transaction_token: TOKEN_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 419 type: Mastercard postal_code: 10004 Reload a gift card via saved payment card: value: client: CLIENT_GOES_HERE design_id: 13 amount: '10' payment_type: recurring transaction_token: SAVED_CARD_UUID_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 419 type: VISA postal_code: 10004 parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: false name: My first card last_fetched_amount: 42 last_fetched_at: '2016-05-12T04:44:01-06:00' status: active type: null updated_at: '2016-05-12T04:44:01-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE summary: Import Physical Gift Card description: Imports a user's physical gift card into the app. The physical gift card is added to the Punchh system. operationId: mobile_import_physical_gift_card tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 074d603d4be19 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business design_id: type: string description: 'ID of a particular gift card design selected by the user while purchasing a gift card ' card_number: type: string description: Card number of the physical gift card epin: type: string description: Security PIN associated with the gift card name: type: string description: Name assigned to the gift card by a user examples: default: value: client: CLIENT_GOES_HERE design_id: 1 card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE name: My first card /api2/mobile/gift_cards/{uuid}: put: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE design_id: 1 preferred: true name: My first card usb_scannable_card_number: CARD_NUMBER_GOES_HERE users: - state: owner email: test@example.com first_name: null last_name: null avatar_remote_url: null fb_uid: null user_id: 111111111 card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE created_at: '2016-06-13T12:42:21-07:00' last_fetched_amount: 0 last_fetched_at: '2016-06-13T12:42:21-07:00' status: active updated_at: '2016-06-13T12:42:21-07:00' uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array x-stoplight: id: v6xbmnaj8c2gc items: x-stoplight: id: ybpdyzfk0hkg0 type: string examples: example: value: errors: - You should be the owner of this card to perform this action. summary: Update Gift Card description: Enables a gift card owner to update the name, design, and preference of a gift card operationId: mobile_udpate_gift_card tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card issued by and maintained in the Punchh system. - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 5a6da59e09732 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business design_id: type: integer description: 'ID of a particular gift card design selected by the gift card owner while purchasing a gift card Note: As Punchh no longer supports updating the design ID of the gift card via the Update Gift Card API, the parameter is marked deprecated. It will be removed from the request body of the API topic.' x-deprecated: true name: type: string description: Name assigned to a gift card by the gift card owner preferred: type: boolean description: A "true" value for a gift card indicates that the gift card owner has selected it to be the preferred gift card for payment. auto_reload_enabled: type: boolean description: Whether auto-reload is enabled for a gift card or not threshold_amount: type: number format: float description: Threshold amount below which a gift card would be eligible for auto-reload default_amount: type: number format: float description: Default amount with which a gift card would be auto-reloaded payment_card_id: type: string description: UUID of a payment card examples: default: value: client: CLIENT_GOES_HERE name: My first card preferred: true auto_reload_enabled: true threshold_amount: 50 default_amount: 50 payment_card_id: PAYMENT_CARD_UUID_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true delete: responses: '200': description: '' content: application/json: schema: type: object properties: {} examples: default: value: "{ \n \"Gift Card successfully deleted.\"\n}" summary: Delete Gift Card description: 'Removes a gift card from a user''s app so that it will not be returned in API responses under the gift card list for a user, but does not delete it from the Punchh system Note: It will be visible under the user profile in the Punchh platform as "card removed". To delete it from an existing user account in order to add it again for the same user or another user, please file a support ticket.' operationId: mobile_delete_gift_card tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: 'Unique ID of the gift card issued by and maintained in the Punchh system ' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 18c84ea58fbd5 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/gift_cards/: get: responses: '200': description: '' content: application/json: schema: type: array items: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: - card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: true name: My first card last_fetched_amount: 42 last_fetched_at: '2016-05-12T04:44:01-06:00' status: active type: null updated_at: '2016-05-12T04:44:01-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE - card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-13T06:15:44-06:00' design_id: 1 preferred: false name: My second card last_fetched_amount: 50 last_fetched_at: '2016-05-13T06:15:45-06:00' status: active type: null updated_at: '2016-05-13T06:15:46-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: shared - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE summary: Fetch Gift Cards description: Returns all of the active gift cards of a user operationId: mobile_fetch_gift_cards tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f72dcf064d8e5 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business passcode: type: string description: Passcode is a secondary authentication PIN that must be passed if it is enabled for a business. It can be turned on/off from the Punchh platform. required: - client - passcode examples: default: value: client: CLIENT_GOES_HERE passcode: '123456' /api2/mobile/gift_cards/{uuid}/balance: get: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: false name: My first card last_fetched_amount: 42 last_fetched_at: '2016-05-12T05:03:23-06:00' status: active type: null updated_at: '2016-05-12T05:03:23-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner user_card_id: ID_GOES_HERE uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE auto_reload_enabled: true gc_user_auto_reload_threshold_amount: 50 gc_user_auto_reload_default_amount: 50 gc_user_auto_reload_preferred_payment: PAYMENT_CARD_UUID_GOES_HERE summary: Fetch Gift Card Balance description: Returns the details of a specified gift card operationId: mobile_fetch_gift_card_balance tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: 'Unique ID of the gift card issued by and maintained in the Punchh system ' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 2be7804e627a0 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards/{uuid}/history: 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 transaction happened, in ISO 8601 format event: type: string description: Title of the transaction event displayed in the app. This respects the locale, so the value of this may change with the requested locale. description: type: string description: Additional information about the transaction event. A 'null' value indicates that no additional details are available. amount: type: number format: float description: 'Amount involved in the transaction ' balance: type: number format: float description: Updated balance of the gift card after the transaction event_type: type: string description: "Fixed value of the transaction event that indicates the type of gift\ \ card transaction. Logic in the app can be applied based on the values returned\ \ in this parameter. For example, color coding in the transaction history can\ \ be based on this. Values returned are:\n- reloaded \n- card_added \n- transferred\ \ \n- redeemed" examples: default: value: - date: '2016-05-12T03:54:45-06:00' event: Reloaded description: null amount: $10.00 balance: $10.00 event_type: reloaded - date: '2016-05-12T04:43:12-06:00' event: Reloaded description: null amount: $15.00 balance: $25.00 event_type: reloaded - date: '2016-05-12T04:44:01-06:00' event: Reloaded description: null amount: $17.00 balance: $42.00 event_type: reloaded summary: Fetch Gift Card Transaction History description: Returns the transaction history of a specified gift card operationId: mobile_fetch_gift_card_transaction_history tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: uuid required: true description: 'Unique ID of the gift card issued by and maintained in the Punchh system ' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: a7c0fda10d070 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards/{uuid}/transfer: post: responses: '200': description: '' content: text/plain: examples: default: value: "[\n \"Your transfer of $13.00 to is bound to come back to you tenfold.\ \ It’s the burrito karma, Amigo!\"\n]" summary: Transfer Gift Card or Balance description: Transfers an entire gift card or partial amount from one user to another user operationId: mobile_transfer_gift_card_or_balance tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card issued by and maintained in the Punchh system - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 5019de3af9ae9 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business recipient_email: type: string description: Email address of the user to whom the balance / gift card is being transferred. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_phone: type: integer format: int32 description: Phone number of the user to whom the balance / gift card is being transferred. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_fb_uid: type: string description: Facebook "uid" of the user to whom the balance / gift card is being transferred. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. passcode: type: string description: Secondary authentication PIN that must be passed if it is enabled for a business. It can be turned on/off from the Punchh platform. amount: type: string description: Amount being transferred to a recipient. If the entire available amount on a gift card is selected, the whole card will be transferred. full_transfer: type: boolean description: Whether a gift card should be transferred or not. A "true" value indicates that the gift card itself should be transferred. Following the gift card transfer, the system revokes the original user’s ownership, and the transferee becomes the new owner. A "false" value indicates that only a partial amount should be transferred from the gift card. required: - client - recipient_email - recipient_phone - recipient_fb_uid - amount examples: default: value: client: CLIENT_GOES_HERE recipient_email: test@example.com recipient_phone: 1111111111 recipient_fb_uid: FB_UID_GOES_HERE passcode: '1234' amount: '13' full_transfer: false parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards/{uuid}/share: post: responses: '200': description: OK content: text/plain: examples: default: value: "[\n \"Well done Amigo, you’re sharing our Cafe love by giving access\ \ to your card. Well done.\"\n]" '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: object properties: '0': type: string examples: Unauthorized (unknown client): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us Unauthorized ( access token not valid): value: '{ "errors": { "unauthorized": [ "An active access token must be used to query information about the current user." ] } }' summary: Share Gift Card description: Enables a user to share a gift card with another user operationId: Mobile_share_gift_card tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card issued by and maintained in the Punchh system - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: b418bf82a0cfb requestBody: content: application/json: schema: type: object properties: recipient_email: type: string description: Email address of the user with whom the balance / gift card is being shared. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_phone: type: string description: Phone number of the user with whom the balance / gift card is being shared. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_fb_uid: type: string description: Facebook "uid" of the user with whom the balance/gift card is being shared. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. passcode: type: string description: Secondary authentication PIN that must be passed if it is enabled for a business. It can be turned on/off from the Punchh platform. client: type: string description: OAuth client ID provided by the business required: - recipient_email - recipient_phone - recipient_fb_uid - passcode - client examples: default: value: recipient_email: test@example.com recipient_phone: 1111111111 recipient_fb_uid: FB_UID_GOES_HERE passcode: '1234' client: CLIENT_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards/{uuid}/revoke: parameters: - schema: type: string name: uuid in: path required: true description: Unique ID of the gift card issued by and maintained in the Punchh system delete: summary: Revoke Sharing operationId: delete-revoke_sharing responses: '200': description: OK headers: {} content: text/plain: examples: default: value: - You are no longer sharing this card with . '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: object examples: Unauthorized (access token not valid): value: errors: unauthorized: - An active access token must be used to query information about the current user. Unauthorized (unknown client): value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us description: If a user has [shared a gift card](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1gift_cards~1{uuid}~1share/post) with another user, this API enables the user to revoke the sharing rights. parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' tags: - Gift Cards x-stoplight: id: 7e6f5ca940716 requestBody: content: application/json: schema: type: object properties: sharer_email: type: string description: Email address of the user whose gift card sharing rights will be revoked client: type: string description: OAuth client ID provided by the business required: - sharer_email - client examples: default: value: sharer_email: test@example.com client: CLIENT_GOES_HERE /api2/mobile/gift_cards/gift: post: responses: '200': description: '' content: text/plain: examples: default: value: "[\n \"Whoa! You are one generous burrito stuffed amigo, with your gift of $28.00\ \ to .\"\n]" summary: Gift a Gift Card description: Enables a user to gift a gift card to another user operationId: mobile_gift_a_card tags: - Gift Cards parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 49b921e067bb4 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business recipient_email: type: string description: Email address of the user who will receive the gift card. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_phone: type: integer format: int32 description: Phone number of the user who will receive the gift card. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. recipient_fb_uid: type: string description: Facebook "uid" of the user who will receive the gift card. At least one of the three (i.e., recipient_email, recipient_phone, and recipient_fb_uid) should be provided. If more than one are provided as parameters, the system will identify that user for whom all of the provided parameters match. amount: type: string description: Monetary value of the gift card design_id: type: string description: Identification of a particular gift card design selected by the user while gifting a gift card payment_type: type: string description: This parameter is required when a user makes a payment via saved cards. Send "recurring" as the value of this parameter. transaction_token: type: string description: Unique digital identifier/token of the user's payment card, or the UUID of the saved payment card if the value of `payment_type` is "recurring". The transaction token is issued by a payment processor used by a business. cardholder_name: type: string description: Name of the person who owns the payment card used to purchase the gift card exp_date: type: string enum: - YYYY-MM-DD format: date description: Expiration date of the payment card used by the user type: type: string description: Type of payment card used by the user (e.g., Visa, Mastercard, etc.). required: - client examples: Payment via credit card: value: recipient_email: test@example.com recipient_phone: 1111111111 recipient_fb_uid: FB_UID_GOES_HERE client: CLIENT_GOES_HERE amount: '28' design_id: '1' transaction_token: TOKEN_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 418 type: VISA Payment via saved payment card: value: recipient_email: test@example.com recipient_phone: 1111111111 recipient_fb_uid: FB_UID_GOES_HERE client: CLIENT_GOES_HERE amount: '28' design_id: '1' payment_type: recurring transaction_token: TOKEN_GOES_HERE cardholder_name: FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE exp_date: 418 type: VISA /api2/mobile/gift_cards/{uuid}/consolidate: patch: responses: '200': description: '' content: application/json: schema: type: object properties: source_card: $ref: '#/components/schemas/Gift-Card-Object' destination_card: $ref: '#/components/schemas/Gift-Card-Object' examples: default: value: "{\n \"source_card\": {}, \n \"destination_card\": {}\n}" '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_param: type: string examples: default: value: errors: missing_param: source_cards is missing/invalid summary: Consolidate Gift Cards description: 'Enables a user to transfer the entire balance of a gift card to another gift card. Note: After the balance transfer, the system removes the source gift card from the user''s timeline and changes its status to ''closed'' for the owner. Additionally, access is revoked for all users with whom the gift card was shared. Currently, this is applicable only to Givex and Heartland gift card providers.' operationId: mobile_consolidate_gift_cards tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: Unique ID of the destination gift card to which the entire balance will be transferred - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: a2e28763b0597 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Access token of the user source_card: type: string description: UUID of the source gift card from which the entire balance will be transferred required: - client - access_token - source_card examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE source_card: CARD_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/gift_cards/{uuid}/tip: post: responses: '200': description: '' content: application/json: schema: type: object properties: tipping_time: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the tip was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format checkin_id: type: integer description: 'Identifier of the check-in/order for which the tip is given ' location_id: type: integer description: Unique ID of the location where the tip occurred approved_amount: type: number description: Amount of the tip gift_card_uuid: type: string description: Unique ID of the gift card used for the tip examples: default: value: tipping_time: '2018-03-12T11:30:20+00:00' checkin_id: 47004327 location_id: 315736 approved_amount: 4.52 gift_card_uuid: UUID_GOES_HERE summary: Tip via Gift Card description: Enables a user to leave a tip (gratuity) using a gift card operationId: mobile_tip_via_gift_card tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card used for the tip - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 0dacb575663e1 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business checkin_id: type: integer description: Identifier of the check-in/order for which the tip is given tip: type: number description: Currency value of the tip, which should be less than or equal to the gift card balance required: - client - checkin_id - tip examples: default: value: client: CLIENT_GOES_HERE checkin_id: 47004327 tip: 4.52 parameters: - schema: type: string name: uuid in: path required: true /api2/mobile/{checkin_id}/referrals: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: avatar_remote_url: type: string description: Avatar URL of the possible referrer's profile image email: type: string description: Email address of the possible referrer fb_uid: type: string description: Facebook ID of the possible referrer first_name: type: string description: First name of the possible referrer last_name: type: string description: Last name of the possible referrer user_id: type: string description: ID that identifies the possible referrer within Punchh examples: default: value: - avatar_remote_url: URL_GOES_HERE email: test@example.com fb_uid: FB_UID_GOES_HERE first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE user_id: 111111111 summary: Fetch Possible Referrers description: Returns the details of people who have possibly referred a guest to use the loyalty program of a business operationId: mobile_fetch_possible_referrers tags: - Referrals parameters: - schema: type: integer in: path name: checkin_id required: true description: 'Check-in ID of the first check-in done by the referred user ' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 679d8638cb88f requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE parameters: - schema: type: string name: checkin_id in: path required: true post: responses: '200': description: '' summary: Select Referrer description: Selects a person who possibly referred a guest to use the loyalty program of a business operationId: mobile_select_referrer tags: - Referrals parameters: - schema: type: integer in: path name: checkin_id required: true description: Check-in ID of the first check-in done by the referred user - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: e1a077c19a06b requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business friend_to_refer: type: string description: Punchh ID of the user who possibly referred the guest required: - client - friend_to_refer examples: default: value: client: CLIENT_GOES_HERE friend_to_refer: '1058012332' /api2/mobile/feedbacks: post: responses: '200': description: '' content: application/json: schema: type: object properties: feedback_id: type: integer description: Unique ID assigned to a user's feedback examples: default: value: feedback_id: 267383 '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: default: value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required.' '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: rating: type: array items: type: string examples: default: value: errors: rating: - Rating is not a number. summary: Create Feedback description: Creates feedback in the system based on the message and/or rating provided by a user operationId: mobile_create_feedback parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 7d1ab1645c5b5 tags: - Feedback requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business message: type: string description: Text feedback that a user provides. At least one of 'message', 'rating', 'photo_url', or 'video_url' must be provided. rating: type: integer format: int32 description: Rating that a user provides. The maximum rating is indicated in the`maximum_rating_in_feedback` response parameter in the [Program Meta API](/docs/dev-portal-mobile/2617bed9b0e8e-program-meta-api). At least one of 'message', 'rating', 'photo_url', or 'video_url' must be provided. checkin_id: type: integer description: ID of the check-in for which a user provides feedback redemption_id: type: integer description: ID of the redemption for which a user provides feedback facebook_post_id: type: integer description: ID of the feedback posted by a user to the user's Facebook account republishable: type: boolean description: Whether the feedback message can be republished on a social media platform or not. The default value is "true", so the user must explicitly specify not to allow it. requires_response: type: boolean description: Whether the user wants to be contacted by the business for this feedback or not examples: default: value: client: CLIENT_GOES_HERE message: Good Coffee. rating: 5 checkin_id: '8393395' redemption_id: '925805' facebook_post_id: '1496981783892853' republishable: false requires_response: false /api2/mobile/checkins/barcode: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Checkin' examples: default: value: created_at: '2016-05-16T08:22:25-04:00' current_membership_level: Club Lite - Level 1 (0-400) location_id: 304252 pending_refresh: false points_earned: 72 store_number: '' survey_url: URL_GOES_HERE checkin_id: 11140692 first_checkin: false expiring_on: null '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: Bad Reqeust (required parameter missing): value: "{\n \"errors\": {\n \"missing_required_param\": [\n \"Required parameter\ \ missing or the value is empty: client\"\n ]\n }\n}" Bad Request (barcode missing): value: "{ \n \"errors\":{ \n \"missing_required_param\":[ \n \"Required\ \ parameter missing or the value is empty: bar_code\"\n ]\n }\n}" '412': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: default: value: errors: invalid_signature: - Signature doesn't match. See [this topic](/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is) '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: base: type: array items: type: string examples: Unprocessable entity (used barcode): value: "{ \n \"errors\":{ \n \"base\":[ \n \"You cannot use the same\ \ receipt more than once.\"\n ]\n }\n}" unprocessable entity (invalid barcode): value: "{ \n \"errors\":{ \n \"base\":[ \n \"This bar code is not\ \ valid.\"\n ]\n }\n}" unprocessable entity (below minimum checkin amount): value: "{ \n \"errors\":{ \n \"base\":[ \n \"The minimum checkin amount\ \ is $0.01.\"\n ]\n }\n}" unprocessable entity (old barcode): value: "{ \n \"errors\":{ \n \"base\":[ \n \"This receipt is too old\ \ to be accepted.\"\n ]\n }\n}" unprocessable entity (guest not within range): value: "{ \n \"errors\":{ \n \"base\":[ \n \"Guest not within range\ \ of restaurant location.\"\n ]\n }\n}" unprocessable entity (no barcode scanned): value: "{ \n \"errors\":{ \n \"base\":[ \n \"Due to network connectivity\ \ issues at the printing location, this Bar Code cannot be scanned. Please submit\ \ a picture of the receipt showing the receipt amount and receipt date via 'Need\ \ Help?' button.\"\n ]\n }\n}" unprocessable entity (multiple checkin error): value: "{ \n \"errors\":{ \n \"base\":[ \n \"You aren't allowed to\ \ scan multiple receipts in one visit, please try again later.\"\n ]\n }\n}" unprocessable entity (failed redis lookup): value: "{ \n \"errors\":{ \n \"base\":[ \n \"We are looking for your\ \ check, but it's taking longer than expected. Once we find it, we'll let you know\ \ and add it to your account.\"\n ]\n }\n}" summary: Create Loyalty Check-in by Barcode description: Creates a loyalty check-in for a user when the user scans/enters the barcode printed on an order receipt. The user can scan the barcode using the mobile app of the business or enter the barcode on the website of the business. operationId: mobile_create_loyalty_checkin_by_barcode parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: e1805d58af142 tags: - Check-ins requestBody: content: application/json: schema: type: object properties: bar_code: type: integer format: int32 description: Barcode printed on the receipt client: type: string description: OAuth client ID provided by the business gps_accuracy: type: string description: Accuracy of the user's device GPS latitude: type: number format: double description: Latitude coordinate of the user's device GPS. The latitude of the location is required if location_id is not provided. location_id: type: integer format: int32 description: ID of the location where the user did the check-in. The location ID is required if both the latitude and longitude of the location are not provided. If the latitude and longitude of the location are not provided, then by default Punchh identifies location based on the barcode printed on the receipt. longitude: type: number format: double description: Longitude coordinate of the user's device GPS. The longitude of the location is required if location_id is not provided. manual: type: boolean description: True if the user entered the barcode by hand. required: - bar_code - client examples: default: value: bar_code: BARCODE_GOES_HERE client: CLIENT_GOES_HERE gps_accuracy: '27' latitude: '26.9167509' location_id: '304991' longitude: '75.8136926' /api2/mobile/checkins/qrcode: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Checkin' examples: default: value: created_at: '2016-05-16T08:22:25-04:00' current_membership_level: Club Lite - Level 1 (0-400) location_id: 304252 pending_refresh: false points_earned: 72 store_number: '' survey_url: URL_GOES_HERE checkin_id: 11140685 first_checkin: false expiring_on: '2024-03-13' '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: Bad Request (client missing): value: errors: missing_required_param: - 'Required parameter missing or the value is empty: client' Bad Request (Decoded QR missing): value: "{ \n \"errors\":{ \n \"missing_required_param\":[ \n \"Required\ \ parameter missing or the value is empty: qr_decoded\"\n ]\n }\n}" '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required.' '412': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: default: value: errors: invalid_signature: - Signature doesn't match. See [this topic](/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is) '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: base: type: array items: type: string examples: unprocessable entity (muliple checkins made): value: "{ \n \"errors\":{ \n \"base\":[ \n \"You aren't allowed to\ \ scan multiple receipts in one visit, please try again later.\"\n ]\n }\n}" unprocessable entity (unable to determine location): value: "{ \n \"errors\":{ \n \"base\":[ \n \"Unable to determine your\ \ distance from El Paso. Please check to see if your phone's GPS is enabled and try\ \ upgrading your app.\"\n ]\n }\n}" unprocessable entity (location time validation): value: "{ \n \"errors\":{ \n \"base\":[ \n \"You can only checkin\ \ at this location within working hours.\"\n ]\n }\n}" unprocessable entity (invalid qr code): value: "{ \n \"errors\":{ \n \"base\":[ \n \"Invalid QR Code.\"\n\ \ ]\n }\n}" summary: Create Loyalty Check-in by QR Code description: Creates a loyalty check-in for a user when the user scans a quick-response (QR) code using the mobile app of the business operationId: mobile_create_loyalty_checkin_by_qr_code parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 351a504277f3b tags: - Check-ins requestBody: content: application/json: schema: type: object properties: qr_decoded: type: string format: int32 description: Decoded form of the QR code printed on the receipt client: type: string description: OAuth client ID provided by the business gps_accuracy: type: string description: Accuracy of the user's device GPS latitude: type: number format: double description: Latitude coordinate of the user's device GPS. The latitude of the location is required if location_id is not provided. location_id: type: integer format: int32 description: 'ID of the location where the user did the check-in. The location ID is required if both the latitude and longitude of the location are not provided. ' longitude: type: number format: double description: Longitude coordinate of the user's device GPS. The longitude of the location is required if location_id is not provided. manual: type: string description: True if the user entered the QR code by hand required: - qr_decoded - client examples: default: value: qr_decoded: QR_CODE_GOES_HERE client: CLIENT_GOES_HERE location_id: 304155 latitude: 26.9167509 longitude: 75.8136926 gps_accuracy: '27' manual: '' /api2/mobile/checkins/receipt_image: post: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Checkin' examples: default: value: created_at: '2016-05-17T08:22:25-04:00' current_membership_level: Club Lite - Level 2 (0-400) location_id: 304252 pending_refresh: false points_earned: 72 store_number: '' survey_url: URL_GOES_HERE checkin_id: 11140255 first_checkin: false expiring_on: null '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: base: type: array items: type: string examples: default: value: errors: base: - Location could not be determined summary: Create Loyalty Check-in by Receipt Image description: Creates a loyalty check-in for a user based on the receipt image captured by the user. The user captures the receipt image for an order and taps the create check-in button on the mobile app of the business. When the receipt is approved, loyalty points are added to the user's account. operationId: mobile_create_loyalty_checkin_by_receipt_image parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: eebe5e52f84d3 tags: - Check-ins requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business location_id: type: string description: ID of the location where the user did the check-in. The location ID is required if both the latitude and longitude of the location are not provided. receipt_url: type: string description: URL of the receipt image captured by the user. Use the [Image Upload to AWS](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1aws_s3_pre_signed_url/post) API endpoint to upload the receipt image to AWS. The endpoint returns the URL of the uploaded image in its response. latitude: type: string description: Latitude coordinate of the user's device GPS. The latitude of the location is required if location_id is not provided. longitude: type: string description: Longitude coordinate of the user's device GPS. The longitude of the location is required if location_id is not provided. gps_accuracy: type: string description: Accuracy of the user's device GPS examples: default: value: client: CLIENT_GOES_HERE location_id: '304155' receipt_url: IMAGE_URL_GOES_HERE /api2/mobile/checkins: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ 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 location_id: type: integer description: Unique location ID associated with the check-in location_name: type: string description: Name of the location associated with the check-in store_number: type: string description: Number of the store where the check-in occurred status: type: string description: 'Defines the type of check-in. Values returned are: - gift - loyalty - referral' pending_refresh: type: boolean description: Whether the check-in is pending refresh or not checkin_id: type: integer description: Unique ID of the check-in expiring_on: type: string enum: - YYYY-MM-DD format: date description: Date on which the check-in will expire examples: default: value: - created_at: '2016-05-06T11:23:03+00:00' location_id: 304252 location_name: ADDRESS_GOES_HERE store_number: '' status: gift pending_refresh: false checkin_id: 10895576 expiring_on: null '401': description: '' content: application/json: schema: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 summary: Fetch Check-ins description: Returns all check-ins of a user operationId: mobile_Fetch_checins parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: c7e74b4a278eb tags: - Check-ins requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/checkins/account_balance: get: responses: '200': description: '' content: application/json: schema: type: object properties: rewards: $ref: '#/components/schemas/rewards' banked_redemptions: $ref: '#/components/schemas/redemption_details' account_balance_details: $ref: '#/components/schemas/account-balance-details' examples: default: value: rewards: - becomes_available_at: '2016-05-17T05:23:29-07:00' campaign_type: null created_at: '2016-05-24T00:52:48-07:00' description: Free with the purchase of an entree. discount_channel: all discount_amount: null reward_image_url: IMAGE_URL_GOES_HERE name: Dessert read_at: null reward_properties: order-ahead store_numbers: [] franchisee_id: 1234 meta_data: Tag1, Tag2, Tag3, Tag4, Tag5 reward_id: 5051791 expiring_at: '2016-06-01T02:59:59-04:00' redemption_details: redemption_status: redeemable created_at: '2016-05-20T16:05:14+05:30' redeemable_id: 1041895320 redeemable_name: Dessert redeemable_description: '' redeemed_value: '20' redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2016-05-20T16:05:14+05:30' redemption_id: 994925280 redemption_tracking_code: '1435308' expiring_at: '2016-05-20T18:05:14+05:30' banked_redemptions: - redemption_status: expired created_at: '2018-02-05T04:52:20-06:00' redeemable_id: 3096 redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2018-02-05T04:52:20-06:00' redemption_id: 22383235 redemption_tracking_code: '8103935' expiring_at: '2018-02-05T08:52:20-06:00' redeemable_name: $5 Reward redeemed_value: null - redemption_status: expired created_at: '2018-02-06T03:48:02-06:00' redeemable_id: 3096 redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2018-02-06T03:48:02-06:00' redemption_id: 22450832 redemption_tracking_code: '8381242' expiring_at: '2018-02-06T07:48:02-06:00' redeemable_name: $5 Reward redeemed_value: null - redemption_status: expired created_at: '2018-07-19T07:19:47-05:00' redeemable_id: null redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2018-07-19T07:19:47-05:00' redemption_id: 34510132 redemption_tracking_code: '1656060' expiring_at: '2018-07-19T11:19:47-05:00' redeemable_name: null redeemed_value: 5 - redemption_status: redeemable created_at: '2019-01-07T02:00:38-06:00' redeemable_id: null redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2019-01-07T02:00:38-06:00' redemption_id: 49572717 redemption_tracking_code: '9861700' expiring_at: '2019-01-07T06:00:38-06:00' redeemable_name: null redeemed_value: 1 account_balance_details: banked_currency: 10 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: 0 redeemed_cards: null total_loyalty_visits: null unredeemed_cards: null current_membership_level_name: null lifetime_points: 165 redeemable_points: 10 unbanked_points: 65 membership_qualification_points: 500 '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: default: value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' summary: Account Balance description: Returns a user's account details, including reward details such as reward ID and account balance details such as banked currency, membership level, etc. operationId: mobile_account_balance parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 1ac8c60c0b08d tags: - Check-ins requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/checkins/transactions: get: responses: '200': description: '' content: application/json: schema: type: object properties: checkin: type: object properties: created_at: type: string description: Date/time when the check-in was created in the system, in ISO 8601 format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time current_membership_level: type: string description: Membership level of the user location_id: type: integer description: ID of the location associated with the loyalty check-in pending_refresh: type: boolean description: Whether the check-in is pending refresh or not points_earned: type: integer description: Number of points earned in the loyalty check-in store_number: type: string description: The store number where the check-in occurred checkin_id: type: integer description: ID of the loyalty check-in made by the user first_checkin: type: boolean description: Whether it is the first check-in at the business or not expiring_on: type: string enum: - YYYY-MM-DD format: date description: Date when points earned in the loyalty check-in will expire survey_url: type: string description: URL of the survey presented to a user completing a check-in redemptions: type: array items: type: object properties: redemption_status: type: string description: 'Status of the redemption. The values returned can be: - redeemable: The redemption can be redeemed at the POS. - expired: The redemption has expired and becomes unusable for the user. - honored: The redemption has already been processed successfully and redeemed by the user at a POS. - cancelled: The redemption can be voided by a user by approaching the POS if a redemption is done by mistake and the user wants to cancel it.' created_at: type: string description: Date/time when the redemption was created in the system, in ISO 8601 format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time redeemable_id: type: integer description: Unique ID of the redeemable redeemable_name: type: string description: Name of the redeemable redeemed_value: type: number format: float description: 'For a business with banked currency, a currency value will be returned (e.g., 10 would mean $10). For a business without banked currency, a points value will be returned (e.g., 10 would mean 10 points).' redemption_image_url: type: string description: URL of the image displayed in the app to depict the redeemable redemption_message: type: string description: A descriptive message that tells a user what the user has redeemed updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time at which the redemption was updated in the system redemption_id: type: integer description: Unique ID of the redemption that has been created redemption_tracking_code: type: string description: Code that a user must submit at the POS to receive the redeemed reward expiring_at: type: string description: Date/time, in ISO 8601 format, when the redemption_tracking_code expires and the user cannot use it at the POS enum: - YYYY-MM-DDThh:mm:ssZ format: date-time examples: default: value: checkin: created_at: '2016-05-24T07:19:37-04:00' current_membership_level: Tier 1 location_id: 304252 pending_refresh: false points_earned: 229 store_number: ABC01 survey_url: null checkin_id: 11370180 first_checkin: false expiring_on: null redemptions: - redemption_status: redeemable created_at: '2016-05-20T16:05:14+05:30' redeemable_id: 1041895320 redeemable_name: Dessert redeemed_value: '20' redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: '' updated_at: '2016-05-20T16:05:14+05:30' redemption_id: 994925280 redemption_tracking_code: '1435308' expiring_at: '2016-05-20T18:05:14+05:30' summary: Transaction Details description: Returns the details of a particular transaction using the transaction ID operationId: mobile_transaction_details parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/signature' x-stoplight: id: 2d7bc9f034998 tags: - Check-ins requestBody: content: application/json: schema: type: object properties: client: type: string description: 'OAuth client ID provided by the business ' transaction_id: type: string description: 'Receipt transaction ID. This transaction ID is received in the payload key "t", which comes along with the push notification. ' required: - client - transaction_id examples: default: value: client: CLIENT_GOES_HERE transaction_id: TRANSACTION_ID_GOES_HERE /api2/mobile/offers: get: responses: '200': description: '' content: application/json: schema: type: object properties: pinned_message: type: string description: An ephemeral message that can be displayed to all users at the top of the News & Offers screen rewards: $ref: '#/components/schemas/rewards' notifications: $ref: '#/components/schemas/Notifications' coupons: $ref: '#/components/schemas/Coupons' examples: default: value: pinned_message: '' rewards: - becomes_available_at: '2016-05-17T05:23:29-07:00' campaign_type: null created_at: '2016-05-24T00:52:48-07:00' description: Free with the purchase of an entree. reward_image_url: IMAGE_URL_GOES_HERE name: Dessert read_at: null reward_properties: order-ahead store_numbers: [] franchisee_id: 1234 meta_data: Tag1, Tag2, Tag3, Tag4, Tag5 reward_id: 5051791 expiring_at: '2016-06-01T02:59:59-04:00' redemption_details: null notifications: - id: 29133403 kind: system message: Something to cheer you up! read_at: null created_at: '2016-05-17T08:23:50-04:00' coupons: - code: Z954AC7 image_url: IMAGE_URL_GOES_HERE name: All Sign Up Final Coupon description: null start_date: null end_date: '2016-10-04' summary: List User Offers operationId: mobile_list_user_offers tags: - Offers parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f988f79b81913 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE /api2/mobile/offers/mark_read: put: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: user_notifications: type: string examples: default: value: errors: user_notifications: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 '422': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_event_type: type: array items: type: string examples: default: value: errors: invalid_event_type: - Invalid name given. It should be read_through_app or app_open_via_push summary: Mark Offers As Read description: 'Marks specific offers that have been read by a user: - Within the app via the News & Offers screen. The value `read_through_app` is passed with the `event_type` request parameter. - Via push notification on the phone screen. The value `app_open_via_push` is passed with the `event_type` parameter. For more information about push notifications and payload based on different types of notifications, including platform configurations required to enable push notifications, see [Push Notifications](/docs/dev-portal-mobile/additional-topics/notifications-push). Also, see [Notifications and Badges Count](/docs/dev-portal-mobile/additional-topics/notifications-badgecounts) for information about various use cases and best practices.' operationId: mobile_mark_read tags: - Offers parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f315da73eb9a7 requestBody: content: application/json: schema: type: object properties: rewards: type: string description: Comma-separated IDs of rewards. Either the `user_notifications` parameter or the `rewards` parameter must be sent in the request. user_notifications: type: string description: Comma-separated IDs of user notifications. Either the `user_notifications` parameter or the `rewards` parameter must be sent in the request. event_type: type: string description: 'Kind of event that shows how offers were read by the user. Valid values are read_through_app or app_open_via_push ' client: type: string description: 'OAuth client ID provided by the business ' required: - client examples: default: value: rewards: 309203, 309210 user_notifications: 7890469, 7890490 event_type: read_through_app client: CLIENT_GOES_HERE description: '' /api2/mobile/notifications: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: id: type: integer description: 'ID of the notification ' format: int64 kind: type: string description: 'Type of notification. There are three types of notifications that a user can receive: ''system'', ''campaign'', or ''news''. ' message: type: string description: 'Message sent to the user in the notification ' created_at: type: string description: 'Date/time when the notification was created in the system, in ISO 8601 format ' enum: - YYYY-MM-DDThh:mm:ssZ format: date-time read_at: type: string description: 'Date/time when the notification was read by the user from the user''s device, in ISO 8601 format ' enum: - YYYY-MM-DDThh:mm:ssZ format: date-time user_survey_id: type: integer description: 'ID of the attached survey. For details, see [Fetch User Survey API](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1survey_details/get). ' examples: default: value: - id: 22240773 kind: system message: Something to cheer you up!! created_at: '2016-03-30T01:50:13-05:00' read_at: null user_survey_id: null - id: 22240649 kind: campaign message: Thanks for signing up for the Club. Enjoy your first 25 points on us! created_at: '2016-03-29T01:38:28-05:00' read_at: null user_survey_id: null - id: 22240545 kind: system message: Thank you for signing up for the Wing Bar. You will receive 25 free points in 24 hours. created_at: '2016-03-28T01:38:34-05:00' read_at: null user_survey_id: null '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: Bad Request (invalid language): value: "{\n \"errors\": {\n \"invalid_language\": [\n \"Unknown/Invalid locale\ \ in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n ]\n\ \ }\n}" Bad request (invalid quantity): value: "{ \n \"errors\":{ \n \"qty\":\"Number of Notifications should be greater\ \ than zero. '-1' is zero, Blank or non-integer value\"\n }\n}" '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unknown_client: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us. '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' '412': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: default: value: errors: invalid_signature: - Signature doesn't match. See [this topic](/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is) summary: Fetch User Notifications description: 'Returns the details of notifications received by a user For more information about push notifications and payload based on different types of notifications, including platform configurations required to enable push notifications, see [Push Notifications](/docs/dev-portal-mobile/additional-topics/notifications-push). Also, see [Notifications and Badges Count](/docs/dev-portal-mobile/additional-topics/notifications-badgecounts) for information about various use cases and best practices.' operationId: mobile_fetch_user_notifications tags: - Notifications parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 0285fe645c89d requestBody: content: application/json: schema: type: object properties: client: type: string description: 'OAuth client ID provided by the business ' qty: type: string description: 'Number of notifications for which the details are required. By default, a maximum of 10 notifications are returned at once in order of recency. ' required: - client examples: default: value: client: CLIENT_GOES_HERE qty: '3' /api2/mobile/notifications/id: delete: responses: '200': description: '' content: application/json: schema: type: object properties: {} summary: Delete User Notification description: 'Deletes a notification received by a user ' operationId: mobile_delete_user_notification tags: - Notifications parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: id required: true description: ID of the notification to be deleted - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 507f773849cef requestBody: content: application/json: schema: type: object properties: client: type: string description: 'OAuth client ID provided by the business ' required: - client /api2/mobile/messages: get: responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/messages' examples: default: value: messages: - background_content: type: image url: IMAGE_URL alt_text: Black Background Image initial_frame: '' body: A new gastronomical experience awaits you as we launch the Double Hamburger. Juicy handmade patties treated with a gravy bath and accompanied by shredded lettuce, tomato, pickle, bulky chopped onion, mustard, and mayo. cta: - type: external_web_link link: https://punchh.com label: More Details cta_type: primary - type: external_web_link link: https://punchh.com label: Terms & Conditions cta_type: secondary dismissable: true hero_content: type: image url: IMAGE_URL alt_text: Double Hamburger initial_frame: '' launch_time: '2017-08-14T06:00:00+00:00' message_type: business_wide rank: 500 style_url: URL_OF_THE_STYLE_SHEET subtitle: Double the fun! tags: - business_announcement - menu_extension - recurring take_down_time: '2017-08-15T06:00:00+00:00' title: Introducing Double Hamburger read_at: '2024-08-19T15:31:28-07:00' created_at: '2024-08-19T15:30:27-07:00' message_id: 7491710585 deleted_at: '2024-08-20T15:30:27-07:00' summary: Fetch Messages description: 'Fetches the list of rich messages available for a user Apart from the API response mentioned here, the mobile client will have to fetch the style JSON directly from S3 (Amazon Cloud Storage), which defines how to render the rich message. For details, see [Style JSON for Rich Messages](/docs/dev-portal-mobile/additional-topics/style-json-for-rich-messages).' operationId: mobile_messages tags: - Notifications parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: e9485ca96ff55 requestBody: content: application/json: schema: type: object properties: client: type: string description: 'OAuth client ID provided by the business ' required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/message_readerships: post: responses: '202': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: default: value: errors: unauthorized: - An active access token must be used to query information about the current user. summary: Mark Messages As Read description: 'Rich messages of type `user_specific` can be marked as read by making this request. ' operationId: mobile_mark_messages_read tags: - Notifications parameters: - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 899a3394bf4e6 requestBody: content: application/json: schema: type: object properties: user_rich_notifications: type: string description: 'Comma-separated values of multiple messages that will be marked as read ' client: type: string x-stoplight: id: jpbcmandbq4y1 description: OAuth client ID provided by the business required: - client examples: default: value: user_rich_notifications: '821' client: CLIENT_GOES_HERE /api2/mobile/message_readerships/{message_id}: delete: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: default: value: errors: client: Required parameter missing or the value is empty. '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: default: value: errors: unauthorized: - An active access token must be used to query information about the current user. summary: Delete Messages description: 'Rich messages of type `user_specific` can be deleted by making this request. ' operationId: mobile_delete_messages tags: - Notifications parameters: - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - schema: type: string in: path name: message_id required: true description: ID of the `user_specific` message that will be deleted - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 8dbb3bf79ad94 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 9il3bfrot8dnr description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE /api2/mobile/batch_api: post: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: response_status_code: type: integer description: Numeric status code (e.g., 200, 400, 401, etc.) http_verb: type: string description: Operation type (e.g., get, put, patch, etc.) uri: type: string description: Target URI for requests body: type: string examples: default: value: - response_status_code: 0 http_verb: put uri: URI_GOES_HERE body: string '401': description: '' content: application/json: schema: type: object properties: message: type: string code: type: integer summary: Making Batch Requests description: Batching allows you to pass instructions for several operations in a single HTTP request. Punchh will process each of your API calls sequentially / in parallel (to be decided). Once all operations have been completed, a consolidated response will be passed back to you. operationId: mobile_making_batch_requests tags: - Meta & Version parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-private: true x-stoplight: id: 311413e35153f requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business batch: type: array items: type: object properties: http_verb: type: string description: Operation type (e.g., get, put, patch, etc.) uri: type: string description: Target URI for requests show_headers_in_response: type: boolean description: If set to "true", it returns the headers of each API call in the batch. Disabled by default access_token: type: string x-stoplight: id: 3ix8sjr1oznke description: Access token of the user required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE batch: - http_verb: get uri: URI_GOES_HERE show_headers_in_response: false description: '' /api2/mobile/users/lifetime_stats: get: responses: '200': description: '' content: application/json: schema: type: object properties: points_earned: type: integer description: Total number of points earned by the user cards_earned: type: integer description: Total number of cards earned by the user cards_redeemed: type: integer description: Total number of cards redeemed by the user offers_redeemed: type: integer description: Total number of offers redeemed by the user examples: default: value: points_earned: 75 cards_earned: 0 cards_redeemed: 0 offers_redeemed: 0 summary: Lifetime Stats x-private: true description: Returns loyalty statistics of a user since the time the user signed up / registered on the app of a business operationId: mobile_lifetime_stats tags: - Users parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: ba9b7b4eabc8a requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 4o60zdlqlpw1o description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_GOES_HERE description: '' /api2/mobile/migration_lookup: post: responses: '200': description: '' content: application/json: schema: type: object properties: email: type: string description: Email address of the user identified in the migration data first_name: type: string description: First name of the user identified in the migration data last_name: type: string description: Last name of the user identified in the migration data phone: type: string description: Phone number of the user identified in the migration data zip_code: type: string description: Zip code of the user identified in the migration data address: type: string description: Address of the user identified in the migration data birthday: type: string description: Birthday of the user identified in the migration data, in YYYY-MM-DD format anniversary: type: string description: Anniversary of the user identified in the migration data, in YYYY-MM-DD format marketing_pn_subscription: type: boolean description: 'Whether the user has subscribed to marketing push notifications or not A "null" value indicates that no preference was received in the user''s migration data.' marketing_email_subscription: type: boolean description: 'Whether the user has subscribed to marketing emails or not A "null" value indicates that no preference was received in the user''s migration data.' examples: default: value: email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE phone: 1111111111 zip_code: '94040' address: ADDRESS_GOES_HERE birthday: '1999-01-01' anniversary: '2013-07-13' marketing_pn_subscription: true marketing_email_subscription: false '422': description: '' content: application/json: schema: type: object properties: errors: type: string examples: default: value: errors: Incorrect information submitted. Please retry. x-private: true summary: Migration Look-up description: Returns the details of a user identified in the migration data provided by a business operationId: mobile_migration_lookup tags: - Migration parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 55d958a0147ba requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business card_number: type: string description: Membership number (any unique identification number) of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. email: type: string description: Email address of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. first_name: type: string description: First name of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. last_name: type: string description: Last name of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. phone: type: string description: Phone number of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. required: - client examples: default: value: client: CLIENT_GOES_HERE card_number: CARD_NUMBER_GOES_HERE get: responses: '200': description: '' content: application/json: schema: type: object properties: response: type: string examples: default: value: response: ok '422': description: '' content: application/json: schema: type: object properties: errors: type: string examples: default: value: errors: Incorrect information submitted. Please retry. description: Returns the success response for a user identified in the migration data provided by a business summary: Basic Migration Look-up operationId: mobile_basic_migration_lookup tags: - Migration parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' x-private: true x-stoplight: id: 132c22d8b0a45 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business email: type: string description: Email address of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. first_name: type: string description: First name of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. last_name: type: string description: Last name of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. phone: type: string description: Phone number of the user from the old loyalty program used for the look-up. It can be made mandatory or optional from the Punchh platform. required: - client examples: default: value: client: CLIENT_GOES_HERE email: test@example.com /api2/mobile/feedbacks/{feedback_id}: patch: summary: Update Feedback operationId: mobile_update_feedback parameters: - schema: type: string in: path name: feedback_id required: true description: Feedback ID - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-private: true x-stoplight: id: 3d4c52e665987 tags: - Feedback responses: '200': description: '' content: application/json: schema: type: object properties: feedback_id: type: string description: ID of the feedback that was updated examples: default: value: feedback_id: FEEDBACK_ID_GOES_HERE requestBody: content: application/json: schema: type: object properties: checkin_id: type: string description: Check-in ID of the feedback video_url: type: string description: Video URL of the feedback photo_url: type: string description: Photo URL of the feedback redemption_id: type: string description: Redemption ID of the feedback client: type: string description: OAuth client ID provided by the business parameters: - schema: type: string name: feedback_id in: path required: true /api2/mobile/gift_cards/{uuid}/epin: get: responses: '200': description: '' content: application/json: schema: type: object properties: epin: type: string description: Security PIN associated with a gift card. A 'NULL' value indicates that no EPIN is associated with the gift card. examples: default: value: epin: EPIN_GOES_HERE x-private: true summary: Get Gift Card EPIN description: Returns the generated EPIN for a gift card operationId: mobile_generating_gift_card_epin tags: - Gift Cards parameters: - schema: type: string in: path name: uuid required: true description: Unique ID of the gift card issued by and maintained in the Punchh system - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 1a0508fff6a62 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: tnkt076emc6xx description: OAuth client ID provided by the business passcode: type: string x-stoplight: id: efhmzbgt45e9x description: Secondary authentication PIN that must be passed if it is enabled for a business. It can be turned on/off from the Punchh platform. required: - client examples: default: value: client: CLIENT_GOES_HERE passcode: PASSCODE_GOES_HERE parameters: - schema: type: string name: uuid in: path required: true description: Unique ID of the gift card issued by and maintained in the Punchh system. /api2/mobile/payments/client_token: get: responses: '200': description: '' content: application/json: schema: type: object properties: token: type: string description: Payment client token examples: default: value: token: TOKEN_GOES_HERE summary: Get Client Token x-private: true operationId: mobile_get_client_token tags: - Payments parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 7053c182bee30 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: u1054amgmgwza description: OAuth client ID provided by the business payment_gateway_name: type: string x-stoplight: id: yi9tccf8jxllq description: Name of the payment gateway for which the nonce is generated. Currently, only "braintree" is supported. enum: - braintree required: - client examples: default: value: client: CLIENT_GOES_HERE payment_gateway_name: braintree /api2/mobile/payments: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 summary: Record Payment x-private: true operationId: mobile_record_payment tags: - Payments parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 07db12035980f requestBody: content: application/json: schema: type: object properties: payment_method_nonce: type: string description: Payment method nonce membership_program_id: type: string description: Membership program ID examples: default: value: payment_method_nonce: PAYMENT_METHOD_NONCE_GOES_HERE membership_program_id: MEMBERSHIP_PROGRAM_ID_GOES_HERE /api2/mobile/file_upload: post: responses: '200': description: '' content: application/json: schema: type: object properties: signed_url: type: string examples: default: value: signed_url: URL_GOES_HERE '401': description: '' content: application/json: examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 operationId: mobile_file_upload x-private: true tags: - File Upload parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' summary: Get Signed URL x-stoplight: id: eaec6a2826a6d requestBody: content: application/json: schema: type: object properties: file_name: type: string description: Name of the file to be uploaded client: type: string description: OAuth client ID provided by the business examples: default: value: file_name: FILE_NAME_GOES_HERE client: CLIENT_GOES_HERE /api2/mobile/locations/beacon_entry: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: Bad Request (missing parameter): value: errors: missing_required_param: - 'Required parameter missing or the value is empty: location_id' Bad Request (invalid language): value: "{ \n \"errors\":{ \n \"invalid_language\":[ \n \"Unknown/Invalid\ \ locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n\ \ ]\n }\n}" '403': description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_access_token: type: array items: type: string examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' description: This API pertains to how a registered user is detected when the user enters the beacon's range and what follows. summary: Record Beacon Entry operationId: mobile_record_beacon_entry tags: - Beacons parameters: - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-private: true x-stoplight: id: 6720eb5930c53 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Security token that identifies a user beacon_major: type: integer description: ID of the business assigned by Punchh beacon_minor: type: integer description: ID assigned to the beacon. This value can be configured in the Punchh platform. A single location can have multiple minors. examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE beacon_major: 635 beacon_minor: 1 /api2/mobile/locations/beacon_exit: delete: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: Bad Request (missing parameter): value: errors: missing_required_param: - 'Required parameter missing or the value is empty: location_id' Bad Request (invalid language): value: "{ \n \"errors\":{ \n \"invalid_language\":[ \n \"Unknown/Invalid\ \ locale in Accept-Language Header.Supported locales are en-GB, es-CR, en, es.\"\n\ \ ]\n }\n}" '403': description: '' content: application/json: examples: default: value: errors: invalid_access_token: - 'Error: access_token not found or is incorrect! Valid access_token of the user required' summary: Record Beacon Exit description: This API pertains to what action is triggered when an already-detected, registered user leaves the beacon's range. operationId: mobile_record_beacon_exit tags: - Beacons parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-private: true x-stoplight: id: 512261b657431 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business access_token: type: string description: Security token that identifies a user beacon_major: type: integer description: ID of the business assigned by Punchh beacon_minor: type: integer description: ID assigned to the beacon. This value can be configured in the Punchh platform. A single location can have multiple minors. examples: default: value: client: CLIENT_GOES_HERE access_token: ACCESS_TOKEN_GOES_HERE beacon_major: 635 beacon_minor: 1 /api2/mobile/locations/configuration: get: responses: '200': description: '' content: application/json: schema: type: object properties: log_level: type: string description: 'Log level (0-6) of the location: 0 - None - no logs generated 1 - System - system level logs 2 - Error - any error from API or system errors 3 - Warning - app level or system level warning 4 - Information - app level logs 5 - Request - logs for all request data 6 - Response - logs for all request and response details' print_barcodes: type: string description: Set to 1 if the program type of the business is points unlock redeemables. If this is 1, banked_rewards_mode and visits_mode will be 0. short_key: type: string description: Short location access key by which the location is accessible diagnostics: type: string description: Should be `1` if the location has diagnostic logs; else it should be `0` header: type: string description: Header message of the location on the receipt trailer_1: type: string description: Line 1 of receipt message trailer_2: type: string description: Line 2 of receipt message trailer_3: type: string description: Line 3 of receipt message trailer_4: type: string description: Line 4 of receipt message trailer_5: type: string description: Line 5 of receipt message update_interval: type: string description: The time polling interval between the POS and Punchh is known as the update_interval (minutes). examples: default: value: log_level: '4' print_barcodes: '0' short_key: '0' diagnostics: '1' header: 'CAPAddicts Rewards ' trailer_1: 'Bar code valid for 24 hours. ' trailer_2: 'Visit URL_GOES_HERE ' trailer_3: 'to download our mobile app! ' trailer_4: '' trailer_5: '' update_interval: '60' '401': description: '' content: application/json: examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 summary: Location Configuration operationId: mobile_location_configuration tags: - Locations parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-private: true x-stoplight: id: b7af184243f26 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business location_key: type: string description: Location key examples: default: value: client: CLIENT_KEY_GOES_HERE location_key: LOCATION_KEY_GOES_HERE /api2/mobile/locations/{location_key}/diagnostic_logs: post: responses: '200': description: '' content: application/json: schema: type: object properties: {} '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 summary: Diagnostic Logs x-private: true operationId: mobile_diagnostic_logs tags: - Locations parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f2358033b6f88 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business terminals: type: integer description: Number of terminals for diagnostic logs location_id: type: integer description: Location ID terminal: type: integer description: Number of terminal for diagnostic logs language: type: string description: Language of diagnostic logs (e.g., `en`) mac_address: type: string description: Mac address of diagnostic logs receipt_datetime: type: string description: Date/time when the receipt was created pos_type: type: string description: Type of POS (e.g., `aloha`) description: type: string description: Description of diagnostic logs examples: default: value: client: CLIENT_KEY_GOES_HERE terminals: 123 location_id: 12345 terminal: 12345 language: LANGUAGE_GOES_HERE mac_address: MAC_ADDRESS_GOES_HERE receipt_datetime: RECEIPT_DATETIME_GOES_HERE pos_type: POS_TYPE_GOES_HERE description: DESCRIPTION_GOES_HERE parameters: - schema: type: string name: location_key in: path required: true description: Location key /api2/mobile/locations/search: get: responses: '200': description: '' content: application/json: schema: type: object properties: location_id: type: integer description: Location ID pos_scanner_type: type: string description: Type of POS scanner used at the location examples: default: value: location_id: 43535 pos_scanner_type: barcode '401': description: '' content: application/json: schema: type: object properties: errors: type: object properties: message: type: string code: type: integer examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 x-private: true summary: Search Locations operationId: mobile_search_locations tags: - Locations parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 9f3efef0afc6b requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business latitude: type: string description: Latitude coordinate of the location longitude: type: string description: Longitude coordinate of the location gps_accuracy: type: string description: GPS accuracy of the location name_like: type: string description: Alias name of the location max: type: string description: Maximum redemption amount at the location examples: default: value: client: CLIENT_KEY_GOES_HERE latitude: LATITUDE_GOES_HERE longitude: LONGITUDE_GOES_HERE gps_accuracy: GPS_ACCURACY_GOES_HERE name_like: NAME_LIKE_GOES_HERE max: MAXIMUM_REDEMPTION_AMOUNT_GOES_HERE description: '' /api2/mobile/badges/{badge_id}: put: responses: '200': description: '' content: application/json: schema: type: object properties: {} '400': description: '' content: application/json: examples: default: value: errors: message: Access is denied due to invalid credentials. code: 401 summary: Update Badge With Story ID operationId: mobile_update_badge tags: - Badges parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-private: true x-stoplight: id: b244797d7dd58 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business story_id: type: string description: Story ID of Facebook post examples: default: value: client: CLIENT_KEY_GOES_HERE story_id: STORY_ID_GOES_HERE parameters: - schema: type: string name: badge_id in: path required: true /api2/wifi/users/: get: responses: '202': description: '' content: application/json: schema: type: object properties: {} summary: Guest Look-up for WiFi Enrollment description: Returns whether a user exists in the business or not operationId: mobile_wifi_enrollment tags: - WiFi Acquisition parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: ccd88fee787fe requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: m89d3as1th0l0 description: OAuth client ID provided by the business email: type: string x-stoplight: id: xyu85ewum26uv description: Email address of the user that will be looked up. Either `email` or `phone` should be provided to make the request. required: - client - email examples: default: value: client: CLIENT_GOES_HERE email: test@example.com description: '' post: responses: '202': description: "Accepted! This response means that the user has been added to the business as\ \ a WiFi-enrolled guest. \n\nIf this call is made accidentally for a user who already exists\ \ in the business, the record will be skipped and the response will still be `202` (accepted)." content: application/json: schema: type: object properties: {} summary: Enroll Guests via WiFi description: Enrolls guests for eClub using WiFi as the acquisition channel operationId: mobile_enroll_guest_for_wifi tags: - WiFi Acquisition parameters: - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: f3a013f9ed402 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business location_id: type: integer description: ID of the WiFi location store_number: type: integer description: Store number of the location user: $ref: '#/components/schemas/User-object' examples: default: value: client: CLIENT_GOES_HERE location_id: 311031 store_number: 4 user: email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE phone: '1111111111' address_line1: ADDRESS_GOES_HERE state: California zip_code: '94040' birthday: '1999-01-01' marketing_email_subscription: '1' /api2/mobile/users/points_expiry_timeline: get: responses: '200': description: '' content: application/json: schema: type: object properties: points_expiry: type: array description: 'The API returns in the points_expiry array object all future dates on which points are scheduled to expire when the status parameter is set to expired in the request. The values are shown in the `expiring_points` and `expired_at` response parameters. When the request contains the `lookback_period` parameter, the API returns the points expired in the last 30 days in the `expired_points` and `expired_at` response parameters. ' items: type: object properties: expiring_points: type: integer description: Number of points scheduled to expire on a date specified by the `expiring_at` parameter. This value is 0 (zero) if the user has already redeemed points for the corresponding time period. expiring_at: type: string description: Future date when points are due to expire, in ISO 8601 format format: date expired_points: type: integer description: Number of points that have already expired at some past timestamp (i.e., the value of the `expired_at` parameter) expired_at: type: string format: date description: Date when points expired examples: - '2023-05-20' examples: User's expiring points: value: points_expiry: - expiring_points: 1305 expiring_at: '2024-05-11' - expiring_points: 1102 expiring_at: '2024-09-27' - expiring_points: 403 expiring_at: '2025-03-12' User's expired points in the last 30 days: value: points_expiry: - expired_at: '2023-07-23' expired_points: 500 '422': description: Unprocessable Entity - Feature is disabled content: application/json: schema: type: object properties: errors: type: object x-stoplight: id: r86nyjhpr5qb7 properties: error_name: type: string x-stoplight: id: viqxhmn2ukev8 examples: Feature is disabled: value: errors: disabled_feature: Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. summary: Fetch Rolling Points Expiry description: 'Enables a business to display the number of points that are expiring each month for users in the mobile app. The API returns all future dates on which points are scheduled to expire. Prerequisite To make API calls, the backend flag "track_reward_banked_points" and the "Expires After" (unredeemed point expiry) option in the Punchh platform must be enabled for the business. If one or both are disabled in Punchh for your business, the API will return an error with this message: "Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue." Note: This API is currently supported for "points convert to rewards" and "points unlock redeemables" loyalty programs. The `status` and `lookback_period` parameters are applicable to only the "points unlock redeemables" program. Currently, `status` supports a value of "expired", and `lookback_period` supports a value of "30" days. Businesses can use the parameters to fetch all check-ins / related points for users that have expired in the last 30 days.' operationId: rolling_points_expiry parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Accept-Language' tags: - Users x-stoplight: id: 44f5841c77d4d requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business examples: - CLIENT_GOES_HERE status: type: string description: Filter for check-in status. The value supported for this parameter is "expired". lookback_period: type: integer description: Past duration, in days, for which the API returns the expired points for the user. The value supported for this parameter is 30. default: 30 required: - client examples: Request to fetch user's expiring points: value: client: CLIENT_GOES_HERE Request to fetch user's expired points: value: client: CLIENT_GOES_HERE status: expired lookback_period: 30 description: '' /api2/mobile/iframe_payments/new: get: summary: Get a PAR Pay Token tags: - Payments operationId: get-api2-mobile-iframe_payments-new description: 'Enables a user to generate a token for a payment card. The user can use the PAR Pay token to purchase gift cards, reload gift cards, generate a single scan code, etc. The API response presents a web page showing fields for entering payment card details. Once this HTML is submitted with proper card details, it will return a token. To generate a token, PAR Payments must be configured in the Punchh platform for the business to enable integration services. Once integration services are enabled, the platform can be configured to enable recurring payments for the payment processor. Contact your Punchh representative to update this Punchh platform configuration. ' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/User-Agent' responses: '200': description: The response body will contain HTML text. content: application/json: schema: type: object properties: error: type: string examples: Payment not supported: value: error: Payment is not supported or invalid configuration '400': description: Bad Request (missing or blank required parameter) content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: string examples: default: value: errors: missing_required_param_name: Required parameter missing or the value is empty '401': description: Unauthorized Request (Incorrect client value) content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: default: value: errors: unknown_client: - Client ID is incorrect. Please check client param or contact us x-stoplight: id: 210d5819985a4 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: BUSINESS_CLIENT_ID_GOES_HERE description: '' /api2/mobile/users/google_sign_in: post: summary: Log in With Google operationId: post-api2-mobile-users-google_sign_in responses: '200': description: Success Response - 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. headers: {} content: application/json: schema: type: object properties: access_token: $ref: '#/components/schemas/access_token-Object' user: type: object description: Includes details about the users who are registered on a particular business properties: address: 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 communicable_email: type: string description: Email address used for communication with the user created_at: type: string 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 in the mobile app using Facebook. For all subsequent logins, it returns a null value. 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 favourite_location_ids: type: string description: Favorite location IDs of the user 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 first_name: type: string description: First name of the user gender: type: string description: Gender of the user has_generated_fb_email: type: boolean description: Whether the user has generated a Facebook email or not 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: string description: Phone number of the user referral_code: type: string description: Referral code of the user profile_field_answers: $ref: '#/components/schemas/profile_field_answers' 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`. 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 privacy_policy: type: boolean description: Whether the user has agreed to the privacy policy to use the app as per the configuration title: type: string description: Salutation as selected by the user 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 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 preferred_locale: type: string description: Preferred locale of the user user_relations: $ref: '#/components/schemas/user-relation-attribute' zip_code: type: string description: Zip code where the user lives verification_mode: type: string description: Mode of verification (available only for a user in awaiting migration state) sms_subscription: type: boolean description: Whether the user has subscribed to SMS services or not age_verified_status: type: boolean x-stoplight: id: xop56wrem0667 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.' user_joined_at: type: string x-stoplight: id: d18g7662b7mh5 format: date-time description: Date and time when the user became a loyalty member apple_pass_url: type: string format: uri description: URL that a user can use to download the user's associated loyalty Apple pass google_pass_url: type: string format: uri description: URL that a user can use to download the user's associated loyalty Google pass examples: default: value: access_token: token: ACCESS_TOKEN_GOES_HERE seconds_to_expire: null revoked_at: null refresh_token: REFRESH_TOKEN_GOES_HERE scopes: - wifi user: address: ADDRESS_GOES_HERE anniversary: null avatar_remote_url: null birthday: '1999-01-01' city: Mountain View communicable_email: test@example.com created_at: '2023-02-24T15:56:07+05:30' email: test@example.com email_verified: false facebook_signup: null apple_signup: null apple_uid: APPLE_UID_GOES_HERE favourite_location_ids: '304155' favourite_store_numbers: '1023' fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: female has_generated_fb_email: false last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: upf0: test upf1: test upf2: test upf3: test referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: null state: null superuser: false terms_and_conditions: false privacy_policy: false title: '' updated_at: '2023-02-28T19:06:24+05:30' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 preferred_locale: en user_relations: [] zip_code: null verification_mode: null sms_subscription: false age_verified_status: true user_joined_at: '2023-02-24T15:56:07+05:30' apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE '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 description: "Enables mobile application users to log in using Google Sign-in. \n\nThe following\ \ must be configured for the business in the Punchh platform to make a successful call to the\ \ API:\n\n1\\. The Enable Google Sign-in option must be enabled in the Punchh platform. Contact\ \ your Punchh representative to update this Punchh platform configuration. \n\n2\\. Google Web Client ID, Google iOS Client ID / Google Andriod\ \ Client ID, and Google Web Client Secret must be specified in the Punchh platform. Contact your\ \ Punchh representative to update this Punchh platform configuration." 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: - Users x-stoplight: id: 76b0c3fab780c requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by 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: qblsop9lnlwhg 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 /api2/mobile/users/request_reactivation: post: summary: Reactivate User Profile operationId: post-api2-mobile-users-request_reactivation responses: '200': description: '200 OK. On submitting the request, the API returns this message in the response: "Please check your email for instructions on reactivating your account". ' headers: {} '422': description: Unprocessable Entity - Resending reactivation request content: application/json: schema: type: object properties: error: type: string x-stoplight: id: 3wt5hao3ulkiz examples: Resending reactivation request: value: error: There is already an ongoing request parameters: - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Accept' description: "Enables users to reactivate their deactivated profiles directly from the mobile app\ \ if 1) guests are allowed to raise reactivation requests via mobile app and iFrame and 2) the admin indicates that a user profile is eligible\ \ for future activation when deactivating the user profile in the Punchh platform. \n\nThe API\ \ returns a 200 response and sends a reactivation email with the subject line \"Reactivate account\ \ instructions\" to the user. The email message will contain instructions on how to proceed with\ \ the reactivation process and a link to complete the reactivation request. When the user clicks\ \ the link, a message is sent to the Punchh server for account reactivation. A message is displayed\ \ to the user stating \"Your reactivation request has been received successfully. Please check\ \ the status in the next 24-48 hours.\"\n\nIf the phone number of the user is used for reactivation\ \ on the mobile app (applicable only when the phone number sign-up feature is enabled for the\ \ business), the user is prompted to enter the OTP (One-Time Password) sent to the user's phone\ \ number. After the user submits the OTP, the request for reactivating the user account is sent\ \ to the Punchh server. The sign-up feature can be enabled in the Punchh platform for new businesses.\ \ \n\nIf email alerts\ \ are enabled for admins for all reactivation requests \ \ and if at least one admin is selected, the admin will receive email alerts for each reactivation\ \ request raised by users. \n\nThe Guests > Reactivation Requested tab in the Punchh platform\ \ lists all pending requests for account reactivation. The business can manually approve all reactivation\ \ requests made through the mobile app via the Punchh platform or opt for automatic approval.\n\ \nNote: Contact your Punchh representative to update these Punchh platform configurations. " tags: - Users x-stoplight: id: 5f81f5f1ee065 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: elwmkxmz2d25l description: OAuth client ID provided by the business email: type: string x-stoplight: id: qwqdd64irk36h description: Email address of the user that was used for creating the loyalty account phone: type: string x-stoplight: id: 0vfijoru2ru87 description: Phone number of the user that was used for creating the loyalty account (applicable only when the phone number sign-up feature is enabled for the business) required: - client - email examples: Example: value: client: CLIENT_GOES_HERE email: test@example.com description: '' /api2/mobile/drivethru_code: post: summary: Generate Loyalty Short Code operationId: post-api2-mobile-drivethru_code responses: '200': description: OK content: application/json: schema: type: object properties: short_code: type: string x-stoplight: id: 11bejs2b2uvv4 description: Short code generated for the loyalty guest expiring_at: type: string x-stoplight: id: milcbftl59ekt description: Date/time when the short code expires and can no longer be used at the drive-thru, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format new_short_code_generated: type: boolean description: Indicates whether a new short code is generated. When the value is true, a new short code is generated and returned. When false, a previously active short code is returned. examples: Response Example: value: short_code: CODE_GOES_HERE expiring_at: '2025-11-04T07:58:07Z' new_short_code_generated: true '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object x-stoplight: id: s4k0g7hir3u42 properties: location_id: type: string x-stoplight: id: h77vd9ybb3b3j examples: location_id is missing: value: errors: location_id: Required parameter missing or the value is empty. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string x-stoplight: id: jqp0b8ys32qb1 examples: Drive-thru feature disabled: value: errors: Drive-thru feature not enabled description: "Generates a short code from the mobile app, which the loyalty user can share verbally\ \ at the drive-thru window, enabling faster and more convenient account look-up at the POS. \n\ \nThe loyalty short code is intended for drive-thru identification only and cannot be used for\ \ payments. To generate a loyalty short code that supports both identification and payments, use\ \ the [Generate Single-Scan Code or Short Code API](https://developers.partech.com/docs/dev-portal-mobile/apis/mobile-api/tag/single-scan-code/post/api2/mobile/single_scan_tokens).\n\ \nNote: To generate the code, the drive-thru loyalty identification must be enabled for the business\ \ on the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration\ \ setting.\n" parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/signature' tags: - Drive-Thru x-stoplight: id: 647b28e02d630 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 28nbheozq2h1p description: OAuth client ID provided by the business location_id: type: number x-stoplight: id: vb9f2ayu0h0s6 description: ID of the location for which the short code is requested. This parameter is required only when the location-level short code strategy is selected in the Punchh platform for the business. Contact your Punchh representative to update this Punchh platform configuration setting. required: - client examples: Request Example: value: client: CLIENT_GOES_HERE location_id: 1 /api2/mobile/challenge_opt_in: put: summary: Opt In to Challenge operationId: put-api2-mobile-challenge_opt_in responses: '200': description: 'OK: For a valid user and campaign ID, the API returns 200 OK with "status": "success". ' content: application/json: examples: Request Example: value: message: You have been successfully enrolled in the challenge campaign. '401': description: 'Unauthorized: For an invalid access_token, the API returns 401 unauthorized error with the message (“An active access token must be used to query information about the current user.”).' content: application/json: schema: type: object properties: {} '409': description: 'Conflict: If an opt-in request is sent again for the same user and campaign, the API returns a 409 error with the message ‘Guest already opted in.' content: application/json: schema: type: object properties: {} '422': description: "Unprocessable Entity: \n- For an invalid or non-existing campaign ID, the API\ \ returns a 422 error with a descriptive error message (“Challenge campaign not found”).\n\ - When the Enable Guest Opt-in to Challenge Campaigns flag is set to false, the API returns\ \ 422 Unprocessable Entity with the message “Business does not have challenges opt-in enabled.”\n" content: application/json: schema: type: object properties: {} description: 'Allows loyalty users to explicitly opt into challenge campaigns. This functionality is disabled by default. Contact your Punchh representative to update this configuration setting. ' parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' tags: - Challenges x-stoplight: id: ef045c6ba3b80 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: f25ymzwge28vf description: OAuth client ID provided by the business id: type: string x-stoplight: id: d281gca2ohpsc description: ID of the challenge to opt in required: - client - id examples: Request Example: value: client: CLIENT_GOES_HERE id: '63724' /api2/mobile/challenge_opt_out: put: summary: Opt Out of Challenge operationId: put-api2-mobile-challenge_opt_out responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string x-stoplight: id: vb4yodbfk2k31 examples: Example Response: value: message: You have been successfully opted out of the challenge campaign. '400': description: 'Bad Request: API returns a 400 error with the message "Parameter ''id'' is required" if `id` is missing or empty' content: application/json: schema: type: object properties: {} '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string x-stoplight: id: jfbb7m1w77zio examples: User Not Signed In: value: error: You need to sign in or sign up before continuing. '404': description: Not Found content: application/json: schema: type: object properties: message: type: string x-stoplight: id: th0q67aeox9j6 examples: User Not Enrolled In Challenge: value: message: You did not opt in for this challenge campaign yet. '409': description: Conflict content: application/json: schema: type: object properties: {} examples: User Already Opted Out: value: message: You have already opted out of this challenge campaign. '422': description: Unprocessable Entity (WebDAV) content: application/json: schema: type: object properties: errors: type: object x-stoplight: id: clyir58p5cgxo properties: error_name: type: string x-stoplight: id: 6u2kim391jtik examples: Challenge Not Found: value: errors: challenge_not_found: Challenge campaign not found. Opt-Out Option Disabled in Platform: value: errors: challenges_opt_out_disabled: Business does not have challenges opt out enabled. Opt-In Option Disabled in Platform: value: errors: challenge_explicit_opt_in_disabled: Challenge campaign does not have explicit opt in enabled. description: 'Allows loyalty users to explicitly opt out of enrolled/opted-in challenge campaigns. This functionality is disabled by default. Contact your Punchh representative to update this configuration setting. ' parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' tags: - Challenges x-stoplight: id: c3990cac3e805 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: 2ih0cf821pmok description: OAuth client ID provided by the business id: type: string x-stoplight: id: ex15s1doe7np6 description: ID of the challenge to opt out of required: - client - id examples: Request Example: value: client: CLIENT_GOES_HERE id: '63724' description: '' /api2/mobile/par_games: get: summary: Fetch Games tags: - Game responses: '200': description: OK content: application/json: schema: type: object properties: games: $ref: '#/components/schemas/games' pagination: $ref: '#/components/schemas/pagination' examples: Response Example: value: games: - id: 4 name: Spin Wheel 1 description: zscc url: URL_GOES_HERE status: active channel: mobile created_at: '2025-11-30T22:32:25-08:00' updated_at: '2025-11-30T22:32:25-08:00' cover_img: IMAGE_URL_GOES_HERE - id: 3 name: Black OPS I description: '' url: URL_GOES_HERE status: active channel: web created_at: '2025-11-30T22:32:01-08:00' updated_at: '2025-11-30T22:32:01-08:00' cover_img: null - id: 1 name: Mario description: test url: URL_GOES_HERE status: active channel: mobile_web created_at: '2025-11-30T22:31:13-08:00' updated_at: '2025-11-30T22:31:13-08:00' cover_img: IMAGE_URL_GOES_HERE pagination: current_page: 1 per_page: 20 total_count: 3 total_pages: 1 has_next_page: false has_previous_page: false '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object x-stoplight: id: rha4znr291vz1 properties: parameter_name: type: string x-stoplight: id: 5aon316o67m1h examples: client parameter value empty or missing: value: errors: client: Required parameter missing or the value is empty. '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object x-stoplight: id: bkdiw7ypfvxuu properties: error_name: type: array x-stoplight: id: qbwgu8p7g5ll6 items: {} examples: Invalid or missing access token: value: errors: unauthorized: - An active access token must be used to query information about the current user. '404': description: 'Not Found: No games found for the given brand' content: application/json: schema: type: object properties: {} operationId: get-api2-mobile-par_games description: This API allows clients to fetch configured game URLs from the Punchh dashboard through an authenticated request. It enables mobile and web applications to dynamically display or trigger the correct game experiences based on the configurations set by brand admins. Only active game URLs are returned, ensuring that apps always reference the most current and valid game links. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: fxllut8rdqa9i description: OAuth client ID provided by the business page: type: integer x-stoplight: id: vbsnwue59ti1b description: Page number of results to retrieve. If a value is provided, the API returns only that page, using the value of per_page to determine how many records are included. If page is not specified, the API returns the first page by default. Any invalid value will be treated as the default value. default: 1 per_page: type: integer x-stoplight: id: 5x7dm4ii6qxzj description: Number of records to return per page. If per_page is not specified, the API defaults to 20 records per page. The maximum allowed value is 100. Any invalid value will be treated as the default value. minimum: 1 maximum: 100 default: 20 channel: type: string x-stoplight: id: kdot3n2lj5wt7 description: 'Filters the list of games by channel. Possible values: * mobile: Returns games available on mobile. * web: Returns games available on web. * mobile_web: Returns games available on both mobile and web. * If not specified, all games are returned.' required: - client examples: Request Example: value: client: CLIENT_GOES_HERE page: 1 per_page: 20 channel: mobile description: '' /api2/mobile/collectibles: get: summary: List Collectibles operationId: get-api2-mobile-collectibles description: 'Returns the list of collectibles configured for a business. Supports pagination and optional filtering by collectible category. Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration. ' tags: - Collectibles parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: collectible_id: type: integer description: Unique ID of the collectible collectible_name: type: string description: Name of the collectible image: type: string description: URL of the collectible image description: type: string description: Description of the collectible sequence: type: integer description: Display order of the collectible. Null if no ordering is configured. collectible_category_name: type: string description: Name of the category the collectible belongs to. Null if not mapped to any category. collectible_category_id: type: integer description: ID of the category the collectible belongs to. Null if not mapped to any category. meta: type: object properties: current_page: type: integer description: Current page number next_page: type: integer description: Next page number. Null if there is no next page. prev_page: type: integer description: Previous page number. Null if there is no previous page. total_pages: type: integer description: Total number of pages total_count: type: integer description: Total number of collectibles examples: Collectible without category: value: data: - collectible_name: Immortal collectible_id: 123 image: IMAGE_URL_GOES_HERE description: DESCRIPTION_GOES_HERE sequence: null collectible_category_name: null collectible_category_id: null meta: current_page: 1 next_page: 2 prev_page: null total_pages: 4 total_count: 33 Collectible with category: value: data: - collectible_name: Test collectible_id: 123 image: IMAGE_URL_GOES_HERE description: DESCRIPTION_GOES_HERE sequence: null collectible_category_name: AutoCat_1770282575250 collectible_category_id: 67 meta: current_page: 1 next_page: null prev_page: null total_pages: 1 total_count: 1 '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: client: type: string examples: Missing client parameter: value: errors: client: Required parameter missing or the value is empty. '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string error: type: string message: type: string examples: Invalid or missing access token: value: errors: unauthorized: - An active access token must be used to query information about the current user. Invalid client ID: value: error: INVALID_CLIENT message: Client ID is incorrect. Please verify client param or contact support. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Feature disabled: value: errors: Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. requestBody: content: application/json: schema: type: object properties: client: type: string description: Unique client identifier page: type: integer description: Page number for pagination per_page: type: integer description: Number of records to return per page collectible_category_id: type: string description: Comma-separated collectible category IDs to filter by (e.g., "67,69,75"). Multiple category IDs must be comma-separated. required: - client examples: Request Example: value: client: CLIENT_GOES_HERE page: 1 per_page: 33 collectible_category_id: 67,69,75 /api2/mobile/collectibles/{collectible_id}: get: summary: Fetch Collectible Details operationId: get-api2-mobile-collectibles-collectible_id description: 'Returns the details of a specific collectible by its ID, including the active campaigns associated with it. The API enforces the following validations and business rules: * Only one collectible_id is allowed per request. * Responses are limited to collectibles associated with the requesting business. * Only active campaigns are included in the response. * Campaigns are sorted by start date in ascending order, with the earliest starting campaign displayed first. Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration. ' tags: - Collectibles parameters: - schema: type: integer in: path name: collectible_id required: true description: The unique identifier of the collectible to fetch details for. - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/punchh-app-device-id' - $ref: '#/components/parameters/User-Agent' responses: '200': description: OK content: application/json: schema: type: object properties: collectible_id: type: integer description: Unique ID of the collectible collectible_name: type: string description: Name of the collectible image: type: string description: URL of the collectible image description: type: string description: Description of the collectible sequence: type: integer description: Display order of the collectible. Null if no ordering is configured. collectible_category_name: type: string description: Name of the category the collectible belongs to. Null if not mapped to any category. collectible_category_id: type: integer description: ID of the category the collectible belongs to. Null if not mapped to any category. disappear_date: type: string format: date-time description: Date and time when the collectible disappears. Null if it does not disappear. timezone: type: string description: Timezone associated with the collectible disappearance date status: type: string description: Current status of the collectible (e.g., Active) share_message: type: string description: Message displayed when the collectible is shared campaign_details: type: array description: List of campaigns associated with this collectible items: type: object properties: name: type: string description: Name of the campaign description: type: string description: Description of the campaign type: type: string description: Type of campaign (e.g., ChallengeCampaign) start_date: type: string description: Start date of the campaign. Null if not set. end_date: type: string description: End date of the campaign. Null if not set. timezone: type: string description: Timezone associated with the campaign start and end dates examples: Response Example: value: collectible_id: 123 collectible_name: Test Collectible image: IMAGE_URL_GOES_HERE description: Test Collectible sequence: 6 collectible_category_name: Easter 2026 collectible_category_id: 7 disappear_date: '2027-03-19T18:29:59Z' timezone: Asia/Kolkata status: Active share_message: Test Collectible campaign_details: - name: Every X universal new2 description: '' type: ChallengeCampaign start_date: null end_date: null timezone: Asia/Kolkata - name: segment auto enrolled description: '' type: ChallengeCampaign start_date: '2026-04-04' end_date: '2026-04-30' timezone: Asia/Kolkata - name: With Collectible description: With Collectible type: ChallengeCampaign start_date: '2026-04-18' end_date: '2026-05-30' timezone: America/Los_Angeles '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Invalid or missing access token: value: errors: unauthorized: - An active access token must be used to query information about the current user. '404': description: Not Found content: application/json: schema: type: object properties: errors: type: string examples: Collectible not found: value: errors: Collectible not found. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Feature disabled: value: errors: Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: Request Example: value: client: CLIENT_GOES_HERE /api2/mobile/users_collectibles: get: summary: Fetch User Collectibles operationId: get-api2-mobile-users_collectibles description: 'Returns the list of collectibles earned by a user. Supports pagination and optional filtering by collectible category. Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration. ' tags: - Collectibles parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/User-Agent' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: collectible_id: type: integer description: Unique ID of the collectible collectible_name: type: string description: Name of the collectible image: type: string description: URL of the collectible image count: type: integer description: Number of times the user has earned this collectible disappear_at: type: string description: Date and time when the collectible disappears. Null if it does not disappear. sequence: type: integer description: Display order of the collectible. Null if no ordering is configured. collectible_category_id: type: integer description: ID of the category the collectible belongs to. Null if not mapped to any category. collectible_category_name: type: string description: Name of the category the collectible belongs to. Null if not mapped to any category. meta: type: object properties: current_page: type: integer description: Current page number next_page: type: integer description: Next page number. Null if there is no next page. prev_page: type: integer description: Previous page number. Null if there is no previous page. total_pages: type: integer description: Total number of pages total_count: type: integer description: Total number of collectibles examples: With collectibles: value: data: - collectible_id: 116 collectible_name: easter 7 image: IMAGE_URL_GOES_HERE count: 1 disappear_at: null sequence: 1 collectible_category_id: 7 collectible_category_name: Easter 2026 - collectible_id: 103 collectible_name: without category3 image: IMAGE_URL_GOES_HERE count: 1 disappear_at: '2026-03-28T09:00:00Z' sequence: 4 collectible_category_id: null collectible_category_name: null meta: current_page: 1 next_page: 2 prev_page: null total_pages: 2 total_count: 22 No collectibles: value: data: [] meta: current_page: 1 next_page: null prev_page: null total_pages: 0 total_count: 0 '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: unauthorized: type: array items: type: string examples: Invalid or missing access token: value: errors: unauthorized: - An active access token must be used to query information about the current user. '404': description: Not Found content: application/json: schema: type: object properties: status: type: integer error: type: string examples: Incorrect endpoint: value: status: 404 error: Not Found '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: string examples: Feature disabled: value: errors: Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. x-stoplight: id: collectibles-users-get requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business page: type: integer default: 1 description: Page number for pagination. If not specified, returns the first page by default. per_page: type: integer default: 20 description: Number of records to return per page. Defaults to 20 if not specified. include_disappeared_collectibles: type: boolean default: false description: Whether to include collectibles that have disappeared. Defaults to false. collectible_category_id: type: string description: 'Filters collectibles by category. Accepts a single ID or multiple comma-separated IDs. - NULL (not provided) → Returns all categories, including collectibles with no category. - 0 → Returns only collectibles with no category. - Single or multiple IDs (e.g., "0,1,2,3") → Returns collectibles matching those category IDs.' required: - client examples: Request Example: value: client: CLIENT_GOES_HERE /api2/mobile/user_banking_preferences: put: responses: '200': description: 200 OK — Successful Update content: application/json: schema: type: object properties: save_points_for_swag_enabled: type: boolean description: Indicates whether the guest has enabled saving points for swag redemption saved_swag_points_threshold: type: integer minimum: 0 maximum: 999999 description: The number of points the guest has configured to reserve for swag redemption swag_balance: type: integer minimum: 0 description: "The number of points currently accumulated in the swag balance. Calculated\ \ as the smaller of the user's available points balance and the configured `saved_swag_points_threshold`.\ \ \n\nFor example, if the guest has 100 points and the threshold is 200, the swag\ \ balance is 100. If the guest has 300 points and the threshold is 200, the swag\ \ balance is 200.\n\nReturns 0 when `save_points_for_swag_enabled` is false or `saved_swag_points_threshold`\ \ is 0.\n" examples: Save Points Disabled: value: save_points_for_swag_enabled: false saved_swag_points_threshold: 0 swag_balance: 0 Save Points Enabled — Available Points Below Threshold (100 points): value: save_points_for_swag_enabled: true saved_swag_points_threshold: 200 swag_balance: 100 Save Points Enabled — Active Swag Balance: value: save_points_for_swag_enabled: true saved_swag_points_threshold: 200 swag_balance: 200 '400': description: 'Bad Request - Missing required parameters — "Provide at least one of save_points_for_swag_enabled or saved_swag_points_threshold." ' '401': description: 'Unauthorized - Missing or invalid access token — "An active access token must be used to query information about the current user." ' '422': description: 'Unprocessable Entity - Save Points for Swag feature disabled — "Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue." - Threshold not a number — "Saved swag points threshold is not a number" - Threshold exceeds maximum — "Saved swag points threshold must be less than or equal to 999999" ' summary: Save Points for Swag description: "In Points Convert to Currency or Points Convert to Rewards loyalty programs, loyalty\ \ users earn points on every purchase. By default, these points are automatically converted (\"\ banked\") into rewards or currency. However, some loyalty users may prefer to accumulate their\ \ points and redeem them for swag instead.\n\nThis API lets loyalty users manage their \"Save\ \ Points for Swag\" preference from the mobile app. When the \"Save Points for Swag\" feature\ \ is enabled for the brand, loyalty users can opt in or out of the feature and set a points threshold.\ \ Points accumulated up to this threshold are reserved for swag redemption, while points earned\ \ above the threshold are automatically converted into rewards or currency. This gives loyalty\ \ users flexibility in how they use their points. If a loyalty user no longer wants to save points\ \ for swag, they can update their preference to opt out.\n\n## Prerequisite\n\nBefore processing\ \ the request, the API verifies that the \"Save Points for Swag\" feature is enabled for the brand\ \ on the Punchh platform. If the feature is not enabled, the API returns an appropriate error\ \ code and message. \n\n**Note**: Contact your Punchh representative to update this Punchh platform\ \ configuration.\n\nOn success, the API responds with a **200 OK** status.\n\n\nSee [Get User\ \ Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/get),\ \ [Fetch Available User Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_merch/get),\ \ [Redeem Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1swag_redemptions/post),\ \ and [Get Swag Shipping Details](https://developers.partech.com/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/swag/get/api2/dashboard/swag_shipping_details).\n" operationId: mobile_update_user_banking_preferences tags: - Swag parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business save_points_for_swag_enabled: type: boolean x-nullable: true description: "Enables (true) or disables (false) the \"Save Points for Swag\" preference.\ \ The \"Save Points for Swag\" feature must be enabled for the brand. \n\nWhen enabled,\ \ the user's points are accumulated and saved for swag redemption up to the `saved_swag_points_threshold`.\ \ \n\nWhen disabled, no points are saved for swag, and all points are automatically\ \ converted into rewards/currency per the program rules. A null value (or omitting\ \ the parameter) is treated as 'false', which disables saving mode and resets `saved_swag_points_threshold`\ \ to 0. \n\nNote: Both `save_points_for_swag_enabled` and `saved_swag_points_threshold`\ \ parameters can be provided together or independently in a single request. At least\ \ one parameter must be provided; omitting both returns a 400 Bad Request error.\n" saved_swag_points_threshold: type: integer minimum: 0 maximum: 999999 x-nullable: true description: 'The member-defined points threshold. Points accumulated up to this limit are reserved for swag and excluded from automated banking conversion. Points above this threshold are automatically converted into rewards or currency. Must be a non-negative integer. Invalid values (for example, "abc") return a 422 Unprocessable Entity error. The maximum allowed value is 999999; values exceeding this limit also return a 422 Unprocessable Entity error. If `save_points_for_swag_enabled` is ''false'' or null, this threshold is ignored and treated as 0. If `save_points_for_swag_enabled` is ''true'' and this parameter is omitted, it defaults to 0, meaning no points are reserved for swag, and all points are eligible for automated banking conversion. Note: Both `save_points_for_swag_enabled` and `saved_swag_points_threshold` parameters can be provided together or independently in a single request. At least one parameter must be provided; omitting both returns a 400 Bad Request error. ' required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE save_points_for_swag_enabled: true saved_swag_points_threshold: 500 get: summary: Get User Save Points for Swag description: 'Retrieves a loyalty user''s "Save Points for Swag" banking preferences, including the save-points opt-in status, configured threshold, and the number of points currently accumulated toward swag redemption. ## Prerequisites - The business must have the "Save Points for Swag" feature enabled in the Punchh platform. - The business must support banked point debit. If either condition is not met, the endpoint returns a 422 Unprocessable Entity error. **Note**: Contact your Punchh representative to update this Punchh platform configuration. See [Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/put), [Fetch Available User Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_merch/get), [Redeem Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1swag_redemptions/post), and [Get Swag Shipping Details](https://developers.partech.com/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/swag/get/api2/dashboard/swag_shipping_details).' operationId: mobile_get_user_banking_preferences tags: - Swag parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' responses: '200': description: OK content: application/json: schema: type: object properties: save_points_for_swag_enabled: type: boolean description: Indicates whether the guest has enabled saving points for swag redemption saved_swag_points_threshold: type: integer minimum: 0 maximum: 999999 description: The number of points the guest has configured to reserve for swag redemption swag_balance: type: integer minimum: 0 description: "The number of points currently accumulated in the swag balance. Calculated\ \ as the smaller of the user's available points balance and the configured `saved_swag_points_threshold`.\ \ \n\nFor example, if the guest has 100 points and the threshold is 200, the swag\ \ balance is 100. If the guest has 300 points and the threshold is 200, the swag\ \ balance is 200.\n\nReturns 0 when `save_points_for_swag_enabled` is false or `saved_swag_points_threshold`\ \ is 0.\n" examples: Save Points Disabled: value: save_points_for_swag_enabled: false saved_swag_points_threshold: 0 swag_balance: 0 Save Points Enabled — Available Points Below Threshold (100 points): value: save_points_for_swag_enabled: true saved_swag_points_threshold: 200 swag_balance: 100 Save Points Enabled — Active Swag Balance: value: save_points_for_swag_enabled: true saved_swag_points_threshold: 200 swag_balance: 200 '400': description: 'Bad Request - Missing `client` parameter — "Required parameter missing or the value is empty." ' content: application/json: schema: type: object properties: errors: type: object examples: Missing client parameter: value: errors: client: Required parameter missing or the value is empty. '401': description: 'Unauthorized - Missing or invalid access token — "An active access token must be used to query information about the current user." - Invalid client ID — "Unknown client." ' content: application/json: schema: type: object properties: errors: type: object examples: Invalid or missing access token: value: errors: unauthorized: An active access token must be used to query information about the current user. Invalid client ID: value: errors: unknown_client: Unknown client. '404': description: 'Not Found - Incorrect endpoint URL ' content: application/json: schema: type: object properties: status: type: integer error: type: string examples: Incorrect endpoint: value: status: 404 error: Not Found '422': description: 'Unprocessable Entity - Save Points for Swag feature disabled or banked point debit not supported — "Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue." ' content: application/json: schema: type: object properties: errors: type: string examples: Feature disabled: value: errors: Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE /api2/mobile/swag_redemptions: post: summary: Redeem Swag description: 'The Swag Redemption API allows an authenticated loyalty member to redeem saved loyalty points for a branded swag item. The API handles the full redemption flow end-to-end — including eligibility checks, point deduction, inventory decrement, reward creation, and optional shipping detail capture. See [Get User Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/get), [Fetch Available User Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_merch/get), [Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/put), and [Get Swag Shipping Details](https://developers.partech.com/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/swag/get/api2/dashboard/swag_shipping_details).' operationId: mobile_create_swag_redemption tags: - Swag parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Accept-Language' responses: '200': description: Swag redeemed successfully. content: application/json: schema: type: object properties: message: type: string examples: default: value: message: Swag redeemed successfully. '400': description: 'Bad Request - Missing `location_id` — "Required parameter missing or the value is empty: location_id" ' '401': description: 'Unauthorized - Missing or invalid access token — "You need to sign in or sign up before continuing." ' '404': description: 'Not Found - Item not available as swag (redeemable ID passed) — "Swag item not found." - Invalid/Deactivated swag ID — "Swag item not found." - Unknown or cross-business `location_id` — "Location not found." ' '422': description: 'Unprocessable Entity - Save Points for Swag feature disabled — "Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue." - Per-member redemption limit exceeded — "Redemption limit reached for the member." - Insufficient saved points — "Insufficient points to redeem this SWAG." - Item out of stock (quantity = 0 or NULL) — "Item is currently out of stock." - Invalid fulfillment method value — "Invalid fulfilment type specified." - Missing required field(s) — "Missing required field(s): {field_name}." ' requestBody: content: application/json: schema: type: object required: - client - swag_id - fulfillment_method properties: client: type: string description: OAuth client ID assigned to the business swag_id: type: integer description: ID of the swag item to redeem location_id: type: string description: ID of the store location. If not provided, the business's primary location is used. fulfillment_method: type: string description: 'Delivery method. Possible values: STORE_PICKUP or HOME_DELIVERY (case-insensitive)' enum: - STORE_PICKUP - HOME_DELIVERY shipping_info: type: object description: Required when `fulfillment_method` is HOME_DELIVERY. Ignored when `fulfillment_method` is STORE_PICKUP. required: - full_name - email - phone_number - address_line_1 - city - state - zipcode properties: full_name: type: string description: Full name of the shipping recipient email: type: string description: Contact email for the shipment phone_number: type: string description: Contact phone number. Must be a valid phone number. Current validation does not enforce a minimum length of 10 digits. address_line_1: type: string description: First line of the shipping address address_line_2: type: string description: Second line of the shipping address (apartment, suite, etc.) city: type: string description: City of the shipping address state: type: string description: State or region of the shipping address zipcode: type: string description: Postal / ZIP code of the shipping address delivery_instructions: type: string description: Special delivery instructions. No character limit currently enforced examples: default: value: swag_id: 73072 location_id: '353291' fulfillment_method: HOME_DELIVERY shipping_info: full_name: NAME_GOES_HERE email: test@example.com phone_number: '1111111111' address_line_1: Street 1 address_line_2: Street 2 delivery_instructions: please deliver it asap city: New York state: USA zipcode: '12344' /api2/mobile/user_merch: get: summary: Fetch Available User Swag description: 'Retrieves all available swag items that the authenticated user can view or redeem using their loyalty points. The response includes item details such as name, image, point cost, availability window, and fulfilment method. Results are paginated. Only items available in inventory are returned in the response. See [Get User Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/get), [Save Points for Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1user_banking_preferences/put), [Redeem Swag](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1swag_redemptions/post), and [Get Swag Shipping Details](https://developers.partech.com/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/swag/get/api2/dashboard/swag_shipping_details).' operationId: mobile_fetch_available_user_merch tags: - Swag parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/signature' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/punchh-app-device-id' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer description: Unique identifier for the swag item. name: type: string description: Display name of the swag item. image_url: type: string description: URL of the swag item image. points: type: integer description: Number of loyalty points required to redeem this item. start_time: type: string format: date-time description: Start date/time when the item becomes available for redemption in ISO 8601 format. end_time: type: string format: date-time description: End date/time after which the item is no longer available in ISO 8601 format. timezone: type: string description: Timezone for the availability window (IANA format). available_to_redeem: type: boolean description: Whether the item is currently available for the user to redeem. Set to 'true' when the user's points balance allocated for the swag is greater than or equal to the item's `points` value; otherwise, it is set to 'false'. fulfilment_method: type: string description: 'How the item is fulfilled. Possible values: store_pickup, home_delivery.' meta: type: object description: Pagination metadata. properties: current_page: type: integer description: The current page number. next_page: type: integer x-nullable: true description: The next page number, or null if on the last page. prev_page: type: integer x-nullable: true description: The previous page number, or null if on the first page. total_pages: type: integer description: Total number of pages available. total_count: type: integer description: Total number of merchandise items across all pages. examples: default: value: data: - id: 1 name: Merch Name1 image_url: IMAGE_URL_GOES_HERE points: 10 start_time: '2026-05-06T08:01:42Z' end_time: '2026-06-07T08:01:42Z' timezone: America/New_York available_to_redeem: true fulfilment_method: store_pickup - id: 2 name: Merch Name2 image_url: IMAGE_URL_GOES_HERE points: 15 start_time: '2026-05-16T08:01:42Z' end_time: '2026-06-17T08:01:42Z' timezone: America/New_York available_to_redeem: false fulfilment_method: home_delivery meta: current_page: 1 next_page: 2 prev_page: null total_pages: 2 total_count: 2 '401': description: 'Unauthorized - Missing or invalid access token — "You need to sign in or sign up before continuing." ' '422': description: 'Unprocessable Entity - Save Points for Swag feature disabled — "Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue." ' requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business required: - client examples: default: value: client: CLIENT_KEY_GOES_HERE tags: - name: Badges - name: Beacons - name: Challenges - name: Check-ins - name: Collectibles - name: Coupons - name: Drive-Thru - name: Feedback - name: File Upload - name: Game - name: Gift Cards - name: Invitations - name: Locations - name: Meta & Version - name: Migration - name: Notifications - name: Offers - name: Passcodes - name: Payment Cards - name: Payments - name: Referrals - name: Loyalty Transfers - name: Single Scan Code - name: Social Cause Campaign - name: Surveys - name: Users - name: Swag - name: WiFi Acquisition x-stoplight: id: bf6eddb435209 openapi: 3.1.1 servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com components: schemas: ChallengeListingItem: type: object properties: challenge_id: type: integer description: Challenge ID name: type: string description: Name of the challenge. The name is returned in the language specified in the Accept-Language request header, provided the challenge name has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies "fr" (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language. description: type: string description: Description of the challenge. The description is returned in the language specified in the Accept-Language request header, provided the challenge description has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under Marketing Automation > Campaign Management. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies "fr" (French), the description is returned in French if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language. image_url: type: string description: URL of the main banner image associated with the challenge campaign icon_url: type: string description: URL of the default icon image for the challenge icon_completed_url: type: string description: URL of the image icon that represents completion of the challenge start_date: type: string format: date enum: - YYYY-MM-DD description: Start date of the campaign end_date: type: string format: date enum: - YYYY-MM-DD description: End date of the campaign challenge_starting_at_tz: type: string format: date-time description: Start date and time of the challenge in the business timezone (ISO 8601 format) challenge_expiring_at_tz: type: string format: date-time description: End date and time of the challenge in the business timezone (ISO 8601 format) challenge_reach: type: string x-nullable: true description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are: - universal_auto_enrolment - segment_auto_enrolment - null (when no reach strategy is defined)' challenge_status: type: string x-nullable: true description: "Returns the details of availability of and enrollment of a guest into a specific\ \ challenge. Possible values are:\n* unavailable: This status will be returned for \"segment_auto_enrolment\"\ \ when a guest is NOT added to the \"user_feature_enrolment\" table.\n* enrolled: This status\ \ will be returned for:
\n a) \"universal_auto_enrolment\" in all cases since all signed-up\ \ guests are automatically enrolled for the challenge.
\n b) \"segment_auto_enrolment\"\ \ in cases when guests from the attached segment (to the challenge campaign) get added to\ \ the user_feature_enrolment table and are automatically enrolled for the challenge.
\n\ * null: For older default \"Segment\" type challenges, the status will always be null." challenge_type: type: string description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are: - receipt_qualification - every_x_points - segment' occurrence: type: string description: 'Possible values are: - **single** - Shows when restarting the challenge button is OFF in the campaign - **multiple** - Shows when restarting the challenge button is ON in the campaign' past_completions: type: integer description: The number of times the user has previously completed the challenge campaign. opted_in: type: boolean description: 'Indicates whether the user has opted in to a challenge. Possible values: * true - The user has opted in. The mobile app should show the opt-out button on the challenge card if the opt-out feature is enabled for the business in the Punchh platform. * false - The user has not opted in. The mobile app should show the opt-in button on the challenge card if the opt-in feature is enabled for the business in the Punchh platform. Contact your Punchh representative to update this configuration setting.' opted_out: type: boolean description: Indicates whether the user has opted out of the challenge explicit_opt_in: type: boolean description: Indicates whether the challenge requires explicit opt-in from the user before enrollment gift_reason: type: string description: Reason to give gifts to a user miscellaneous: type: string description: Returns miscellaneous response string as configured in the Punchh platform progress: type: array description: Array of progress objects showing completed steps and total steps for the challenge items: type: object properties: completed_steps: type: integer description: Number of steps a user has completed for a challenge total_steps: type: integer description: Number of total steps set for a challenge 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: 750d787ef37a5 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-details: type: object title: Account Balance Details (Object) x-stoplight: id: 2a0aec02b7738 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. 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." 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 (Deprecated): 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 (Deprecated): 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 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' 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: gq5ah9naehygk 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.' background-content: type: object description: "This is the content that makes the background of the message.\n\n```json\n{\n \"\ type\": \"image\",\n \"url\": \"IMAGE_URL_GOES_HERE\",\n \"alt_text\": \"Black Background\ \ Image\",\n \"initial_frame\": \"\"\n}\n```" title: Background Content (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. x-stoplight: id: 80de922cbc5ff banking_rules-Object: type: array title: Banking Rules (Array Object) items: type: object properties: banked_redeemable_id: type: string description: ID of the redeemable that is banked by the user as per the defined banking rules banking_slab: type: integer description: Banking slabs define the different intervals of earning. points_conversion_threshold: type: integer description: Points conversion thresholds are the sub-levels within a particular slab at which banking occurs. currency_earned: type: string description: Value of currency that is banked by the user as per the defined banking rules x-stoplight: id: ce2fab6db84eb base_redeemable-Object: type: object properties: name: type: string description: Name of the base redeemable description: type: string description: A description of the redeemable that appears in the app. This can be used to persuade users to redeem. image_url: type: string description: URL of the image displayed in the app to depict the redeemable redeemable_properties: type: array description: Properties such as "Merchandise", "Food Item", etc. can be added to a particular redeemable. items: type: string meta_data: type: string description: Metadata that can be added to a redeemable. This can be used to program mobile apps to have a certain behavior when specific data are received from the server. This can be configured in the Punchh platform. The maximum length is 255 characters. description: 'A base redeemable is used to provide identity to intangible entities, such as a completed card in a visit-based business. For example, in a visit-based business the configuration of a completed card (such as expiry, etc.) is picked from the base redeemable. ' title: Base Redeemable (Object) x-stoplight: id: c9d4a439024c8 Checkin: type: object title: Check-in (Object) x-stoplight: id: 4bae7b81b0f8a properties: created_at: type: string 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: External unique identifier of the check-in checkin_id: type: integer description: ID of the loyalty check-in made by the user pending_points: type: integer description: Number of pending points 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 description: Barcode printed on the receipt current_membership_level: type: string description: Membership level of the user x-nullable: true 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 expiring_on: type: string format: date description: Date when points earned in the loyalty check-in will expire examples: - '2024-03-13' Converted-Category-Balance: type: array title: Converted Category Balances (Array Object) 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 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 x-stoplight: id: ba04d89cdeea7 Coupons: type: array title: Coupons (Array Object) 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 x-stoplight: id: 16135004ce2f7 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.' description: "Short for call to action, a device designed to prompt an immediate response from a\ \ user\n\n```json\n[\n {\n \"type\": \"external_web_link\",\n \"link\": \"URL_GOES_HERE\"\ ,\n \"label\": \"More Details\",\n \"cta_type\": \"primary\"\n },\n {\n \ \ \"type\": \"external_web_link\",\n \"link\": \"URL_GOES_HERE\",\n \"label\"\ : \"Terms & Conditions\",\n \"cta_type\": \"secondary\"\n }\n]\n```\n" title: CTA (Array Object) x-stoplight: id: 80d7d22f4d11c Event-details-object: type: object properties: redemption_status: type: string description: 'Status of the redemption. The values returned can be: - redeemable: The redemption can be redeemed at the POS. - expired: The redemption has expired and becomes unusable for the user. - honored: The redemption has already been processed successfully and redeemed by the user at a POS. - cancelled: The redemption can be voided by a user by approaching the POS if a redemption is done by mistake and the user wants to cancel it.' created_at: type: string description: Date/time when the redemption was created in the system enum: - YYYY-MM-DDThh:mm:ssZ format: date-time redeemable_id: type: integer description: Unique ID of the redeemable redeemable_name: type: string description: Name of the redeemable redeemed_value: type: - 'null' - number description: 'For a business with banked currency, a currency value will be returned (e.g., 10 would mean $10). For a business without banked currency, a points value will be returned (e.g., 10 would mean 10 points).' format: float redemption_image_url: type: string description: URL of the image displayed in the app to depict the redeemable redemption_message: type: string description: A descriptive message that tells a user what the user has redeemed updated_at: type: string description: Date/time at which the redemption was updated in the system enum: - YYYY-MM-DDThh:mm:ssZ format: date-time redemption_id: type: integer description: Unique ID of the redemption that has been created redemption_tracking_code: type: string description: Code that a user must submit at the POS to receive the redeemed reward expiring_at: type: string description: Date/time when the redemption_tracking_code expires and the user cannot use it at the POS enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Returned in the response of the [User Account History](/docs/dev-portal-mobile/f340773e6bef7-user-account-history) API. title: Event Details (Object) x-stoplight: id: a44caeddc8412 games: title: Games (Array Object) x-stoplight: id: 4mrgpodjouhpb type: array description: A paginated list of active games available for the brand, along with detailed information for each game. items: x-stoplight: id: 6vw5kq92w2hyf type: object properties: id: type: string x-stoplight: id: lmpwcytq6fwlw description: Unique Punchh identifier for the game configuration name: type: string x-stoplight: id: 0p7e7fm39qk1k description: Display name of the game (e.g., "Spin Wheel 1") description: type: string x-stoplight: id: h7mltk1dbo7c0 description: Brief summary of the game url: type: string x-stoplight: id: ya00ps1c1c4it description: Primary URL that brand's app must use to launch the game channel: type: string x-stoplight: id: mo8kq1e1fb8x0 description: 'Channel(s) where the game is intended to be displayed or played. Possible values: * mobile: Returns games available on mobile. * web: Returns games available on the web. * mobile_web: Returns games available on both mobile and web.' status: type: string x-stoplight: id: icy8s3fjs86nb description: Current status of the game configuration (e.g., active). created_at: type: string x-stoplight: id: c3f9tynsqep6f description: Date and time when the game configuration was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format updated_at: type: string x-stoplight: id: 5ms5jk0n31mn1 description: Date and time when the game configuration was last updated, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format cover_img: type: string x-stoplight: id: cover-img-games x-nullable: true description: The URL of the branded cover/intro image for the game. Used by brand mobile app to display the image on the games list and details screens. Returns null if no cover image has been uploaded, or if the game's channel is set to Web only. Only populated for games with a channel of `mobile` and `mobile_web` Gift-Card-Object: type: object title: Gift Card (Object) x-stoplight: id: 2eff352e87b8c properties: card_background_image: type: string description: URL of the image that is displayed as the gift card background in the app of a business card_number: type: string description: Unique gift card number as issued by the gift card processor (e.g., Aloha, Vantiv, Valutec, etc.) used by the business epin: type: string description: Security PIN associated with a gift card. A "null" value indicates that no epin is associated with the gift card. usb_scannable_card_number: type: string description: Easily scannable form of a gift card's number by adding ~ and ^ as prefix and suffix, respectively, to the gift card number. This is done to avoid issues at certain POS systems while scanning the QR code. created_at: type: string description: Date/time when the gift card was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ format: date-time design_id: type: integer description: Identification of a particular gift card design selected by the user while purchasing a gift card preferred: type: boolean description: A "true" value for a gift card indicates that a user has selected it to be the preferred gift card for payment. name: description: Name of the card that has been assigned by the user. In case of purchase of a gift card from an app, users cannot add a name to the card. A "null" value indicates that a name has not been added to the card. A name can be added later using the [Update Gift Cards](/docs/dev-portal-mobile/5a6da59e09732-update-gift-cards) API. x-nullable: true last_fetched_amount: type: number description: The balance amount of a gift card last fetched from the gift card processor format: float last_fetched_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: The last time the balance amount of a gift card was fetched from the gift card processor. This indicates when it was cached. status: type: string description: The status of a gift card. The only value exposed to a gift card in the app is "active". Other statuses are maintained for internal tracking. updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the gift card was updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format users: $ref: '#/components/schemas/User-object' uuid: type: string description: Unique ID of the gift card issued by and maintained in the Punchh system gift_card_id: type: integer description: Unique ID assigned to each gift card by the Punchh system. This ID will be passed in the push notification payload to app clients in the key `gc`. By mapping this, the app client can fetch the updated balance of a particular gift card. auto_reload_enabled: type: boolean description: Whether auto-reload is enabled for a gift card or not gc_user_auto_reload_threshold_amount: type: number format: float description: Threshold amount below which a gift card becomes eligible for auto-reload gc_user_auto_reload_default_amount: type: number format: float description: Default amount with which a gift card would be auto-reloaded gc_user_auto_reload_preferred_payment: type: string x-stoplight: id: vi0chaw55927t description: UUID of the preferred payment card, which is used for making payments when auto-reloading the gift card gift-card-default-amounts: title: Gift Card Default Amounts (Object) x-stoplight: id: lgdqs5iworoa5 type: object x-examples: [] description: 'The object provides default values for gift card purchase amount options, reload amount options, auto-reload amount options, and balance threshold amount options, as well as their respective default selections. ' properties: gift_card_purchase_amounts_options: type: object x-stoplight: id: vkx0gyk0megkr description: Contains a set of predefined purchase amount options that users can select when purchasing a gift card. Each option within this object provides a specific amount, offering users convenient choices without requiring manual input. properties: gift_card_purchase_amount_1: type: integer x-stoplight: id: 3zbksxqoyqydk description: First option for the amount a user can choose when purchasing a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_purchase_amount_2: type: integer x-stoplight: id: tnxg2grbqzep5 description: Second option for the amount a user can choose when purchasing a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_purchase_amount_3: type: integer x-stoplight: id: 211ka1ebfmgri description: Third option for the amount a user can choose when purchasing a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_purchase_default_option: type: integer x-stoplight: id: uw99n6g4erbhn description: Default selected amount, if the user does not choose an option, for gift card purchases from the available purchase amount options. Contact your Punchh representative to update this Punchh platform configuration. gift_card_reload_amounts_options: type: object x-stoplight: id: elo6lm7b90nqw description: Contains a set of predefined amount options that users can select when reloading a gift card. Each option within this object provides a specific amount, offering users convenient choices without requiring manual input. properties: gift_card_reload_amount_1: type: integer x-stoplight: id: p2cx85bibekkn description: First option for reloading a gift card with a specified amount. Contact your Punchh representative to update this Punchh platform configuration. gift_card_reload_amount_2: type: integer x-stoplight: id: uvbz3awkfu5gn description: Second option for reloading a gift card with a specified amount. Contact your Punchh representative to update this Punchh platform configuration. gift_card_reload_amount_3: type: integer x-stoplight: id: ei06dgkg6tits description: Third option for reloading a gift card with a specified amount. Contact your Punchh representative to update this Punchh platform configuration. gift_card_reload_default_option: type: integer x-stoplight: id: ml5kfyatlyku6 description: Default selected amount, if the user does not choose an option, for reloading a gift card from the available reload amount options. Contact your Punchh representative to update this Punchh platform configuration. gift_card_auto_reload_amounts_options: type: object x-stoplight: id: hrvjsd7mlziab description: Contains a set of predefined amount options that users can select when setting up auto-reload for their gift card in the mobile app. Each option within this object provides a specific amount, offering users convenient choices without requiring manual input. properties: gift_card_auto_reload_amount_1: type: integer x-stoplight: id: m39x0bsvkg5nv description: First option for the amount a user can set for automatic reloading of a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_auto_reload_amount_2: type: integer x-stoplight: id: 6afwvs012sovr description: Second option for the amount a user can set for automatic reloading of a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_auto_reload_amount_3: type: integer x-stoplight: id: qubb30lezgdki description: Third option for the amount a user can set for automatic reloading of a gift card. Contact your Punchh representative to update this Punchh platform configuration. gift_card_auto_reload_default_option: type: integer x-stoplight: id: sh0csaujqb3fr description: Default selected amount, if the user does not choose an option, for auto-reloading a gift card from the available auto-reload amount options. Contact your Punchh representative to update this Punchh platform configuration. balance_threshold_amounts_options: type: object x-stoplight: id: 9ec0vk4od29km description: Contains a set of predefined amount options that users can select when setting a threshold amount for auto-reloading their gift card in the mobile app. Each option within this object specifies an amount, offering users convenient choices without requiring manual input. properties: balance_threshold_amount_1: type: integer x-stoplight: id: z98owwml05omg description: First option for the threshold balance amount. When set, a gift card is eligible to be auto-reloaded if its balance is less than this threshold amount. Contact your Punchh representative to update this Punchh platform configuration. balance_threshold_amount_2: type: integer x-stoplight: id: uibtdpafa7otf description: Second option for the threshold balance amount. When set, a gift card is eligible to be auto-reloaded if its balance is less than this threshold amount. Contact your Punchh representative to update this Punchh platform configuration. balance_threshold_amount_3: type: integer x-stoplight: id: phezshfaz8d6f description: Third option for the threshold balance amount. When set, a gift card is eligible to be auto-reloaded if its balance is less than this threshold amount. Contact your Punchh representative to update this Punchh platform configuration. balance_threshold_default_option: type: integer x-stoplight: id: j2lzekoj66fzk description: Default selected threshold balance amount from the available balance threshold amount options for auto-reloading a gift card. Contact your Punchh representative to update this Punchh platform configuration. 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```json\n{\n \"type\": \"image\",\n \"url\"\ : \"IMAGE_URL_GOES_HERE\",\n \"alt_text\": \"Fries\",\n \"initial_frame\": \"\"\n}\n```\n" title: Hero Content (Object) 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. x-stoplight: id: 4779761c509cd Locations: type: array x-examples: Example: - address: ADDRESS_GOES_HERE brand: nil city: Ann Arbor country: United States external_store_id: '' latitude: '41.707145' location_id: 310956 loc_email: '' longitude: '-93.582188' name: Ann Arbor online_order_url: '' phone_number: '' post_code: ' 48104' state: Michigan store_number: ' 4' store_tags: Ordering store_times: - day: Mon start_time: nil end_time: nil - day: Tue start_time: nil end_time: nil - day: Wed start_time: nil end_time: nil - day: Thu start_time: nil end_time: nil - day: Fri start_time: nil end_time: nil - day: Sat start_time: nil end_time: nil - day: Sun start_time: nil end_time: nil time_zone: America/New_York updated_at: '2019-10-21T06:19:42-04:00' status: approved franchisee_id: 570 ncr_store_id: '' enable_daily_redemption_report: false enable_weekly_redemption_report: false checkin_evidenced_by: image guest_identity_code_type: qrcode title: Locations (Array Object) description: 'Returns a list of business locations. Each location object within the Locations array contains information about a specific business location. ' x-internal: false x-stoplight: id: c1e917a05275b items: type: object properties: address: type: string description: Full address of a particular business location brand: type: string description: Brand name of a subcategory of a business. A parent business may own multiple brands under one umbrella company. For example, Yum! Brands, Inc. owns KFC, Pizza Hut, and Taco Bell. city: type: string description: City of a particular business location country: type: string description: Country of a particular business location external_store_id: type: string description: External identifier configured in the Punchh platform under location attributes via Store Locations > All Store Locations > [choose location] > POS > External POS Store Identifier latitude: type: number description: Latitude coordinate of a particular business location format: float location_id: type: integer description: Unique ID of a particular business location. This is generated by Punchh. longitude: type: number description: Longitude coordinate of a particular business location format: float name: type: string description: Name of a particular business location phone_number: type: string description: Phone number of a particular business location loc_mail: type: string description: Email address of a particular business location post_code: type: string description: Zip code of a particular business location state: type: string description: State where a particular business is located store_number: type: string description: The store number where the check-in occurred store_tags: type: string description: Tags that provide additional details about a particular business location store_times: type: array description: Returns details about the business hours of particular location items: type: object properties: day: type: string description: Day of week when a store is open for business start_time: type: string description: Time of day when a store opens format: time end_time: type: string description: Time of day when a store closes format: time time_zone: type: string description: Time zone in which the business is located updated_at: type: string format: date-time description: Date/time the when location was last updated in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ status: type: string description: Whether the location is enabled for check-ins or not. `approved` means enabled for check-ins, and `disapproved` means disabled for check-ins. franchisee_id: type: integer description: Unique ID of the franchisee who owns the location. This is generated by Punchh. enable_weekly_redemption_report: type: boolean description: Enables sharing the weekly redemption report to the location email (applicable only for the franchisee model) checkin_evidenced_by: type: string description: The method of check-in used by a user (e.g., barcode, qr_code, receipt_image, etc.). A blank string indicates the default value of the business. guest_identity_code_type: type: string description: The POS scanner type used to identify the user at the POS (e.g., barcode, qr_code, etc.). A blank string indicates the default value of the business. enable_pos_monitoring: type: boolean description: Whether POS monitoring has been enabled for the location or not. This is used by the POS integration team members. generate_barcodes: type: boolean description: Whether barcodes are generated on the receipt or not alternate_store_number: type: string x-stoplight: id: k1wmwag5ki6i9 description: Alphanumeric alternate store identifier for a specific location, as provided by the business. This information is configured in the Punchh platform under Store Locations > All Store Locations > [choose location] > Location > Alternate Store Number/Identifier. additional_url: type: array x-stoplight: id: vpig2ui4hrfxs items: x-stoplight: id: 3xo8afl94lww1 type: object properties: label: type: string x-stoplight: id: zqjxlm5hwc1l8 description: Label for the additional URL. url: type: string x-stoplight: id: n654fpo983ucb description: Custom URL configured for the additional URL. This URL can link to a location-specific brand webpage, such as catering information, discounts, private events, reservations, or other custom content beyond the standard call, order, and directions links. This information is configured in the Punchh platform under Store Locations > All Store Locations > [choose location] > Mobile App. single_scan_type: type: string x-stoplight: id: yyr95bc0qpv8u description: "Determines the type of code the mobile app should display for completing a single-scan\ \ transaction at a specific POS location. Possible values:\n- none: No scan code is displayed\ \ or used. \n- short_token: A short code (deprecated)\n- long_token: A longer code (deprecated)\n\ - single_scan_code: A specific code generated for a one-time scan transaction. See [Single\ \ Scan Flow](https://developers.partech.com/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)" hide_in_store_tipping: type: boolean x-stoplight: id: 0197dpgz884wh description: Determines whether the mobile app should hide the tip option for Single-Scan Flow at a location. Only applies to businesses that have enabled in-store tipping via Single-Scan Flow. default: false hide_in_store_cc_payment: type: boolean x-stoplight: id: ni7rmm0ouoz5x description: Determines whether the mobile app should hide the option to pay with a credit card (CC) for Single-Scan Flow at a location. Only applies to businesses that have enabled in-store credit card payment via Single-Scan Flow default: false hide_ssf_gift_card: type: boolean x-stoplight: id: 05psjinz5w99p description: Determines whether the mobile app should hide the option to pay with a gift card for Single-Scan Flow at a location. Only applies to businesses that have enabled gift card payment via Single-Scan Flow. default: false multiple_redemption_on_location: type: boolean x-stoplight: id: 2nh7ev8pc1w2e description: Indicates whether the multiple redemptions feature is enabled for a particular location. You can access this setting for a location on the Punchh platform under Store Locations > All Store Locations > [choose location] > Location > Allow Location for Multiple Redemption. guest_identification_type: type: string description: "Indicates whether loyalty users can be identified using a short code at locations\ \ that do not support the single scan flow. Possible values: \n- When set to restrict_pay_allow_lookup,\ \ the location supports user lookup using a short code, and SSF-based payments are disabled.\ \ \n- When set to restrict_lookup, user lookup using a short code is not allowed.\nContact\ \ your Punchh representative to update this Punchh platform configuration.\n" Membership-Levels: type: array items: type: object properties: background_image_url: type: string description: URL of the image that can be displayed in the app. As the URL may change with the membership level, the image can be changed accordingly. points_multiplier: type: number format: float description: Factor (rate) with which points accumulate for a user. For example, if the points multiplier for a particular membership level is 1, the user will get 1 point for every $1 spent. If the points multiplier is 2, the user will get 2 points for every $1 spent. membership_level_id: type: integer description: Unique ID of the membership level name: type: string description: Membership level name that is displayed in the app description: type: string description: Description of a particular membership level. This can be displayed in the app (e.g., "Earn twice the points for every dollar you spend.") maximum_points: type: integer description: Upper threshold of a membership level in terms of points minimum_points: type: integer description: Lower threshold of a membership level in terms of points currency_earned: type: number description: When accumulated points reach the `points_conversion_threshold`, they are converted to a dollar value defined by `currency_earned`. A value of 10 means that accumulated points will be converted to banked rewards in batches of $10. format: float points_conversion_threshold: type: integer description: Number of points required to get converted to banked rewards x-examples: [] title: Membership Levels (Array Object) x-stoplight: id: f51be9319f856 description: The object contains details about each membership tier in a loyalty program menu-items: type: array title: Menu Items (Array Object) x-stoplight: id: 5e6ad0a980e1c description: This object used in the API request contains one or more menu items added to an order. It is mandatory to provide an array of menu items. See [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh) items: x-stoplight: id: wjmxzsnncbdfs type: object properties: item_name: type: string x-stoplight: id: u7y4uxds5t8kd description: Name of the menu item item_qty: type: integer x-stoplight: id: p0uk3mnn8409h 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 x-stoplight: id: ovtybina1ueqw 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. format: float menu_item_type: type: string x-stoplight: id: aerjo6zjehk6u description: 'The classification of the item. Choose from the following types based on the item: M - Menu item ( + or - ) D - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call 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. T - Tax item. Taxes of all sorts P - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the order)' menu_item_id: type: integer x-stoplight: id: 8amg3kbrvh2l3 description: Unique identifier for the item menu_family: type: string x-stoplight: id: lqjz4lia32cbw 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 x-stoplight: id: y54dcl0ygtdv7 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 x-stoplight: id: tb198p855rg4u 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 response-menu-items: title: Menu Items (Array Object) x-stoplight: id: lsmmevd84zcsf type: array items: x-stoplight: id: 12qjoo9ej1acb type: object properties: item_name: type: string x-stoplight: id: axqs34w91dcg6 description: Name of the menu item item_qty: type: string x-stoplight: id: tjf2haq05zi5g description: Quantity ordered by the customer. If the item is a modifier (such as extra cheese on a pizza base item), 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 x-stoplight: id: uw5i7i1owa7zn format: float 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. This value is always represented as a positive number, even when the item is a discount. menu_item_type: type: string x-stoplight: id: 3bhm3vrzg0m7y description: 'The classification based on the item type: M - Menu item ( + or - ) D - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call 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. T - Tax item. Taxes of all sorts P - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the order)' menu_item_id: type: integer x-stoplight: id: 1p9gohm0bhxos description: Unique identifier for the item menu_family: type: string x-stoplight: id: 75hzwgdhqqf2m description: The family that the item belongs to. The family is the subcategory for the item. A blank value means the item does not belong to a family. menu_major_group: type: string x-stoplight: id: bfj7s8t3n78jk description: The major group that the item belongs to. The major group is the parent category for the item. A blank value means the item does not belong to a major group. serial_number: type: string x-stoplight: id: 92xkqaijbrjds description: A serialized number that differentiates distinct menu items on a receipt. The value identifies 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. description: Returns a list of menu items in the API response messages: type: object description: 'Returned in response to the [Fetch Messages](/docs/dev-portal-mobile/e9485ca96ff55-fetch-messages) API ' x-examples: [] title: Messages (Array Object) x-stoplight: id: 4e7b944f87362 properties: messages: type: array items: type: object properties: background_content: $ref: '#/components/schemas/background-content' body: type: string description: 'The text content of a rich message ' cta: $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](https://en.wikipedia.org/wiki/ISO_8601) format,\ \ when the notification should be rendered by the application client. This is 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.\n\n\ 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.\n\nThe values of take_down_time and launch_time parameters\ \ are determined when configuring campaign announcements. To set up a campaign announcement\ \ in the Punchh platform, in the left navigation pane, navigate to Loyalty Program\ \ > App Message Composer, and click Add App Message. In the New Announcement\ \ page, specify the date and time of the launch in the Launch Time field and\ \ the take down time in the Take Down Time field. \n\nOnce configured, these\ \ values will be displayed in the `launch_time` and `take_down_time` parameters respectively\ \ when the messages are fetched via this Mobile API." 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](https://en.wikipedia.org/wiki/ISO_8601) format,\ \ when the mobile client should stop rendering the rich message in the app.\n\nIf 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.\n\nThe values of take_down_time and launch_time parameters\ \ are determined when configuring campaign announcements. To set up a campaign announcement\ \ in the Punchh platform, in the left navigation pane, navigate to Loyalty Program\ \ > App Message Composer, and click Add App Message. In the New Announcement\ \ page, specify the date and time of the launch in the Launch Time field and\ \ the take down time in the Take Down Time field. \n\nOnce configured, these\ \ values will be displayed in the `launch_time` and `take_down_time` parameters respectively\ \ when the messages are fetched via this Mobile API." 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 ' read_at: type: string x-stoplight: id: ten5f40qgu98e format: date-time description: Date/time when the message was read, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. To mark a message read, you must call the [Mark Messages As Read](/docs/dev-portal-mobile/899a3394bf4e6-mark-messages-as-read) API. The `read_at` parameter value remains null until the message is explicitly marked as read using the appropriate API. enum: - YYYY-MM-DDThh:mm:ssZ created_at: type: string x-stoplight: id: 04jvdgbo8cmcv format: date-time description: Date/time when the message was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format enum: - YYYY-MM-DDThh:mm:ssZ deleted_at: type: string x-stoplight: id: jynu306dbfuc9 format: date-time description: Date/time when the message was deleted, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. To delete the message, you must call the [Delete Messages](/docs/dev-portal-mobile/8dbb3bf79ad94-delete-messages) API. Once deleted, the `deleted_at` parameter will return a value in the API response. enum: - YYYY-MM-DDThh:mm:ssZ UserBalanceMessages: type: object description: 'Returned in response to the [Fetch User Balance](/docs/dev-portal-mobile/fb962621d8f10-fetch-user-balance) API ' title: User Balance Messages (Array Object) x-stoplight: id: 3ca96c1a6bcbf properties: messages: type: array items: type: object properties: background_content: $ref: '#/components/schemas/background-content' body: type: string description: 'The text content of a rich message ' cta: $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](https://en.wikipedia.org/wiki/ISO_8601) format,\ \ when the notification should be rendered by the application client. This is 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.\n\n\ 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.\n\nThe values of take_down_time and launch_time parameters\ \ are determined when configuring campaign announcements. To set up a campaign announcement\ \ in the Punchh platform, in the left navigation pane, navigate to Loyalty Program\ \ > App Message Composer, and click Add App Message. In the New Announcement\ \ page, specify the date and time of the launch in the Launch Time field and\ \ the take down time in the Take Down Time field. \n\nOnce configured, these\ \ values will be displayed in the `launch_time` and `take_down_time` parameters respectively\ \ when the messages are fetched via this Mobile API." 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](https://en.wikipedia.org/wiki/ISO_8601) format,\ \ when the mobile client should stop rendering the rich message in the app.\n\nIf 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.\n\nThe values of take_down_time and launch_time parameters\ \ are determined when configuring campaign announcements. To set up a campaign announcement\ \ in the Punchh platform, in the left navigation pane, navigate to Loyalty Program\ \ > App Message Composer, and click Add App Message. In the New Announcement\ \ page, specify the date and time of the launch in the Launch Time field and\ \ the take down time in the Take Down Time field. \n\nOnce configured, these\ \ values will be displayed in the `launch_time` and `take_down_time` parameters respectively\ \ when the messages are fetched via this Mobile API." 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 ' read_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the message was read, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the message was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format deleted_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the message was deleted, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format multiple-redemptions: title: Multiple Redemptions (Object) x-stoplight: id: pc040hb7vwe08 type: object description: Lists the Punchh platform settings for multiple redemptions for the business. This object is returned in the API response if the `multiple_redemptions_enabled` response parameter is set to true in the Program Meta API for the business. properties: auto_redemption: type: boolean x-stoplight: id: o9qvner9yfrsi description: Indicates whether auto-redemption of discounts is enabled for the business enable_discount_locking: type: boolean x-stoplight: id: qgflsm4wta2ic description: Indicates whether reward locking on the transaction is enabled for the business enable_auto_unlock: type: boolean x-stoplight: id: 8czj7kyivckcc description: Indicates whether auto-unlocking of the guest account after a time interval is enabled for the business max_redemptions_in_transaction: type: integer x-stoplight: id: 6advmswmvdfee description: Maximum number of discounts that can be applied in a single transaction auto_redemption_discounts: type: array x-stoplight: id: 8vimqhjjjfo63 description: 'Discount categories eligible for the auto-application of discounts. Possible values: offer, subscription, fuel_reward, discount_amount' items: x-stoplight: id: 9au9bp5c76wzf type: string allow_multiple_redemption_on_item: type: boolean x-stoplight: id: t09lybhqu48zz description: Indicates whether multiple discounts can be stacked on a menu item for the business allow_qualifying_items_reused: type: boolean x-stoplight: id: di92haxdegs17 description: Indicates whether the reuse of qualifier items for the application of multiple discounts is enabled for the business discount_processing_strategy: type: string x-stoplight: id: 462rf5g1dao5n description: 'Condition that determines the order in which discounts are applied to a transaction. Possible value: date_of_expiry' processing_priority_by_discount_type: type: array x-stoplight: id: a894wxabxbr46 description: 'Determines the order in which discounts are applied to a transaction based on the discount type. Possible values: reward, promo_coupon, subscription, discount_amount' items: x-stoplight: id: c89kmd7mxprz9 type: string processing_priority_by_acquisition_type: type: array x-stoplight: id: 14x90y5zeya2s description: Determines the order in which discounts are applied to a transaction based on the acquisition type items: x-stoplight: id: 27pnqeartgdiw type: object properties: code: type: string x-stoplight: id: gahvrtmoowfyw description: 'Type of acquisition. Possible values: loyalty, pre_purchased, offer, promo_coupon' priority: type: integer x-stoplight: id: ioc5j5tvdxipf description: Order in which a discount of an acquisition type is applied in a transaction (lower numbers indicate higher priority) multiplication_factor: type: integer x-stoplight: id: 9n1uxziyivb1q description: Maximum number of discount units per category that can be applied in a transaction exclude_interoperability_strategy_between: type: array x-stoplight: id: f1rp7wsenihj8 description: 'Defines the rules for excluding interoperability between discounts of different acquisition types. The parameter value is a pair of pipe-separated values that specify which discounts from an acquisition type cannot be combined with discounts from another acquisition type. For example, the parameter value `offer|loyalty` means an offer discount cannot be combined with a loyalty discount at the time of redemption. Possible values are any combination of the following: loyalty, pre_purchased, offer, promo_coupon' items: x-stoplight: id: 3ydk20bk8j8fc type: string auto_unlock_duration: type: integer x-stoplight: id: ioqqb1t3mfdkv description: Time interval (in minutes) after which a guest account will be automatically unlocked for a transaction Notifications: type: array description: Returns the details of the notifications received by a user. A maximum of 10 notifications will be fetched. title: Notifications (Array Object) 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 x-stoplight: id: c1638b1a83f29 pagination: title: Pagination (Object) x-stoplight: id: tgyhdl9oiowfr type: object description: Returns pagination information of the results. properties: current_page: type: integer x-stoplight: id: u3w44a3aeb9lc description: Page number of the results currently being returned by the API per_page: type: integer x-stoplight: id: 3fzvsml7u9cpv description: Number of items returned per page in the response total_count: type: integer x-stoplight: id: ypgff6iq9dgqx description: Total number of records available across all pages total_pages: type: integer x-stoplight: id: kprld26pw8gae description: Total number of pages required to display all available records has_next_page: type: boolean x-stoplight: id: 3ax9n5j7i0e7i description: Indicates whether more pages are available after the current page has_previous_page: type: boolean x-stoplight: id: qshbr9pjl4b3c description: Indicates whether there are pages available before the current page payment_credential: title: Payment Credential (Object) x-stoplight: id: yz9yasmzl1jck type: object description: Contains settings related to the payment adapter, recurring payment type, and passcode x-examples: application/json: adapter_code: ADAPTER_CODE_GOES_HERE enable_recurring_payments: true enable_passcode_for_payment: true properties: adapter_code: type: string description: Name of the payment processor/gateway. Valid value is par_payment. enable_recurring_payments: type: boolean description: Whether a business has enabled recurring payments for the selected payment adapter enable_passcode_for_payment: type: boolean description: Whether a business has enabled the passcode for payments profile_field_answers: title: Profile Field Answers (Object) x-stoplight: id: lme68mm8va3zz type: 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. 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). profile_field_questions-Object: type: array items: type: object properties: question: type: string description: Question that can be displayed to a user in the app answer_options: type: string description: Answer options that can be displayed to a user for a question in the app data_type: type: string description: 'Data type of answers that can be accepted for a question. The values can be: - SINGLE_LINE : "text", - MULTIPLE_LINE : "text", - DATE_TIME => "datetime-local" - NUMBER => "number", - EMAIL => "email", - PHONE => "tel", - RATING => "range", - MCMA => "multiple-select",
This type can accept multiple answers for a multiple-choice question. - MCSA => "select",
This type can accept only a single answer for a multiple-choice question.' hint: type: string description: Hint that can be displayed for a question to help users answer it mandatory: type: boolean description: A true value indicates that it is mandatory to answer the question. size: type: integer description: Maximum number of options that can be provided in the answer set upf: type: string description: User profile code or question code. Answers are 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''. Each profile field (upf0 - upf24) corresponds to a line from the configuration in the Punchh platform. updatable: type: boolean description: A true value indicates that the answers can be updated. title: Profile Field Questions (Array Object) x-stoplight: id: f347f00a28a60 description: '' redeemable: type: array items: type: object properties: redeemable_image_url: type: string description: URL of the image displayed in the app to depict the redeemable redeemable_properties: type: array description: Properties such as "Merchandise", "Food Item", etc. can be added to a particular redeemable. items: type: string redeemable_id: type: integer description: Unique ID that identifies a redeemable in the system 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. points_required_to_redeem: type: integer description: Number of points required to redeem a particular 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. title: Redeemable (Array Object) x-stoplight: id: 7658402f497c2 description: Lists the redeemables and their details defined in the Punchh system redemption_details: type: object description: 'Returns the details of a redemption done by a user ' properties: redemption_status: type: string description: 'Status of the redemption. The values returned can be: - redeemable: The redemption can be redeemed at the POS. - expired: The redemption has expired and becomes unusable for the user. - honored: The redemption has already been processed successfully and redeemed by the user at a POS. - cancelled: The redemption can be voided by a user by approaching the POS if a redemption is done by mistake and the user wants to cancel it.' created_at: type: string description: 'Date/time when the redemption was created in the system ' redeemable_id: type: integer description: 'Unique ID of the redeemable ' redeemable_name: type: string description: 'Name of the redeemable ' redeemed_value: type: string description: 'For a business with banked currency, a currency value will be returned (e.g., 10 would mean $10). For a business without banked currency, a points value will be returned (e.g., 10 would mean 10 points).' redemption_image_url: type: string description: 'URL of the image displayed in the app to depict the redeemable ' redemption_message: type: string description: 'A descriptive message that tells a user what the user has redeemed ' redeemable_description: type: string description: 'Description of the redeemable ' updated_at: type: string description: 'Date/time at which the redemption was updated in the system ' redemption_id: type: integer description: 'Unique ID of the redemption that has been created ' redemption_tracking_code: type: string description: 'Code that a user must submit at the POS to receive the redeemed reward ' expiring_at: type: string description: Date/time when the redemption_tracking_code expires and the user cannot use it at the POS location_id: type: integer description: ID of the location associated with the with the redemption (where the redemption code is generated). If no location ID is provided, then the ID for the default location is returned. title: Redemption Details (Object) x-stoplight: id: bc87eb1cec331 rewards: type: array description: Contains information about the available rewards of the user title: Rewards (Array Object) x-stoplight: id: 593a939bbb6fa items: x-stoplight: id: boujhknpz5coc type: object properties: becomes_available_at: type: string x-stoplight: id: im795luv5su27 description: Date/time at which the reward becomes redeemable by a user format: date-time campaign_type: type: string x-stoplight: id: 7f6xlqvvehpqk description: Type of campaign through which a user received a reward. Currently, the only possible value is "loyalty". A null value indicates that the user did not get the reward through a campaign. created_at: type: string x-stoplight: id: os20mdeoqfq3z format: date-time description: Date/time when the reward was created for a user in the system description: type: string x-stoplight: id: 6hg1xma6nl1w4 description: Description of the reward discount_channel: type: string x-stoplight: id: 0ti076e2v9ohc description: 'Channels where the reward can be used. Possible values are: - online_only - online orders - offline_only - POS - all - both' discount_amount: type: integer x-stoplight: id: e7waqx8jk4ulk description: Discount amount associated with the reward reward_image_url: type: string x-stoplight: id: v0wl0df7rs844 description: URL of the image displayed in the app to depict the reward name: type: string x-stoplight: id: e2ho1o5jtdjin description: Name of the reward read_at: type: string x-stoplight: id: p3uv2kyj3085t format: date-time description: Date/time when the reward notification was read by a user in the app reward_properties: type: string x-stoplight: id: v4jg31ks5gly0 description: Additional properties of the reward (e.g., "merchandise", "order ahead", "promo", etc.) that can be configured in the Punchh platform store_numbers: type: array x-stoplight: id: eu3v3y9m8zkxi description: Store numbers of all locations where the reward can be redeemed. An empty array indicates that the reward can be redeemed at any location. items: x-stoplight: id: 2cijorr4t6693 type: string franchisee_id: type: integer x-stoplight: id: aqdjczff8wolf description: ID of the franchisee who credited the reward to the user's account. This could be done through a campaign or admin generosity. meta_data: type: string x-stoplight: id: zzj946kbbq1xw 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_created_at: type: string x-stoplight: id: mlwoe89xeubtv format: date-time description: Date/time when the redeemable was created in the Punchh platform reward_id: type: integer x-stoplight: id: rvc7fk1jyance format: int64 description: Unique ID of the reward expiring_at: type: string x-stoplight: id: 40snv09u8jow8 description: Date/time when the reward expires format: date-time redemption_details: $ref: '#/components/schemas/redemption_details' auto_select: type: boolean x-stoplight: id: supgkji7b6rag description: Whether the offer is enabled for auto-redemption or not subscription: type: object description: 'The object contains details related to subscription configurations, including subscription cancellation reasons for the business. The subscription cancellation reasons are configured in the Punchh platform under Wallet and Passes > Subscription Cancellation Reasons. Note: If the option to enable meta cache update on request is not enabled in the Punchh platform, the API will not return any subscription cancellation reasons in the Program Meta API response. Contact your Punchh representative to update this Punchh platform configuration.' title: Subscriptions (Object) x-examples: application/json: subscriptions: subscription_cancellation_reasons: - component_code: Price cancellation_reason_id: 1 cancellation_reason: It is expensive - component_code: 'Cancel ' cancellation_reason_id: 3 cancellation_reason: Reason - component_code: code cancellation_reason_id: 6 cancellation_reason: reason enable_cancellation_feedback: true cancellation_feedback_placeholder: Enter Additional Feedback If Any payment_disclaimer_text: This is payment disclaimer text. terms_and_conditions: These are terms and conditions. properties: subscription_cancellation_reasons: type: array description: Different cancellation reasons that the business has configured and guests can select from within the mobile app when cancelling a subscription items: type: object properties: component_code: type: string description: This is the business-defined component code, which reflects the category of a cancellation reason. This may or may not be shown on the mobile app per the discretion of the business. cancellation_reason_id: type: integer description: System-generated unique ID of the business-defined cancellation reason cancellation_reason: type: string description: Cancellation reason as configured by the business enable_cancellation_feedback: type: boolean description: 'Whether feedback will be collected when guests cancel a subscription or not ' cancellation_feedback_placeholder: type: string description: This is the cancellation feedback placeholder, which can be used by app developers as the title/label/placeholder text while capturing subjective feedback from guests when they cancel a subscription. payment_disclaimer_text: type: string description: Payment disclaimer text as configured in the Punchh platform terms_and_conditions: type: string description: Terms and conditions text as configured in the Punchh platform x-stoplight: id: 111a77a646d9e subscriptions_payment_credential: title: Subscriptions Payment Credential (Object) x-stoplight: id: 3xx7c32hkevh7 type: object description: 'Subscription-related payment details if a business uses Punchh''s native payment integration with payment processors to support subscription-related payments Note: If the business chooses not to use Punchh''s native integration with payment processors, the [Program Meta](/docs/dev-portal-mobile/2617bed9b0e8e-program-meta-api) API does not return the `subscriptions_payment_credential` object in the API response.' x-examples: application/json: adapter_code: par_payment enable_recurring_payments: false properties: adapter_code: type: string description: Code of the payment processor that will be used by the business for subscription-related payments. Possible values are no_adapter and par_payment. enable_recurring_payments: type: boolean description: Whether recurring payments capability is enabled for the business or not User-object: type: object description: Includes details about the users who are registered on a particular business x-examples: json/application: address: '' anniversary: '2013-02-16' avatar_remote_url: null birthday: '1999-01-01' city: '' communicable_email: test@example.com created_at: '2019-01-11T09:08:25Z' email: test@example.com email_verified: false facebook_signup: null apple_signup: null apple_uid: null favourite_location_ids: 306082,333070,304374 favourite_store_numbers: 12345,0604,1234 fb_uid: null first_name: FIRST_NAME_GOES_HERE gender: '' has_generated_fb_email: false last_name: LAST_NAME_GOES_HERE marketing_email_subscription: true marketing_pn_subscription: true migrate_status: false passcode_configured_for_giftcards: false phone: '1111111111' profile_field_answers: test1: Option 1 referral_code: REFERRAL_CODE_GOES_HERE referral_path: URL_GOES_HERE secondary_email: '' state: '' superuser: false terms_and_conditions: true title: '' updated_at: '2020-04-29T04:18:24Z' user_as_qrcode: QR_CODE_GOES_HERE user_code: P11111111 user_id: 111111111 preferred_locale: en user_relations: [] zip_code: null verification_mode: null sms_subscription: true apple_pass_url: APPLE_PASS_URL_GOES_HERE google_pass_url: GOOGLE_PASS_URL_GOES_HERE user_joined_at: '2019-01-11T09:08:25Z' title: User (Object) x-stoplight: id: 447c4c510a499 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: 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 in the mobile app using Facebook. For all subsequent logins, it returns a null 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: string description: Phone number of the user profile_field_answers: $ref: '#/components/schemas/profile_field_answers' referral_code: type: string description: Referral code of the user. A user can refer others to join the business loyalty program by sharing this referral code. When a referred user signs up and enters the shared referral code in the mobile app, this `referral_code` must be passed in the `invite_code` request parameter when calling the Sign up / Register API. 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/Apple 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 the 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: type: array description: Relatives of the user. Valid values are "kid" and "spouse". items: type: string enum: - kid - spouse 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 apple_pass_url: type: string format: uri description: URL that a user can use to download the user's associated loyalty Apple pass google_pass_url: type: string format: uri description: URL that a user can use to download the user's associated loyalty Google pass age_verified_status: type: boolean x-stoplight: id: ougfjyb55y0rf 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.' account_created_at: type: string x-stoplight: id: o07dhmip4epo0 format: date-time description: 'This value is set when a guest account is created on the Punchh Platform and varies depending on business configurations. For example: * If an eClub account is created with a historical registration date, that specific date is returned in this parameter. * If guest data is migrated from a previous platform and includes a registration date, the system creates the guest account with this registration date from the prior system, and the API returns that date in this parameter.' user_joined_at: type: string x-stoplight: id: kbj7omjru7mry format: date-time description: Date and time when the user became a loyalty member user-relation-attribute: title: User Relation Attributes (Object) x-stoplight: id: dtzj3oncqzeji type: object 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' description: 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. parameters: signature: schema: type: string default: '{{$$.env.signature}}' name: x-pch-digest in: header description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call required: true Accept: schema: type: string default: application/json name: Accept in: header description: Advertises which content types the client is able to understand required: true Accept-Language: schema: type: string default: en name: Accept-Language in: header description: Preferred language Authorization: schema: type: string default: Bearer ACCESS_TOKEN_GOES_HERE name: Authorization in: header description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`. required: true Content-Type: schema: type: string default: application/json name: Content-Type in: header description: Set this header to application/json. required: true client: schema: type: string name: client in: query description: OAuth client ID provided by the business required: true User-Agent: schema: type: string default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version) in: header name: User-Agent description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent). required: true Accept-Timezone: schema: type: string default: Etc/UTC name: Accept-Timezone in: header description: Used to indicate the time zone in which you would like the date and time information in the response to be formatted. punchh-app-device-id: schema: type: string default: APP_DEVICE_ID_GOES_HERE name: punchh-app-device-id in: header required: true description: The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the [sample code](/docs/dev-portal-mobile/56657769b1422-headers-and-caching#generating-the-punchh-app-device-id-header) to generate the punchh-app-device-id header. responses: Gift_card_object: description: '# "gift_card" Object |Attribute|Data Type|Description |----------|---------|---------- |`card_background_image`|String|URL of the image which is displayed as the Gift Card Background in the business'' app. |`card_number`|String|Unique Gift Card number as issued by the Gift Card Processor (e.g. Aloha, Vantiv, Valutec etc.) used by the business. |`epin`|String|Security Pin associated with Gift Card. A ''NULL'' value signifies there is no `epin` is associated with the Gift Card. |`usb_scannable_card_number`|String|Easily scannable form of a gift card''s number by adding ~ and ^ as prefix and suffix respectively to the gift card number. This is done to avoid trouble at certain POS systems while scanning the QR code. |`created_at`|Timestamp|Datetime when the gift card was created in the system in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. |`design_id`|Integer|Design ID is the identification of a particular gift card design selected by the user while purchasing a gift card. |`preferred`|Boolean|A "true" value for a gift card indicates that a user has selected it to be the preferred gift card for payment. |`name`|String|Name of the card that has been assigned by the user. In case of purchase of a gift card from app, users cannot add name to that card. A "null" value signifies that a name has not been added to the card. Name can be added later by using [Update Gift Card API](https://developers.punchh.com/v2/docs/update-gift-card). |`last_fetched_amount`|Float |The balance amount of a gift card last fetched from the Gift Card Processor. |`last_fetched_at`|Timestamp|The last time when the balance amount of a gift card was fetched from the Gift Card Processor. This indicates when it was cached. |`status`|String|The status of a gift card. The only value exposed to a gift card in the app is "active." Other statuses are maintained for internal tracking. |`updated_at`|Timestamp|Datetime when the gift card was updated in the system in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. |[users](http://developers.punchh.com/v2/page/users-gift-card) |Object|An object which contains a gift card user''s details such as user''s `user_id`, `first_name` etc. This returns details of all the users who are associated with a gift card. |`uuid`|String|Unique ID of the gift card issued by and maintained in the Punchh system. |`gift_card_id`|Integer|This is also a unique ID assigned to each gift card by the Punchh system. This ID will be passed in the Push Notification payload to app clients in the key `gc`. By mapping this, app client can fetch the updated balance of a particular gift card.' content: application/json: schema: type: object properties: card_background_image: type: string card_number: type: string epin: type: string usb_scannable_card_number: type: string created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time design_id: type: integer preferred: type: boolean name: type: string last_fetched_amount: type: number format: float last_fetched_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time status: type: string updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time users: type: array items: type: object properties: user_id: type: integer email: type: string first_name: type: string last_name: type: string fb_uid: type: string avatar_remote_url: type: string state: type: string uuid: type: string gift_card_id: type: integer examples: default: value: card_background_image: IMAGE_URL_GOES_HERE card_number: CARD_NUMBER_GOES_HERE epin: EPIN_GOES_HERE usb_scannable_card_number: CARD_NUMBER_GOES_HERE created_at: '2016-05-12T03:54:45-06:00' design_id: 1 preferred: false name: null last_fetched_amount: 10 last_fetched_at: '2016-05-12T03:54:45-06:00' status: active updated_at: '2016-05-12T03:54:45-06:00' users: - user_id: 111111111 email: test@example.com first_name: FIRST_NAME_GOES_HERE last_name: LAST_NAME_GOES_HERE fb_uid: null avatar_remote_url: null state: owner uuid: ID_GOES_HERE gift_card_id: ID_GOES_HERE Social_cause_response: description: '|Name|Type|Description |-----|-----|-------- |social_cause_id|Integer|Unique ID assigned to a Social Cause Campaign. This ID is generated by Punchh when the Social Cause campaign is created in the Punchh platform. |name|String|Name of a Social Cause Campaign as defined by the Business'' Admin while creating the social cause campaign in the Punchh platform. |description|String|Description of a Social Cause campaign as given by the Business'' Admin. |image_url|String|URL of the image that is attached to the Social Cause Campaign by the Business'' Admin. |tags|Object|Tags configured in the platform. |miscellaneous|String|Returns misc response string as configured in the Punchh platform |city|String|City |state|String|State |street|String|Street |zip|String|Zipcode |phone|String|Phone |email|String|email address |address|String|Address' content: application/json: schema: type: array items: type: object properties: social_cause_id: type: integer name: type: string description: type: string image_url: type: string tags: type: object miscellaneous: type: string city: type: string state: type: string street: type: string zip: type: string phone: type: string email: type: string address: type: string examples: default: value: - social_cause_id: 1 name: Test Campaign description: Test image_url: IMAGE_URL_GOES_HERE tags: [] miscellaneous: '' city: San Mateo state: CA street: ADDRESS_GOES_HERE zip: '94402' phone: '' email: '' address: ADDRESS_GOES_HERE redemption object: description: '# Redemption Detail Response |Name|Type|Description |-----|------|-------- |`redemption_status`|String|Status of the redemption. The values returned can be:1. redeemable: the redemption can be redeemed at the POS.2. expired: the redemption has expired and becomes unusable for the user.3. processed: the redemption has already been processed successfully and redeemed by the user at a POS.4. cancelled: the redemption can be voided by a user by approaching the POS in case a redemption is done by mistake and user wants to cancel it. |`created_at`|DateTime|Date and Time when the redemption was created in the system in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. |`redeemable_id`|Integer|Unique ID of the redeemable. |`redemption_image_url`|String|URL of the image depicting the redeemable. It can be displayed in the app. |`redemption_message`|String|A descriptive message which tells the user what they have redeemed. |`updated_at`|DateTime|Date and Time at which the redemption was updated in the system |`redemption_id`|Integer|Unique ID of the redemption that has been created. |`redemption_tracking_code`|String|Code which a user has to submit at the POS in order to receive the redeemed reward. |`expiring_at`|DateTime|Date and Time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, when the redemption_tracking_code expires and the user cannot use it at the POS. |`redeemable_name`|String|Name of the redeemable. |`redeemed_value`|Float||In case of a business with banked_currency, the value indicates currency amount redeemed by en user. E.g. a value 10 indicates a discount of $10. In case of a points based business, the value returned indicates the number of points redeemed by a user. E.g. a value 20 indicates 20 points. |`user`|Object|This object returns the information of the user who used the redemption code.Response includes:`first_name`, `last_name`, `email` and `avatar_remote_url`(URL of user''s profile image uploaded on an Online File Storage System. This will be used for users signed up using email. ' content: application/json: schema: type: object properties: redemption_status: type: string created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time redeemable_id: type: integer redeemable_name: type: string redeemed_value: type: number format: float redemption_image_url: type: string redemption_message: type: string redeemable_description: type: string updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time redemption_id: type: integer redemption_tracking_code: type: string expiring_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time examples: default: value: redemption_status: redeemable created_at: '2016-05-25T06:41:37-04:00' redeemable_id: null redemption_image_url: IMAGE_URL_GOES_HERE redemption_message: Message associated with the redemption. updated_at: '2016-05-25T06:41:37-04:00' redeemable_description: '' redemption_id: 1822896 redemption_tracking_code: '7246338' expiring_at: '2016-05-25T08:41:37-04:00' redeemable_name: null redeemed_value: 10 Checkin Object: description: '#checkin attributes |Name|Type|Description |--------|----------|--------- |checkin_id|Integer|ID of the loyalty checkin made by the user. |created_at|Timestamp|Datetime when the checkin was created in the system in ISO 8601 format. |current_membership_level|String|Membership Level of the user. |first_checkin|Boolean|Whether it is the First Checkin at Business or not? |location_id|Integer|ID of the location associated with the loyalty checkin. |pending_refresh|Boolean|Whether checkin is pending refresh or not? |points_earned|Integer|Number of points earned in the loyalty checkin. |store_number|String|The store number where the checkin occurred. |survey_url|String|URL of the survey presented to a user after they have done a checkin. |expiring_on|Date|Date on which the checkin will expire.' content: application/json: schema: type: object properties: created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Datetime when the checkin was created in the system in ISO 8601 format. current_membership_level: type: string description: Membership Level of the user. location_id: type: integer description: ID of the location associated with the loyalty checkin. pending_refresh: type: boolean description: Whether checkin is pending refresh or not? points_earned: type: integer description: Number of points earned in the loyalty checkin. store_number: type: string description: The store number where the checkin occurred. survey_url: type: string description: URL of the survey presented to a user after they have done a checkin. checkin_id: type: integer description: ID of the loyalty checkin made by the user. first_checkin: type: boolean description: Boolean Value indicating whether the checkin is user's first checkin or not expiring_on: type: string enum: - YYYY-MM-DD format: date description: Date on which the checkin will expire. examples: default: value: created_at: '2016-05-16T08:22:25-04:00' current_membership_level: Club Lite - Level 1 (0-400) location_id: 304252 pending_refresh: false points_earned: 72 store_number: '' survey_url: URL_GOES_HERE checkin_id: 11140692 first_checkin: false expiring_on: null 400 Bad Request (Invalid Language): description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_language: type: array items: type: string examples: default: value: errors: invalid_language: - Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es. 400 Bad Request (Client): description: '' content: application/json: schema: type: object properties: errors: type: object properties: missing_required_param: type: array items: type: string examples: default: value: errors: missing_required_param: - 'Required parameter missing or the value is empty: client' 412 Precondition Failed: description: '' content: application/json: schema: type: object properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: default: value: errors: invalid_signature: - Signature doesn't match. See [this topic](/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is) securitySchemes: {} x-ext-urls: {}