Punchh Meta & Version API

openapi: 3.2.0
info:
  title: Mobile Meta & Version 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.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Meta & Version
paths:
  /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 paymen

# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-meta-version-api-openapi.yml