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

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.
   
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.

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.

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.

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

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.

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.

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).
   
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.
   
   The Base URLs page appears.
4. On the Base URLs page, click + Add New URL
   
   The Create New Base URL page appears.
   
5. Complete the following on the Create New Base URL page:
• Enter a descriptive Name.
• In the Webhook Base URL field, paste the Attentive Webhook Base URL you gathered in Part 1: Configure loyalty event and attribute synchronization in Attentive.
• Enter an Admin Email address.
• Click Submit.
6. Go back to the Webhooks tab.
7. Click + Create Webhook.
   
   The Create New Webhook page appears.
   
8. Complete the following on the Create New Webhook page:
• Enter a Name.
• Enter a Description.
• In the Webhook End Point field, paste the Attentive Webhook End Point you gathered in Part 1: Configure loyalty event and attribute synchronization in Attentive.
• From the Authentication dropdown, choose Bearer.
• In the Auth Bearer Token field, paste your Business Admin Key, which you gathered as part of the Prerequisites.
• From the Events Selection dropdown, select all events.
• Click Submit.

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.
• If https://hooks.us-west.punchh.com is the Base URL, the Platform Function API Base URL (optional) should be https://dashboard-api.us-west.punchh.com.
• 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.
   
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
       
   • 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.

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.
   
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.

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.

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.