Punchh: overview

You can connect Attentive with PAR Punchh (a PAR Technology Company), a leading loyalty and marketing platform for restaurants and convenience stores.

This integration allows you to seamlessly share data between Attentive and Punchh to enhance your marketing program. With this integration, you can:

  • Keep SMS consent aligned: Sync SMS opt-in and opt-out statuses between Attentive and Punchh, including an initial sync of historical statuses.
  • Use loyalty and event data: Use real-time customer loyalty data attributes and events from Punchh to build targeted segments and trigger personalized journeys.
  • Grow your loyalty program: Use Attentive sign-up units or text-a-keyword journeys to capture new sign-ups for your Punchh program.
  • Consolidate user profiles: Perform a one-time import of existing Punchh user profiles into Attentive to enrich your segments.

This guide provides step-by-step instructions on how to set up the Punchh integration and configure key features.

Prerequisites

Before you begin setting up the Attentive + Punchh integration, you need to gather the following information from your Punchh account or representative:

  • Base URL
  • Business UUID
  • Client ID
  • Secret
  • Business Admin Key
Note: The Business Admin Key from Punchh needs to be entered into the field labeled API Key on the setup page in Attentive for the Punchh integration.

Please contact your Punchh account manager or their support team if you need help locating this information. Once you have this information, you can proceed with setting up the integration in Attentive.

Step 1: Set up the Punchh integration in Attentive

Once you’ve gathered the required information from Punchh (as outlined in the Prerequisites section above), follow these steps to set up the integration in your Attentive account:

  1. In Attentive, go to Marketplace.
  2. Find the Punchh tile by scrolling or using the search bar.
  3. Click the Punchh tile. The page for the Punchh integration opens.
  4. Click Install. The Punchh setup page opens.
    Attentive integration settings for Punchh, showing required input fields for Base URL, Business UUID, Client ID, Secret, and API Key, with a 'Save and continue' button.
  5. On the Punchh setup page, fill out the following fields:
    • Base URL
    • Business UUID
    • Client ID
    • Secret
    • API Key (this is called Business Admin Key in Punchh)
  6. Click Save and continue.

After saving, the basic integration between Attentive and Punchh is established. You can now configure specific integration features, such as syncing subscriber consent or loyalty events.

Punchh integration tile in Attentive Marketplace. A red arrow points to the green status indicator label, which reads 'Installed'.

Step 2: Set up Punchh integration features

Now that you’ve set up the Punchh integration in Attentive, you can configure several features to synchronize data and enhance your marketing program.

SMS consent synchronization (required) This essential feature helps ensure that SMS opt-in and opt-out statuses stay consistent between Attentive and Punchh. It includes an initial sync to update historical consent statuses for existing Punchh users and ongoing, real-time updates for new consent changes captured in Attentive.
Loyalty event and attribute synchronization (required) Receive valuable customer data in Attentive from Punchh in real-time. This includes:
  • Loyalty attributes: Sync customer details like membership level, points balance, birthday, and favorite locations for use in segmentation.
  • Loyalty events: Capture events like loyalty check-ins, rewards redemptions, or points conversions to trigger automated journeys in Attentive.
Bulk user profile synchronization (recommended) Perform a one-time import of your existing Punchh user profiles (including their attributes) into Attentive. This is recommended if you plan to use loyalty event and attribute synchronization, since it provides a complete baseline of your loyalty members for segmentation.
Use Attentive sign-up units for loyalty capture (optional) Add a loyalty sign-up option to your Attentive sign-up units so that users can sign up for your loyalty program and opt in to receive messages from you through Attentive at the same time.
Use text-a-keyword journeys to allow existing and prospective subscribers to sign up for your loyalty program (optional) You can allow both existing and prospective SMS subscribers to sign up for your Punchh loyalty program by texting a specific keyword (e.g., REWARDS, LOYALTY) to your number.
Subscribers API for SMS collection (optional) Add SMS subscribers to your Attentive account from your own platforms, like a custom mobile app, website forms, or Punchh-hosted iframe units, using Attentive’s Subscribers API.

Setup instructions for each feature are provided in the following sections.

Configure SMS consent synchronization (required)

This feature helps ensure that your SMS consent preferences are consistent between Attentive and Punchh. This involves two key aspects: synchronizing ongoing consent changes and performing an initial historical backfill.

Ongoing SMS consent updates (postback)

Once you’ve connected and set up the Punchh integration in Attentive, Attentive automatically begins forwarding your new SMS opt-in and opt-out events to Punchh in real-time. This means that when a subscriber’s SMS status changes in Attentive (e.g., they opt-in via a keyword or opt-out by replying STOP to a message), Attentive informs Punchh and the corresponding user’s profile in Punchh is updated.

Notes:
  • This ongoing sync updates SMS consent status for existing user profiles in Punchh that match based on phone number or email. It doesn’t create new user profiles in Punchh.
  • While Attentive sends opt-out information to Punchh, keep in mind that opt-outs initiated directly in Punchh are only sent to Attentive if a user’s phone number is changed or removed in Punchh. Opt-out information isn’t sent when deleting a user account entirely in Punchh.
  • Punchh user statuses like “deactivated” and “banned” don’t sync to Attentive as SMS opt-outs. While Punchh will no longer message these users, their subscription status in Attentive won’t be updated.

No additional configuration is typically required for this ongoing synchronization beyond the initial setup you did in Step 1: Set up the Punchh integration in Attentive.

Historical SMS backfill

Follow these steps to turn on the backfill:

  1. In Attentive, go to Marketplace.
  2. Go to the Installed by you tab and scroll to find the Punchh tile.
  3. Click the Punchh tile.
  4. Go to the Settings tab.
  5. Check Enable SMS Consent Update Sync.
  6. Click Save changes

Punchh settings page showing the 'Enable SMS Consent Update Sync' checkbox checked, with descriptive text below it, and a 'Save changes' button.

After you click Save changes, the sync begins. The sync processes around 50,000 records per day. If you want to verify that the sync is complete, reach out to your Attentive CSM or Attentive’s White Glove team.

Capture Punchh email-only sign-ups

This feature allows you to automatically sync email subscribers captured through Punchh into your Attentive subscriber list via a daily SFTP file transfer.

Note: Before you can configure this feature in Punchh, contact your Attentive CSM or White Glove. They can request provisioning of SFTP credentials and other important setup from our technical teams. Don’t proceed with the steps below until your CSM or White Glove confirms that this setup is complete.

Once Attentive has provided SFTP credentials and confirmed readiness, go to Settings > FTP Endpoints in Punchh and add an FTP endpoint:

  1. Name: Enter a descriptive name (for example, Attentive Punchh)
  2. Protocol: Select SFTP (SSH File Transfer Protocol)
  3. Host: Enter sftp.client.attentivemobile.com
  4. Port: Enter 22.
  5. Username: Enter the username provided to you by Attentive (for example, punchdevel.dev)
  6. Password: Enter the password provided to you by Attentive
  7. Path: Enter the path of the directory where files should be uploaded (for example, uploads/punchh/users). This should match the bulk user file upload location, minus the Attentive domain prefix.
  8. Support Email: Enter an email address to receive notifications if uploads fail.

Click Save when finished.

You can now select your newly-created FTP endpoint when creating or editing a scheduled data export in Punchh.

Edit Data Export Schedule page in Punchh, focusing on the FTP Endpoint selection dropdown.

Configure loyalty event and attribute synchronization (required)

This feature allows you to receive real-time loyalty data in Attentive from Punchh. You can use this data, such as customer attributes (like membership level, points balance, birthday) and events (like check-ins, rewards earned), to create targeted segments and trigger personalized journeys in Attentive.

Setup requires configuration in both Attentive and Punchh.

Part 1: Configure loyalty event and attribute synchronization in Attentive

  1. In Attentive, go to Marketplace.
  2. Go to the Installed by you tab and scroll to find the Punchh tile.
  3. Click the Punchh tile.
  4. Click the Settings tab.
  5. Scroll down to the Loyalty Event Webhooks Synchronization section.
  6. Ensure the checkbox for Loyalty Event Webhooks Synchronization is checked.
  7. Click Save. After saving, two new fields will appear in this section: Attentive Webhook Base URL (optional) and Attentive Webhook End Point (optional).
    Loyalty Event Webhooks Synchronization settings in Attentive, showing fields for Attentive Webhook Base URL and End Point with copy buttons.
  8. Copy the values for Attentive Webhook Base URL(optional) and Attentive Webhook End Point(optional). You’ll need them to complete the setup in Punchh.

Part 2: Configure loyalty event and attribute synchronization in Punchh

Now, log in to your Punchh account to configure the webhook destination:

  1. Go to Data Sharing > Outbound Webhooks.
  2. Go to the Webhooks tab.
  3. Click Base URL.
    Punchh interface, Webhooks tab, with the 'Base URL' button highlighted.
    The Base URLs page appears.
  4. On the Base URLs page, click + Add New URL
    Punchh interface, Base URLs page, with the '+ Add New URL' button highlighted.
    The Create New Base URL page appears.
    Create New Base URL page in Punchh, with fields for Name, Webhook Base URL, and Admin Email.
  5. Complete the following on the Create New Base URL page:
  6. Go back to the Webhooks tab.
  7. Click + Create Webhook.
    Punchh interface, Webhooks tab, with the '+ Create Webhook' button highlighted.
    The Create New Webhook page appears.
    Create New Webhook page in Punchh, with fields for Name, Description, Base URL, Webhook End Point, Authentication, and Events Selection.
  8. Complete the following on the Create New Webhook page:

Once both parts are configured and saved, Punchh will start sending customer attribute updates and event loyalty data to Attentive. Here are some ways you can use this data:

  • Attributes: Build customer segments (for example, segments based on Punchh Membership Level or Punchh Loyalty Points).
  • Events: Trigger Attentive journeys (for example, trigger a journey when a Punchh - Earned Reward event occurs).

See Reference: Punchh attributes synced to Attentive and Reference: Punchh events synced to Attentive for detailed information about available attributes and events.

Troubleshoot webhooks

  • If user attributes and events aren’t appearing in Attentive after enabling webhooks, you may need to add https://dashboard-api.us-west.punchh.com as the Platform Function API Base URL (optional) field on the Settings tab for the Punchh integration in Attentive.
  • New journey triggers based on Punchh events only appear in Attentive once we begin receiving new events from Punchh. New journey triggers won’t be immediately available after completing setup.

Configure bulk user profile synchronization (recommended)

This process allows you to perform a one-time import of your existing user profiles from Punchh into Attentive. It’s useful for establishing a complete baseline of your loyalty members within Attentive, which is recommended if you’ve enabled loyalty event and attribute synchronization. The bulk import should generally be done only once when first setting up the integration.

This process involves exporting user data from Punchh, then requesting that this data be uploaded into Attentive.

Part 1: Export user data from Punchh

  1. Log in to Punchh.
  2. Go to Data Sharing, then select Data Export. The New Data Export Template page appears.
    New Data Export Template page in Punchh. A red arrow points to the 'Data Export' option in the left-hand navigation menu.
  3. Set up the data export:
    • Name: Enter a descriptive name.
    • Date Range: Select the date range for which user data should be exported.
    • Under Data Exports with Optional Modified Records, check Guest Data.
    • Under Guest Data, move at least the following fields from Available Fields to Selected Fields:
      • First Name
      • Last Name
      • Email
      • Gender
      • Birthday
      • Loyalty Guest Signup Date
      • Phone
      • Guest Type

        Note: Attentive can associate the imported profiles with either “Loyalty” or “eClub” status, but not both simultaneously. The standard recommendation is to use “Loyalty.” If your Punchh export file contains both “Loyalty” and “eClub” guest type values, you must edit the downloaded file before it’s uploaded to Attentive to use only “Loyalty”.
      • User ID
        Guest Data selection for Punchh data export, showing 'Available Fields' and 'Selected Fields' such as First Name, Last Name, Email, and Phone.
    • Click Save & Create Schedule, then finish generating and download the export file.

Part 2: Request user data be uploaded into Attentive

After you’ve exported user data from Punchh, contact your Attentive CSM or our White Glove team and let them know that you’re ready to import this data into Attentive.

Once Attentive confirms that the import is complete, historical Punchh user profiles will be available in Attentive for segmentation and analysis.

Use Attentive sign-up units for loyalty capture

Add an optional checkbox to your Attentive sign-up units that allows new subscribers to join your Punchh loyalty program at the same time they opt in to receive messages from you.

Notes:
  • Ensure you’ve already configured loyalty event and attribute synchronization.
  • The loyalty checkbox feature is currently available only for SMS sign-up units, not email-only units.
  • Any discount code or offer associated with a sign-up unit is triggered when the user opts into SMS. Your offers are sent regardless of whether subscribers check the loyalty box.

Part 1: Enable loyalty capture in integration settings

  1. In Attentive, go to Marketplace.
  2. Go to the Installed by you tab and scroll or search to find the Punchh tile.
  3. Click the Punchh tile.
  4. Click the Settings tab.
  5. On the Settings tab, find and check the box labeled Capture Loyalty Sign-ups Through Attentive.
    Attentive settings for Punchh integration, showing the 'Capture Loyalty Sign-ups Through Attentive' checkbox is checked and the 'Enable SMS Consent Update Sync' checkbox is unchecked.
  6. Click Save changes.

Part 2: Add the loyalty checkbox to an SMS sign-up unit.

After you’ve enabled loyalty capture in the integration settings for Punchh, contact your Attentive CSM or our White Glove team and let them know which of your Attentive sign-up units you want to add the loyalty checkbox to. You can also ask for the loyalty checkbox to be pre-checked.

Understand how the loyalty checkbox works

When a visitor clicks the call-to-action button in the sign-up unit and the loyalty box is checked, Attentive sends the visitor’s email address to Punchh via the webhook you configured in the Configure loyalty event and attribute synchronization (required) section. Subscriber phone numbers won’t be sent to Punchh until the visitor completes SMS opt-in.

If a user checks the box, but is already enrolled in your Punchh loyalty program, Punchh won’t create a duplicate account or trigger a new sign-up event. This means that if you have a journey set up to send messages when a subscriber joins your Punchh loyalty program, subscribers who are already enrolled won’t enter that journey.

Use text-a-keyword journeys to allow existing and prospective subscribers to sign up for your loyalty program

You can allow both existing and prospective SMS subscribers to sign up for your Punchh loyalty program by texting a specific keyword (e.g., REWARDS, LOYALTY) to your number.

Notes:

See Punchh: Create a Punchh loyalty texted-a-keyword journey for more information about creating text-a-keyword journeys for your Punchh loyalty program.

Use the Subscribers API for SMS collection

Beyond using Attentive’s sign-up units or keywords, you can also add SMS subscribers to your Attentive account from your own platforms, like a custom mobile app, website forms, or Punchh-hosted iframe units, using Attentive’s Subscribers API.

To add SMS subscribers via the Subscribers API, refer to our Subscribers API documentation. Contact your Attentive CSM or White Glove for questions or assistance.

Note: Any custom sign-up method implemented using the Subscribers API must include appropriate legal language that clearly states the nature of the messages, consent requirements, help/stop instructions, message frequency, and potential data rates. See Template disclosure language for language you must use in custom sign-up methods.

Reference: Punchh attributes synced to Attentive

When you’ve configured loyalty event and attribute synchronization, Attentive receives the following user attributes from Punchh in real-time. You can use these attributes in Attentive’s segment builder to create targeted audiences.

Anniversary
The user's wedding anniversary date.
Banned
Indicates whether the user is marked as banned in Punchh.
Birthday
The user’s birthday in YY-MM-DD format. This can be used for exact date matching or month/day matching in Attentive segments.
City
The city where the user lives.
Email
The user’s email address.
Favorite store numbers
The IDs of the user’s favorite store locations as recorded in Punchh. You may need to cross-reference these IDs with location names in Punchh.
First name
The user’s first name.
Gender
The user’s gender (e.g., male, female, decline to state)
Guest Type
Indicates if the user is classified as “Loyalty” or “eClub” in Punchh.

Note: Attentive can associate profiles with either “Loyalty” or “eClub” status, but not both simultaneously if mixed in the file. The standard recommendation is to use “Loyalty.” If your Punchh export file contains both “Loyalty” and “eClub” guest type values, you must edit the downloaded file before it’s uploaded to Attentive to use only “Loyalty”.
Joined At
Timestamp indicating when the user signed up for loyalty
Last activity at
Timestamp indicating user’s last recorded activity in Punchh
Last name
The user’s last name.
Marketing email subscription
Indicates whether the user is signed up for marketing subscription
Marketing push notification subscription
User is signed up for push notifications
Phone
The user’s phone number
Preferred locale
The user's preferred language locale setting in Punchh.
Punchh Anniversary
The date the user joined the Punchh loyalty program (YYYY-MM-DD)
Punchh Last Visit
The timestamp of the user’s last loyalty visit recorded in Punchh
Punchh Loyalty Points
The user’s total current loyalty points balance.
Punchh Loyalty Signup
Indicates if the user signed up for the Punchh program via an Attentive sign-up unit or via text
Punchh Membership Level
The name of the user’s current membership level in Punchh
Punchh Total Credits
The user’s total loyalty points earned over time, excluding expired points
Punchh User Status
The user’s account status in Punchh (active, banned, deactivated)
Referral code
The user’s unique referral code from Punchh
Signup channel
The channel through which the user originally signed up for Punchh (WebEmail, MobileFacebook, etc.)
SMS subscription
Indicates if the user is subscribed to SMS via Punchh (True/False)
State
The state where the user lives
Unsubscribed Reason
The reason recorded if the user unsubscribed from email via Punchh (e.g., By User, Admin)
Unsubscribed Status
Indicates if the user is unsubscribed from email communications via Punchh.
User ID
The unique identifier assigned to the user in Punchh.
Zip
The Zip code where the user lives.

Reference: Punchh events synced to Attentive

When you’ve configured loyalty event and attribute synchronization, Attentive receives the following events from Punchh in real-time. You can use these events as triggers for Attentive journeys to send messages based on subscriber activity in your Punchh loyalty program.

Punchh - Guest
Triggers when a user’s profile is created, updated, or deleted in Punchh.
Punchh - Checked in for loyalty
Triggers when a user checks into the loyalty program.
Punchh - Checked in for gift
Triggers when a user checks in specifically for a gift or offer.
Punchh - Created Redemption
Triggers when a user creates a redemption (e.g., selects a reward to use).
Punchh - Updated Redemption
Triggers when a user updates a redemption.
Punchh - Applied Redemption
Triggers when a redemption (reward/offer) is actually applied or used.
Punchh - Earned Reward
Triggers when a reward is earned or issued to a user.
Punchh - Earned Expiring
Triggers when a previously earned reward is approaching its expiration date.
Punchh - Checked in at POS scanner
Triggers after a user checks in via a Point-of-Sale (POS) scanner.
Punchh - Received Marketing Notification
Triggers when a customer submits their information via a Punchh sign-up campaign form.
Punchh - Converted Points to Reward
Triggers when a user’s accumulated points are converted into a specific reward.
Punchh - Completed Card
Triggers when a user completes a virtual loyalty card (e.g., buy 10 get 1 free)
Punchh - Logged in from New Device
Triggers when a user logs into their Punchh account from a device not previously used.
Punchh - Triggered Password Reset
Triggers when a user initiates a password reset from their Punchh account.

Questions?

We’re here to help! Contact your Attentive CSM or our White Glove team (whiteglove@attentivemobile.com) to ask about the Attentive + Punchh integration.

Articles in this section