Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Mobile Challenges 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: Challenges
paths:
/api2/mobile/challenges:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
challenges:
type: array
items:
type: object
properties:
gift_reason:
type: string
description: Reason to give gifts to a user
id:
type: integer
description: Challenge ID
icon:
type: string
description: Image icon of the challenge
icon_completed:
type: string
description: Image icon that represents completion of the challenge
name:
type: string
description: Name of the challenge. The name is returned in the language specified in the Accept-Language request header, provided the challenge name has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under <b>Marketing Automation > Campaign Management</b>. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language.
start_date:
type: string
enum:
- YYYY-MM-DD
format: date
description: Start date of the campaign
end_date:
type: string
enum:
- YYYY-MM-DD
format: date
description: End date of the campaign
image_url:
type: string
description: URL of the image
description:
type: string
description: Description of the challenge. The description is returned in the language specified in the Accept-Language request header, provided the challenge description has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under <b>Marketing Automation > Campaign Management</b>. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the description is returned in French if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language.
tasks:
type: array
description: Information about the name and steps involved
items:
type: object
properties:
name:
type: string
number_of_steps:
type: integer
miscellaneous:
type: string
description: Returns miscellaneous response string as configured in the Punchh platform
challenge_reach:
type: string
x-nullable: true
description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are:
- universal_auto_enrolment
- segment_auto_enrolment
- null (when no reach strategy is defined)'
challenge_type:
type: string
description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are:
- receipt_qualification
- every_x_points
- segment'
occurrence:
type: string
description: 'Possibel values are:
- **single** - Shows when restarting the challenge button is OFF in the campaign
- **multiple** - Shows when restarting the challenge button is ON in the campaign'
examples:
default:
value:
challenges:
- gift_reason: Punchh product qa test currency
id: 124872
icon: IMAGE_URL_GOES_HERE
icon_completed: IMAGE_URL_GOES_HERE
name: Punchh product qa test currency
start_date: null
end_date: null
image_url: IMAGE_URL_GOES_HERE
description: ''
tasks:
- name: Punchh product qa test currency
number_of_steps: 10
miscellaneous: ''
challenge_reach: segment_auto_enrolment
challenge_type: every_x_points
occurrence: single
- gift_reason: Punchh product qa test redeemable
id: 124873
icon: IMAGE_URL_GOES_HERE
icon_completed: IMAGE_URL_GOES_HERE
name: Punchh product qa test redeemable
start_date: null
end_date: null
image_url: IMAGE_URL_GOES_HERE
description: ''
tasks:
- name: Punchh product qa test redeemable
number_of_steps: 1
miscellaneous: ''
challenge_reach: null
challenge_type: segment
occurrence: single
- gift_reason: Buy 5 Cheese Breadsticks
id: 124875
icon: IMAGE_URL_GOES_HERE
icon_completed: IMAGE_URL_GOES_HERE
name: Buy 5 Cheese Breadsticks
start_date: '2020-11-30'
end_date: '2021-03-31'
image_url: IMAGE_URL_GOES_HERE
description: Buy 5 Cheese Breadsticks
tasks:
- name: Buy 5 Cheese Breadsticks
number_of_steps: 5
miscellaneous: '{"detailedDescription":"Earn 50 bonus points after you purchase five breadsticks. Your points will automatically be added to your account after completion. Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"fuel", "GiftPoints":"0.55", "challengeType":"Personal", "nounDescription" : "fuel"}'
challenge_reach: segment_auto_enrolment
challenge_type: receipt_qualification
occurrence: single
- gift_reason: Get your 4th Breadstick free
id: 124876
icon: IMAGE_URL_GOES_HERE
icon_completed: IMAGE_URL_GOES_HERE
name: Buy 4 Breadsticks!
start_date: '2020-11-30'
end_date: '2021-02-10'
image_url: IMAGE_URL_GOES_HERE
description: Get your 4th Breadstick free
tasks:
- name: Buy 4 Breadsticks!
number_of_steps: 3
miscellaneous: '{"detailedDescription":"Get your next cheese breadstick free after you purchase three breadsticks. . Terms & Conditions may apply. Complete by 12/31/2020.", "GiftType":"offer", "GiftPoints":"50% off , Breadstick", "challengeType":"Personal","nounDescription" : "breadsticks"}'
challenge_reach: segment_auto_enrolment
challenge_type: receipt_qualification
occurrence: multiple
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
Invalid or missing access token:
value:
unauthorized:
- An active access token must be used to query information about the current user.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
disabled_feature:
type: string
examples:
Challenges not enabled:
value:
errors:
disabled_feature: Business does not have challenges enabled.
summary: List Challenges
description: 'Lists challenges available for a business. The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration.
<!-- Cockpit > Dashboard > Major Features > Enable Challenges? -->
'
operationId: mobile_list_challenges
tags:
- Challenges
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- schema:
type: string
in: header
name: Accept-Language
description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese<br> The locales for a business are configured in the Punchh platform under <b>Administration > Business Profile > Address</b>. Click the <b>Alternate Languages</b> drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under <b>Marketing Automation > Campaign Management</b>.'
x-stoplight:
id: 26fb9c55960f8
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
x-stoplight:
id: ng9tn0hdkmtqy
description: OAuth client ID provided by the business
required:
- client
/api2/mobile/challenges/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
progress:
type: array
items:
type: object
properties:
completed_steps:
type: integer
description: Number of steps a user has completed for a challenge
total_steps:
type: integer
description: Number of total steps set for a challenge
name:
type: string
description: Name of the challenge. The name is returned in the language specified in the Accept-Language request header, provided the challenge name has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under <b>Marketing Automation > Campaign Management</b>. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language.
description:
type: string
description: Description of the challenge. The description is returned in the language specified in the Accept-Language request header, provided the challenge description has been translated into the relevant language by the business admin in the Punchh platform when creating or editing a challenge campaign under <b>Marketing Automation > Campaign Management</b>. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the description is returned in French if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language.
image_url:
type: string
description: URL of the main banner image associated with the challenge campaign
icon_url:
type: string
description: URL of the default icon image for the challenge
icon_completed_url:
type: string
description: URL of the image icon that represents completion of the challenge
start_date:
type: string
enum:
- YYYY-MM-DD
format: date
description: Start date
end_date:
type: string
enum:
- YYYY-MM-DD
format: date
description: End date
gift_reason:
type: string
description: Reason to give gifts to a user
miscellaneous:
type: string
description: Returns miscellaneous response string as configured in the Punchh platform
challenge_id:
type: integer
description: Challenge ID
challenge_reach:
type: string
x-nullable: true
description: 'Returns the type of challenge reach strategy defined on the challenge campaign. Possible values are:
- universal_auto_enrolment
- segment_auto_enrolment
- null (when no reach strategy is defined)'
challenge_status:
type: string
x-nullable: true
description: 'Returns the details of availability of and enrollment of a guest into a specific challenge. Possible values are:
* unavailable: This status will be returned for "segment_auto_enrolment" when a guest is NOT added to the "user_feature_enrolment" table.
* enrolled: This status will be returned for:<br>
a) "universal_auto_enrolment" in all cases since all signed-up guests are automatically enrolled for the challenge.<br>
b) "segment_auto_enrolment" in cases when guests from the attached segment (to the challenge campaign) get added to the user_feature_enrolment table and are automatically enrolled for the challenge.<br>
* null: For older default "Segment" type challenges, the status will always be null.'
challenge_type:
type: string
description: 'Returns the type of challenge that is configured in the Punchh platform. Supported values are:
- receipt_qualification
- every_x_points
- segment'
occurrence:
type: string
description: 'Possible values are:
- **single** - Shows when restarting the challenge button is OFF in the campaign
- **multiple** - Shows when restarting the challenge button is ON in the campaign'
past_completions:
type: integer
description: The number of times the user has previously completed the challenge campaign.
enrollment_status:
type: string
x-stoplight:
id: rllwa7oi3kkzk
description: 'Indicates the user''s enrollment status in a challenge. Possible values:
* active - The user is currently enrolled in the challenge.
* expired - The user''s enrollment in the challenge has expired.'
enrolled_on:
type: string
x-stoplight:
id: cjcebn39q1977
format: date-time
description: Date and time (in ISO 8601 format) when the user enrolled in the challenge
enrollment_expires:
type: string
x-stoplight:
id: 69ktllcf2cv1a
description: Date and time (in ISO 8601 format) when the user's enrollment in the challenge expires
format: date-time
opted_in:
type: boolean
x-stoplight:
id: pilkx64h3cv1y
description: "Indicates whether the user has opted in to a challenge. Possible values:\n* true - The user has opted in. The mobile app should show the opt-out button on the challenge card if the opt-out feature is enabled for the business in the Punchh platform. \n* false - The user has not opted in. The mobile app should show the opt-in button on the challenge card if the opt-in feature is enabled for the business in the Punchh platform.\nContact your Punchh representative to update this configuration setting."
examples:
default:
value:
progress:
- completed_steps: 0
total_steps: 15
name: Potato Cheese Bites Club
description: Buy 10 get 1 free
image_url: IMAGE_URL_GOES_HERE
icon_url: IMAGE_URL_GOES_HERE
icon_completed_url: IMAGE_URL_GOES_HERE
start_date: '2019-06-24'
end_date: '2022-12-31'
gift_reason: New Challenge
miscellaneous: '{"detailedDescription": "Welcome to Potato Cheese ites club - Buy 10 get 1 free", "challengeType":"Clubs","nounDescription" : "Potato Cheese Bites"}'
challenge_reach: universal_auto_enrolment
challenge_status: enrolled
challenge_type: receipt_qualification
occurrence: multiple
past_completions: 0
challenge_id: 34
enrollment_status: active
enrolled_on: '2025-01-10T05:00:00+05:30'
enrollment_expires: '2025-04-10T05:00:00+05:30'
opted_in: true
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
Invalid or missing access token:
value:
unauthorized:
- An active access token must be used to query information about the current user.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
disabled_feature:
type: string
examples:
Challenges not enabled:
value:
errors:
disabled_feature: Business does not have challenges enabled.
summary: Fetch Challenge Details
description: Lists specific challenge details available for a business. The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration. <!-- Cockpit > Dashboard > Major Features > Enable Challenges? -->
operationId: mobile_Fetch_challenge_details
tags:
- Challenges
parameters:
- $ref: '#/components/parameters/signature'
- schema:
type: integer
in: path
name: id
required: true
description: Challenge ID
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- schema:
type: string
in: header
name: Accept-Language
description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese<br> The locales for a business are configured in the Punchh platform under <b>Administration > Business Profile > Address</b>. Click the <b>Alternate Languages</b> drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under <b>Marketing Automation > Campaign Management</b>.'
- $ref: '#/components/parameters/Authorization'
x-stoplight:
id: 71d1550be0f48
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
x-stoplight:
id: vw31qt20pos98
description: OAuth client ID provided by the business
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
access_token: ACCESS_TOKEN_GOES_HERE
/api2/mobile/users/challenges_listing:
get:
summary: List User Challenges
operationId: mobile_list_user_challenges
description: 'Returns all challenges associated with the logged-in user. Challenges are grouped into Available, Active, and Past categories, and include user-specific details such as enrollment status, progress, and relevant metadata required to render the challenges listing screen.
This API supports pagination for efficient data handling.
**Prerequisite**<br>
The Challenges feature must be enabled for the business in the Punchh platform. If not enabled, the API will return a 422 Unprocessable Entity error. Contact your Punchh representative to update this Punchh platform configuration.
<!-- Cockpit > Dashboard > Major Features > Enable Challenges? -->
**Challenge Categories**
**Available Challenges:**
All challenges available for opt-in when the opt-in feature is enabled. When the opt-in feature is disabled, all challenges are returned in the Active category.
**Active Challenges:**
All active challenges that the user has opted into, along with all challenges that do not require opt-in. When the opt-in feature is disabled, all challenges appear in this category.
Note: All segment-based challenges are also included in this category.
**Past Challenges:**
All challenges whose end date has already passed, deactivated challenges, as well as challenges for which the user has already earned a badge.'
tags:
- Challenges
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
- schema:
type: string
in: header
name: Accept-Language
description: 'Preferred language. Punchh supports multiple languages for the challenge name and description in the API response as per the locale specified in the Accept-Language request header for the campaign type challenge. Possible values: ar-kw for Arabic Kuwait, az for Azerbaijani, ca-ES for Catalan, en for English, en-CY for English-Cyprus, en-GB for English British, en-NZ for English-New Zealand, en-TT for English-Trinidad and Tobago, en-ca for English-Canada, es for Spanish, es-CR for Spanish Costa Rica, es-MX for Spanish Mexico, es-US for Spanish United States, fr for French, fr-ca for French-Canada, ro for Romania, vi for Vietnamese<br> The locales for a business are configured in the Punchh platform under <b>Administration > Business Profile > Address</b>. Click the <b>Alternate Languages</b> drop-down field to choose a language. In the Punchh platform, the admin of a business has to configure in the relevant language(s) the challenge name and description when creating or editing a campaign under <b>Marketing Automation > Campaign Management</b>.'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
count:
type: object
description: Object containing the count of challenges for the selected filter category. For example, if `filter`= active, the `count` object returns the count of active challenges. If no filter is specified, the counts for all challenge categories (`active_challenges`, `available_challenges`, `past_challenges`) are returned.
properties:
active_challenges:
type: integer
description: Total number of active challenges for the user. Returned when filter is "active" or when no filter is specified. The number of active challenges returned is determined by the per_page value.
available_challenges:
type: integer
description: Total number of available challenges for the user. Returned when filter is "available" or when no filter is specified. The number of available challenges returned is determined by the per_page value.
past_challenges:
type: integer
description: Total number of past challenges for the user. Returned when filter is "past" or when no filter is specified. The number of past challenges returned is determined by the per_page value.
available_challenges:
type: array
description: All challenges available for opt-in when the opt-in feature is enabled. When the opt-in feature is disabled, this array is empty as all challenges are returned in the active_challenges array.
items:
$ref: '#/components/schemas/ChallengeListingItem'
active_challenges:
type: array
description: 'All active challenges that the user has opted into, along with all challenges that do not require opt-in. When the opt-in feature is disabled, all challenges appear in this array. Note: All segment-based challenges are also included in this array.'
items:
$ref: '#/components/schemas/ChallengeListingItem'
past_challenges:
type: array
description: All challenges whose end date has already passed, as well as non-global challenges for which the user has already earned a badge.
items:
$ref: '#/components/schemas/ChallengeListingItem'
examples:
Response Example:
value:
count:
active_challenges: 12
available_challenges: []
active_challenges:
- challenge_id: 16438
name: Buy 5 Cheese Breadsticks
description: Buy 5 Cheese Breadsticks to earn bonus points
image_url: IMAGE_URL_GOES_HERE
icon_url: IMAGE_URL_GOES_HERE
icon_completed_url: IMAGE_URL_GOES_HERE
start_date: '2025-01-01'
end_date: '2025-12-31'
challenge_starting_at_tz: '2025-01-01T00:00:00+05:30'
challenge_expiring_at_tz: '2025-12-31T23:59:59+05:30'
challenge_reach: universal_auto_enrolment
challenge_status: enrolled
challenge_type: receipt_qualification
occurrence: single
past_completions: 1
opted_in: true
opted_out: false
explicit_opt_in: true
gift_reason: Buy 5 Cheese Breadsticks
mi
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-challenges-api-openapi.yml