Headless Offers Management - Distribution

Overview

Many businesses use third-party platforms for their marketing campaigns (e.g., marketing clouds such as Braze and Salesforce). However, coordinating marketing communications in one platform while distributing offers from Punchh can be challenging. The Punchh Headless Offers APIs enable a business to distribute Punchh offers from a given third-party system by executing mass offer campaigns via API calls. Instead of executing content messaging in an external marketing cloud and then separately executing a Punchh campaign to deliver an offer, these endpoints allow a business to use its existing systems while also using Punchh offers, preventing duplication of effort. Distributing Punchh offers via a third-party platform across various systems and channels allows the business to integrate Punchh offers into its existing infrastructure in order to reach a wider audience and enhance customer engagement by delivering personalized and targeted offers to its customers.

Requirements

• Offers must be created within Punchh
• Only mass gifting campaigns are supported
• Only redeemable discount types are supported
• Segments must exist in both platforms

Additional notes:

• The campaign creation process is invoked by API, but a campaign and reporting will be created in Punchh
• No guest details are exposed in the API calls

Headless Offers API Endpoints

Using the Headless Offers API endpoints, a marketer can create a redeemable in the Punchh platform and distribute the discount with a mass offer campaign from a preferred external marketing system. These endpoints can ​support the use of other marketing automation tools in conjunction with Punchh, where the other platform is responsible for creation and delivery of campaign messaging (emails, push notifications, SMS, etc.).

API Endpoint Name/Path	Use Cases
Get Segment List GET {server-name}/api2/dashboard/segments	Search and filter all segments created in Punchh. Marketers can search the segment based on segment name. The limit for search can be defined. The external platform is responsible for targeting loyalty guests with marketing communications accompanied by offers to be distributed into the accounts of targeted guests. Loyalty guest segments are defined and stored on Punchh. The external platform pulls the available segments on Punchh by name. The external platform configures marketing communications to target the equivalent segment in that system, and passes the matching Punchh segment by name to the Commit Redeemable Distribution API to execute a mass offer campaign to deliver the accompanying offers with the distribution of marketing communications. You can add a user to the segment using either email or user_id. See Add User to a Custom Segment. You can also add users in bulk to a custom segment by uploading a CSV file that contains a list of users and their details. See Bulk Add Users to a Custom Segment. See Custom Segment APIs quickstart topic for the complete list of APIs for managing custom segments and users. The users you add must exist in Punchh. If a user does not exist, then the Add User to a Custom Segment API returns an error. When using the Bulk Add Users to a Custom Segment API, the users who do not exist in Punchh are skipped. You can use the Get User Information API to check whether a user exists in Punchh.
Get Redeemable List GET {server-name}/api2/dashboard/redeemables	Search and filter Punchh redeemables. Marketers can search and filter the redeemable by name or description. The external platform is responsible for targeting loyalty guests with marketing communications accompanied by offers to be distributed into the accounts of targeted guests. Offers are defined and stored on Punchh. The external platform pulls the available redeemables on Punchh by name. The external platform passes the desired Punchh redeemable to be gifted by name to the Commit Redeemable Distribution API to execute a mass offer campaign configuration and scheduling to deliver the accompanying offers with the distribution of marketing communications.
Commit Redeemable Distribution POST {server-name}/api2/dashboard/campaigns	Send mass offer campaigns with Punchh redeemables. Commit the distribution of the Punchh-created redeemable through the external campaign. Marketers can call this API to deliver the redeemable through their marketing cloud. The external platform is responsible for targeting loyalty guests with marketing communications accompanied by offers to be distributed into the accounts of targeted guests. Loyalty guest segments and offers are defined and stored on Punchh. The external platform configures marketing communications to target the equivalent segment in that system, using the Get Segment List API and the Get Redeemable List API to pull Punchh segments and offers into the platform for the end user to select in its workflow. When the marketing communications are scheduled/committed by the end user on the outside platform, the outside platform calls the Commit Redeemable Distribution API and passes the matching Punchh segment by name and the desired Punchh redeemable to be gifted. Punchh executes a mass offer campaign in response to the request to deliver the accompanying offers in tandem with the distribution of marketing communications by the outside platform.

Headless Offers API Workflow

1. The external system needs to create campaigns.

2. The external system requests data from the Get Redeemable List API to obtain the list of redeemable items.

3. The external system also requests data from the Get Segment List API to retrieve all available segments so that they can decide the group for which they want to create the campaign.

4. The data from the Get Redeemable List API and the Get Segment List API are needed for creating campaigns.

5. Using the data obtained from the two APIs, the external system creates campaigns.

6. The campaigns are scheduled to run at a specific time.

7. When the scheduled time arrives, the campaign is triggered for distribution.

8. The rewards associated with the campaign are distributed to the targeted group of users.

9. Users can then access the rewards from their accounts.