Program Meta
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.
- Type: string
x -pch -digest requiredThe signature for the API call
- Type: string
Content - Type requiredSet this header to application/json.
- Type: string
Accept requiredAdvertises which content types the client is able to understand
- Type: string
User - Agent requiredUsed to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see User Agent.
- Type: string
client requiredOAuth client ID provided by the business
- Type: boolean
exclude _locations default:trueInclude 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.
- Type: object
200 - Type: string
accessibility _url URL of the business that provides information or support related to accessibility features
- Type: boolean
allow _guest _to _raise _reactivation 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.
- Type: boolean
allow _rating _in _feedback A value of "true" indicates that the app of the business supports ratings in feedback. Ratings can be either stars or emojis.
The default value is "false".
- Type: string
android _ga _code Android Google Analytics code of the program's Android app
- Type: string
android _geocode _api _key Android geolocation key
- Type: boolean
android _guest _account _deactivation Indicates whether a business has enabled account deactivation for its Android app users
- Type: string
android _guest _account _deletion Guest account deletion type that a business has configured for its Android app users. Possible values: none, direct, email
- Type: string
app _disclaimer Disclaimer about the app and its usage
- Type: string
app _feedback _url URL of the business where users can submit feedback related to the mobile app experience
- Type: string
auto _select _strategy 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.
- Type: array Banking Rules (Array Object)[]
banking _rules - Type: Base Redeemable (Object)
base _redeemable 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.
- Type: string
beacon _uuid Unique ID that identifies a beacon deployed at any location
- Type: integer
business _id Unique ID that identifies the business
- Type: string
business _name Name of the business
- Type: boolean
cancel _redemption Indicates whether the user can revoke (cancel) the generated redemption code from the brand's app
- Type: integer
card _redemption _value What a user gets when redeeming a completed card
- Type: string
careers _url URL of the careers page
- Type: string
catering _url URL of the catering page
- Type: string
challenges _disclaimer Disclaimer about the challenges module available in the app
- Type: string
checkin _evidenced _by Method of check-in used by a user (e.g., barcode, qr_code, receipt_image, etc.)
- Type: string
checkins _earn What a user earns as the result of a check-in. Values returned are "points", "visits", and "points_and_visits".
- Type: string
content _language The language used in the response. Example values are "en", "es", "es-CR", etc.
- Type: boolean
create _empty _gift _cards Determines whether users can create gift cards without any funds loaded onto them initially using the business mobile app
- Type: integer
currency _earned Value of points/visits earned as the result of a conversion as configured in the Punchh platform
- Type: integer
default _map _search _radius The radius within which the app searches for business locations with respect to the current location of a user
- Type: boolean
delete _gift _card _after _consolidation Determines whether the mobile app can automatically delete the empty gift card after card consolidation
- Type: boolean
drive _thru _location _level _strategy 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
- Type: string
earning _description Brief description of the earning program for the business
- Type: string
earning _disclaimer Disclaimer about the earning rules in the app
- Type: string
earning _unit What a user earns as the result of a check-in. Values can be points or visits.
- Type: boolean
email _verification _enabled 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".
- Type: boolean
enable _advance _auth Indicates whether Advanced Authentication is enabled for the business. Returns true if Advanced Authentication is enabled for the business; otherwise, false.
- Type: boolean
enable _gift _card _auto _reload Whether the Gift Card Auto Reload option is enabled for a business or not
- Type: boolean
enable _gift _card _consolidation Determines whether users can transfer the entire balance of a gift card to another gift card using the business mobile app
- Type: boolean
enable _gift _card _gifting Determines whether the mobile app should allow users to gift a card to another user
- Type: boolean
enable _gift _card _purchase Determines whether users can purchase a gift card using the business mobile app
- Type: boolean
enable _gift _card _reload Determines whether users can add to the balance of an existing gift card using the business mobile app
- Type: boolean
enable _gift _card _sharing Determines whether users can share a gift card with another user using the business mobile app
- Type: boolean
enable _gift _card _transfer Determines whether users can transfer the gift card balance amount (both full and partial) to another user using the business mobile app.
- Type: boolean
enable _guest _challenge _opt _in 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.
- Type: boolean
enable _guest _challenge _opt _out 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.
- Type: boolean
enable _loyalty _identification _at _drive _thru 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
- Type: boolean
enable _subscription _taxation _support 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.
- Type: string
facebook _page Facebook page of the business
- Type: boolean
facebook _sharing Determines whether users can share feedback on their Facebook account or not
- Type: string
facebook _signup _incentive _text Text displayed on the sign-up screen to inform a user about any rewards the user might get by signing up using Facebook
- Type: string
faq _url URL of a program's frequently asked questions (FAQ) page
- Type: string
game _disclaimer Disclaimer about the gaming module available in the app
- Type: array object[]
games - Type: numberFormat: float
gift _card _auto _reload _default Default amount with which an eligible gift card will be auto-reloaded
- Type: string
gift _card _auto _reload _disclaimer Disclaimer about gift card auto-reload
- Type: numberFormat: float
gift _card _auto _reload _threshold Threshold amount below which a gift card becomes eligible for auto-reload
- Type: Gift Card Default Amounts (Object)
gift _card _default _amounts 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.
- Type: array object[]
gift _card _designs Returns the different card designs configured in the Punchh platform
- Type: integer
gift _card _minimum _transaction _amount Minimum amount with which gift card transactions (e.g., purchase/reload) will be allowed
- Type: boolean
gift _cards _enabled Whether the app of the business has gift cards or not
- Type: object
guest _account _deletion _request _email 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.
- Type: string
guest _identity _code _type How a user is identified at the POS (the POS scanner type - e.g., barcode, qr_code, etc.)
- Type: string
guest _lookup _type 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.
- Type: string
instagram _page _url Instagram page URL allowing users to follow a business on Instagram
- Type: string
ios _ga _code iOS Google Analytics code of the program's iOS app
- Type: string
ios _geocode _api _key iOS geolocation key
- Type: boolean
ios _guest _account _deactivation Indicates whether a business has enabled account deactivation for its iOS app users
- Type: string
ios _guest _account _deletion Guest account deletion type that a business has configured for its iOS app users. Possible values: none, direct, email
- Type: array Locations (Array Object)[]
locations Returns a list of business locations. Each location object within the Locations array contains information about a specific business location.
- Type: string
marketing _image _url Marketing image URL of the business or service
- Type: string
marketing _info A descriptive/fun blurb about the program
- Type: string
marketing _message 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.
- Type: string
marketing _title Name of the business or service
- Type: numberFormat: double
max _gift _card _balance Maximum currency amount that can be on a gift card
A value of 0 (zero) indicates that there is no limit on the amount that can be on a gift card.
- Type: integer
maximum _rating _in _feedback 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.
- Type: array Membership Levels (Array Object)[]
membership _levels The object contains details about each membership tier in a loyalty program
- Type: string
menus _url URL of the page where the program's menus are explained
- Type: boolean
migration _allowed Returns "true" if the migration flag is enabled for devices
- Type: integer
minimum _age _to _signup Minimum age at which a user is allowed to sign up
- Type: integer
minimum _visit _amount Minimum amount in selected currency required for a visit to be counted
- Type: integer
minimum _visit _hours Minimum time duration between two consecutive visits of a user so that both visits are counted separately
- Type: string
misc1 Miscellaneous field used for app-specific needs. 1 of 4 fields
- Type: string
misc2 Miscellaneous field used for app-specific needs. 2 of 4 fields
- Type: string
misc3 Miscellaneous field used for app-specific needs. 3 of 4 fields
- Type: string
misc4 Miscellaneous field used for app-specific needs. 4 of 4 fields
- Type: Multiple Redemptions (Object)
multiple _redemptions Lists the Punchh platform settings for multiple redemptions for the business. This object is returned in the API response if the
multiple_redemptions_enabledresponse parameter is set to true in the Program Meta API for the business. - Type: boolean
multiple _redemptions _enabled Indicates whether the multiple redemptions feature is enabled for the business. If set to true, the API returns the
multiple_redemptionsobject in the response. - Type: string
nutrition _url URL of the nutrition page
- Type: string
olo _api _key _android Specific to a business using the Olo online ordering service. API key for Android apps
- Type: string
olo _api _key _ios Specific to a business using the Olo online ordering service. API key for iOS apps
- Type: string
olo _base _url Specific to a business using the Olo online ordering service. Base URL used for online ordering
- Type: string
olo _group _order _invite _url 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.
- Type: string
olo _provider _key Specific to a business using the Olo online ordering service. Provider key to use online ordering offered by Olo
- Type: string
order _now _url URL of the page from which a user can order. This opens in the Order tab of the app.
- Type: string
order _url _for _sso SSO URL
- Type: Payment Credential (Object)
payment _credential Contains settings related to the payment adapter, recurring payment type, and passcode
- Type: integer
points _conversion _threshold 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.
- Type: string
points _conversion _type 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:
- staged - Applicable when
program_typeis 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. - none - Applicable when
program_typeis points. The none value indicates points do not get converted into any entity, such as rewards or currency. - currency - Applicable when
program_typeis points. The currency value indicates that earned points are automatically converted to currency at predefined point thresholds. -
rewards - Applicable when
program_typeis points. The rewards value indicates that earned points are automatically converted to rewards at predefined point thresholds. See Punchh Offers and Program Types. You must log in to the developer portal to access the topic.
- staged - Applicable when
- Type: array string[]
preferred _gift _cards 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
- Type: string
privacy _url URL of the page where a user can privately interact with a business or service
- Type: array Profile Field Questions (Array Object)[]
profile _field _questions - Type: string
program _type 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. You must log in to the developer portal to access the topic.
- Type: boolean
promotional _coupons _enabled Whether promotional coupons are enabled for the business or not
- Type: array Redeemable (Array Object)[]
redeemables Lists the redeemables and their details defined in the Punchh system
- Type: integer
redemption _expiry _minutes The time duration after which a redemption code generated by a user expires
- Type: boolean
require _passcode _for _gift _card A secondary authentication that, if enabled from the Punchh platform, is required for sharing and transferring gift cards
- Type: string
share _invite _code _description Invitation code description as configured in the Punchh platform
- Type: string
share _invite _code _message Invitation code message as configured in the Punchh platform
- Type: string
share _invite _code _title Invitation code title as configured in the Punchh platform
- Type: boolean
show _gift _card _history Determines whether the mobile app should show gift card history
- Type: boolean
social _cause _campaigns _enabled Whether social cause campaigns are enabled for the business or not
- Type: boolean
subscription _enabled Whether the subscription feature is enabled for the business or not
- Type: Subscriptions (Object)
subscriptions 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.
- Type: Subscriptions Payment Credential (Object)
subscriptions _payment _credential 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 API does not return the
subscriptions_payment_credentialobject in the API response. - Type: string
support _email _address Support email address of a program
- Type: string
terms _and _conditions _url URL of the page that explains the program's terms and conditions
- Type: string
twitter _handle Twitter handle that allows a user to follow an app (e.g.,
@business_name) - Type: string
uber _client _id Unique ID that identifies Punchh as a consumer of Uber APIs
- Type: string
upgrade _disclaimer Disclaimer about account upgrade (if available) in the app
- Type: integer
visits _per _card Number of visits required for a single card completion
- Type: object
401 - Type: object
Error
{
"android_ga_code": "string",
"android_geocode_api_key": "string",
"beacon_uuid": "string",
"content_language": "string",
"earning_description": "string",
"facebook_sharing": true,
"email_verification_enabled": true,
"ios_ga_code": "string",
"ios_geocode_api_key": "string",
"marketing_image_url": "string",
"marketing_info": "string",
"marketing_message": "string",
"marketing_title": "string",
"uber_client_id": "string",
"promotional_coupons_enabled": true,
"gift_cards_enabled": true,
"gift_card_minimum_transaction_amount": 1,
"max_gift_card_balance": 1,
"social_cause_campaigns_enabled": true,
"default_map_search_radius": 1,
"facebook_signup_incentive_text": "string",
"require_passcode_for_gift_card": true,
"support_email_address": "string",
"faq_url": "string",
"instagram_page_url": "string",
"order_now_url": "string",
"order_url_for_sso": "string",
"menus_url": "string",
"privacy_url": "string",
"terms_and_conditions_url": "string",
"nutrition_url": "string",
"catering_url": "string",
"careers_url": "string",
"facebook_page": "string",
"twitter_handle": "string",
"share_invite_code_message": "string",
"share_invite_code_title": "string",
"share_invite_code_description": "string",
"app_disclaimer": "string",
"game_disclaimer": "string",
"upgrade_disclaimer": "string",
"challenges_disclaimer": "string",
"earning_disclaimer": "string",
"olo_base_url": "string",
"olo_api_key_ios": "string",
"olo_api_key_android": "string",
"olo_provider_key": "string",
"olo_group_order_invite_url": "string",
"business_id": 1,
"business_name": "string",
"checkin_evidenced_by": "string",
"guest_identity_code_type": "string",
"visits_per_card": 1,
"card_redemption_value": 1,
"migration_allowed": true,
"minimum_visit_amount": 1,
"minimum_visit_hours": 1,
"minimum_age_to_signup": 1,
"misc1": "string",
"misc2": "string",
"misc3": "string",
"misc4": "string",
"earning_unit": "string",
"currency_earned": 1,
"points_conversion_threshold": 1,
"redemption_expiry_minutes": 1,
"allow_rating_in_feedback": true,
"maximum_rating_in_feedback": 1,
"checkins_earn": "string",
"gift_card_designs": [
{
"backgroud_image_url": "string",
"card_type": "string",
"name": "string",
"design_id": 1
}
],
"locations": [
{
"address": "string",
"brand": "string",
"city": "string",
"country": "string",
"external_store_id": "string",
"latitude": 1,
"location_id": 1,
"longitude": 1,
"name": "string",
"phone_number": "string",
"loc_mail": "string",
"post_code": "string",
"state": "string",
"store_number": "string",
"store_tags": "string",
"store_times": [
{
"day": "string",
"start_time": "16:30:02",
"end_time": "16:30:02"
}
],
"time_zone": "string",
"updated_at": "YYYY-MM-DDThh:mm:ssZ",
"status": "string",
"franchisee_id": 1,
"enable_weekly_redemption_report": true,
"checkin_evidenced_by": "string",
"guest_identity_code_type": "string",
"enable_pos_monitoring": true,
"generate_barcodes": true,
"alternate_store_number": "string",
"additional_url": [
{
"label": "string",
"url": "string"
}
],
"single_scan_type": "string",
"hide_in_store_tipping": false,
"hide_in_store_cc_payment": false,
"hide_ssf_gift_card": false,
"multiple_redemption_on_location": true
}
],
"membership_levels": [
{
"background_image_url": "string",
"points_multiplier": 1,
"membership_level_id": 1,
"name": "string",
"description": "string",
"maximum_points": 1,
"minimum_points": 1,
"currency_earned": 1,
"points_conversion_threshold": 1
}
],
"redeemables": [
{
"redeemable_image_url": "string",
"redeemable_properties": [
"string"
],
"redeemable_id": 1,
"name": "string",
"description": "string",
"points_required_to_redeem": 1,
"meta_data": "string"
}
],
"games": [
{
"game_viral_message": "string",
"name": "string",
"images_on_card": 1,
"scratch_valid_codes": "string",
"game_type": "string",
"requires_code_validation": true,
"game_id": 1,
"gaming_levels": [
{
"extra_punchhs": 1,
"redeemable_id": null,
"level": "string"
}
]
}
],
"profile_field_questions": [
{
"question": "string",
"answer_options": "string",
"data_type": "string",
"hint": "string",
"mandatory": true,
"size": 1,
"upf": "string",
"updatable": true
}
],
"banking_rules": [
{
"banked_redeemable_id": "string",
"banking_slab": 1,
"points_conversion_threshold": 1,
"currency_earned": "string"
}
],
"base_redeemable": {
"name": "string",
"description": "string",
"image_url": "string",
"redeemable_properties": [
"string"
],
"meta_data": "string"
},
"payment_credential": {
"adapter_code": "string",
"enable_recurring_payments": true,
"enable_passcode_for_payment": true
},
"enable_gift_card_auto_reload": true,
"gift_card_auto_reload_threshold": 1,
"gift_card_auto_reload_default": 1,
"gift_card_auto_reload_disclaimer": "string",
"subscriptions": {
"subscription_cancellation_reasons": [
{
"component_code": "string",
"cancellation_reason_id": 1,
"cancellation_reason": "string"
}
],
"enable_cancellation_feedback": true,
"cancellation_feedback_placeholder": "string",
"payment_disclaimer_text": "string",
"terms_and_conditions": "string"
},
"subscription_enabled": true,
"subscriptions_payment_credential": {
"adapter_code": "string",
"enable_recurring_payments": true
},
"auto_select_strategy": "string",
"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": 1,
"gift_card_purchase_amount_2": 1,
"gift_card_purchase_amount_3": 1
},
"gift_card_purchase_default_option": 1,
"gift_card_reload_amounts_options": {
"gift_card_reload_amount_1": 1,
"gift_card_reload_amount_2": 1,
"gift_card_reload_amount_3": 1
},
"gift_card_reload_default_option": 1,
"gift_card_auto_reload_amounts_options": {
"gift_card_auto_reload_amount_1": 1,
"gift_card_auto_reload_amount_2": 1,
"gift_card_auto_reload_amount_3": 1
},
"gift_card_auto_reload_default_option": 1,
"balance_threshold_amounts_options": {
"balance_threshold_amount_1": 1,
"balance_threshold_amount_2": 1,
"balance_threshold_amount_3": 1
},
"balance_threshold_default_option": 1
},
"preferred_gift_cards": [
"string"
],
"multiple_redemptions_enabled": true,
"multiple_redemptions": {
"auto_redemption": true,
"enable_discount_locking": true,
"enable_auto_unlock": true,
"max_redemptions_in_transaction": 1,
"auto_redemption_discounts": [
"string"
],
"allow_multiple_redemption_on_item": true,
"allow_qualifying_items_reused": true,
"discount_processing_strategy": "string",
"processing_priority_by_discount_type": [
"string"
],
"processing_priority_by_acquisition_type": [
{
"code": "string",
"priority": 1,
"multiplication_factor": 1
}
],
"exclude_interoperability_strategy_between": [
"string"
],
"auto_unlock_duration": 1
},
"cancel_redemption": true,
"ios_guest_account_deactivation": true,
"android_guest_account_deactivation": true,
"ios_guest_account_deletion": "string",
"android_guest_account_deletion": "string",
"guest_account_deletion_request_email": {
"to": "string",
"subject ": "string",
"body": "string"
},
"app_feedback_url": "string",
"accessibility_url": "string",
"enable_advance_auth": true,
"program_type": "string",
"points_conversion_type": "string",
"guest_lookup_type": "string",
"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_subscription_taxation_support": true
}