info:
title: Subscription API - Mobile
version: '1.0'
description: Subscriptions is an add-on Punchh loyalty product that allows businesses to create subscription
plans to generate up-front revenue and offers benefits in addition to the standard benefits that unsubscribed
members of the loyalty program receive. The Subscription APIs are designed in a way that businesses
can programatically achieve the benefits of the subscription for their guest in a mobile app or website.
Also, there are aspects that require calling the API without any guest authentication (e.g., to control
the auto-renewal of the subscription on behalf of the guest).
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
paths:
/api2/mobile/subscriptions:
parameters: []
get:
summary: Fetch Active Purchasable Subscription Plans
operationId: post-api2-mobile-subscriptions
responses:
'200':
description: Success response if the business supports subscriptions
headers: {}
content:
application/json:
schema:
type: array
minItems: 1
uniqueItems: true
x-examples:
example-1:
- name: test v1
description: ''
miscellaneous: ''
validity: 30
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-05-28T13:59:47+05:30'
signup_end_date: '2021-05-18T13:59:47+05:30'
plan_id: 4
purchase_price: 12
image: test-image.png
- name: Test3
description: hello test 3
miscellaneous: null
validity: null
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-05-28T13:59:47+05:30'
signup_end_date: '2021-05-18T13:59:47+05:30'
plan_id: 3
purchase_price: 12
image: null
- name: Test2
description: hello test 2
miscellaneous: null
validity: null
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-05-28T13:59:47+05:30'
signup_end_date: '2021-05-18T13:59:47+05:30'
plan_id: 2
purchase_price: 12
image: null
- name: Test1
description: hello test
miscellaneous: null
validity: null
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-05-28T13:59:47+05:30'
signup_end_date: '2021-05-18T13:59:47+05:30'
plan_id: 1
purchase_price: 12
image: null
description: Array of the active subscription plans
items:
type: object
properties:
name:
type: string
minLength: 1
description: "Name of the subscription plan as provided by an admin at the time\
\ of subscription plan creation \n\nNote: The subscription `name`is returned in\
\ the language specified in the Accept-Language request header, provided the name\
\ has been translated into the relevant language in the Punchh platform. If the\
\ translation is not available, then no value is returned for this parameter in\
\ the API response. For example, if the header specifies “fr” (French), the subscription\
\ name is returned in French only if a French translation for the name is configured\
\ in the Punchh platform."
description:
type: string
description: 'Text description of the subscription plan as configured by an admin
on the subscription plan. This is used to explain the offerings of the subscription
plan to guests.
Note: The subscription `description` is returned in the language specified in
the Accept-Language request header, provided the description has been translated
into the relevant language in the Punchh platform. If the translation is not available,
then no value is returned for this parameter in the API response. For example,
if the header specifies “fr” (French), the subscription description is returned
in French only if a French translation for the description is configured in the
Punchh platform.'
miscellaneous:
type: string
description: 'Free-form text field that can be used by businesses to enter additional
information or a JSON code snippet for greater customization in the mobile app
Note: The subscription `miscellaneous` information is returned in the language
specified in the Accept-Language request header, provided it has been translated
into the relevant language in the Punchh platform. If the translation is not available,
then no value is returned for this parameter in the API response. For example,
if the header specifies “fr” (French), the subscription miscellaneous information
is returned in French only if a French translation for the miscellaneous is configured
in the Punchh platform.'
validity:
type: integer
format: int32
description: Number of days for which one unit of the subscription plan remains
valid after purchase
examples:
- 30
start_time:
type: string
minLength: 1
format: date-time
description: Date and time (in ISO 8601 format) from which the subscription plan
can be purchased by guests
examples:
- '2021-04-28T13:59:47+05:30'
end_time:
type: string
minLength: 1
format: date-time
description: Date and time (in ISO 8601 format) until which the subscription plan
can be purchased by guests
examples:
- '2021-04-28T13:59:47+05:30'
signup_start_date:
type: string
format: date-time
description: Date and time (in ISO 8601 format) after which the subscription plan
can be purchased by guests in advance. This can be used by businesses to make
a plan available for purchase before it actually starts. Any subscriptions bought
after this date and before the start date of the subscription plan will start
from the start_time of the Subscription Plan.
examples:
- '2023-04-28T13:59:47+05:30'
signup_end_date:
type: string
minLength: 1
format: date-time
description: Date and time (in ISO 8601 format) after which the subscription plan
cannot be purchased by guests. This is the purchase cut-off time, and a business
can use it to nudge guests into purchasing a subscription.
examples:
- '2021-04-28T13:59:47+05:30'
external_plan_identifier:
type: string
description: UPC/SKU of the subscription plan as present on third-party applications
of enterprise businesses and is configured on this subscription plan. This will
be stored in the database, and the business can use it for analytics purposes.
plan_id:
type: integer
format: int64
description: System-generated unique ID of a subscription plan created in the Punchh
platform
examples:
- 10
plan_image_url:
type: string
description: URL of the image that is configured for a specific subscription plan
purchase_price:
type: number
format: float
description: Cost of purchase of one unit of a subscription plan
examples:
- 12.32
image:
type: string
minLength: 1
description: Cover image of a subscription plan uploaded at the time of subscription
plan creation
examples:
- test-image.png
subscriber_capping:
type: number
description: Maximum number of unique active subscribers for a plan. If the number
of active subscribers reaches this limit, fresh purchases in that plan will be
stopped.
examples:
- 400
active_subscribers:
type: number
description: Number of unique active subscribers of the plan
examples:
- 251
timezone:
type: string
description: Time zone configured on the subscription plan (e.g., "America/Los_Angeles”
)
auto_renewing:
type: boolean
description: Determines whether a subscription issued from a subscription plan is
an auto-renewal plan or a single-use subscription plan, such as a seasonal pass. A
true value means the subscription plan gets automatically renewed, and a false
value means the subscription plan is a single-use plan. The mobile application
uses this value to determine if the auto_renewal of a subscription should be sent
as true or false with the [Purchase Subscription](/docs/dev-portal-mobile/3d3dba2eeed74-purchase-subscription)
API call.
enable_multibenefit:
type: boolean
description: "Indicates whether the subscription plan has multi-benefit enabled,\
\ allowing up to 5 benefits to be configured on a single plan. Once enabled on\
\ a plan, this setting cannot be disabled. \n\nThe Enable multibenefit\
\ setting under Wallet and Passes > Passes > Subscription Plans > Plan Details\
\ is only available when the multi-benefit subscription feature is enabled for\
\ the business. Contact your Punchh representative to update this Punchh platform\
\ configuration.\n"
purchasable_location_ids:
type: array
items:
type: integer
description: "An array of location IDs where the subscription plan is available\
\ for purchase. When configured, the plan will only appear as purchasable at these\
\ specific locations. If empty or not set, the plan is purchasable at all locations.\
\ \n\nReturned only when the multi-benefit subscription feature is enabled for\
\ the business, and the subscription plan's Enable multibenefit setting\
\ under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled\
\ in the Punchh platform. Contact your Punchh representative to update this Punchh\
\ platform configuration.\n"
purchasable_tag_ids:
type: array
items:
type: integer
description: "An array of location group (tag) IDs where the subscription plan is\
\ available for purchase. Location groups allow admins to scope purchasability\
\ to a set of locations defined by a reusable group. Works in conjunction with\
\ purchasable_location_ids — admins can select individual locations, location\
\ groups, or both. \n\nReturned only when the multi-benefit subscription feature\
\ is enabled for the business, and the subscription plan's Enable multibenefit\
\ setting under Wallet and Passes > Passes > Subscription Plans > Plan Details\
\ is enabled in the Punchh platform. Contact your Punchh representative to update\
\ this Punchh platform configuration.\n"
multiple_effective_locations_name:
type: string
description: "A human-readable display name summarizing the effective purchasable\
\ locations configured for the plan (e.g., selected location names or location\
\ group names). Useful for rendering location-scope information on guest-facing\
\ surfaces. \n\nReturned only when the multi-benefit subscription feature is enabled\
\ for the business, and the subscription plan's Enable multibenefit setting\
\ under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled\
\ in the Punchh platform. Contact your Punchh representative to update this Punchh\
\ platform configuration.\n"
examples:
example:
value:
- name: SUBSCRIPTION_NAME_GOES_HERE
description: DESCRIPTION_GOES_HERE
miscellaneous: MISC_INFORMATION_GOES_HERE
validity: 30
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-04-28T13:59:47+05:30'
signup_start_date: '2023-05-28T13:59:47+05:30'
signup_end_date: '2021-04-28T13:59:47+05:30'
external_plan_identifier: null
plan_id: 10
plan_image_url: PLAN_IMAGE_URL_GOES_HERE
purchase_price: 12.32
image: test-image.png
subscriber_capping: 500
active_subscribers: 251
timezone: Asia/Kolkata
auto_renewing: true
enable_multibenefit: true
purchasable_location_ids:
- 2
- 11
purchasable_tag_ids:
- 1
- 2
multiple_effective_locations_name: location-name-1, location-name-10, PineCrossing,
Eagle Creek
'400':
description: Bad Request
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
client: Required parameter missing or the value is empty.
properties:
errors:
type: object
required:
- client
properties:
client:
type: string
minLength: 1
examples:
- Required parameter missing or the value is empty.
required:
- errors
examples:
example:
value:
errors:
client: Required parameter missing or the value is empty.
'412':
description: Precondition Failed
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
properties:
errors:
type: object
properties:
invalid_signature:
type: array
items:
type: string
examples:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
examples:
example:
value:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
'422':
description: Unprocessable Entity
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
properties:
errors:
type: object
properties:
disabled_feature:
type: string
minLength: 1
examples:
- Your current loyalty program configuration does not support this feature. Please
connect with your Customer Success representative for resolution of the issue.
examples:
example:
value:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
description: This API returns all of the active subscription plans that are purchasable using the
mobile app and have their end time in the future.
parameters:
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/x-pch-digest'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Accept'
x-stoplight:
id: 9ad35b024c337
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
examples:
default:
value:
client: CLIENT_GOES_HERE
post:
summary: Purchase Subscription
operationId: post-api2-mobile-users-subscriptions
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
x-examples:
example-1:
subscription_id: '24'
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-04-28T13:59:47+05:30'
properties:
subscription_id:
type: integer
description: System-generated unique ID of the subscription plan that is issued for
a guest
start_time:
type: string
minLength: 1
format: date-time
description: Date and time (in ISO 8601 format) from which the subscription plan purchased
for the guest will become active
examples:
- '2021-04-28T13:59:47+05:30'
end_time:
type: string
minLength: 1
format: date-time
description: Date and time (in ISO 8601 format) until which the subscription plan
purchased for the guest will remain active
examples:
- '2021-04-28T13:59:47+05:30'
external_plan_identifier:
type: string
description: UPC/SKU of the subscription plan as present on third-party applications
of enterprise businesses and is configured on this subscription plan. This will
be stored in the database, and the business can use it for analytics purposes.
location_id:
type: integer
x-stoplight:
id: ibp0bghfldjdb
description: ID of a valid Punchh location where the subscription plan is purchased.
It identifies the origin of the subscription purchase for the loyalty guest. If
an invalid or missing location_id is passed, the API returns a 400 Bad Request error
with the message "Invalid or missing location_id".
required:
- subscription_id
- start_time
- end_time
examples:
example:
value:
subscription_id: 23
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-04-28T13:59:47+05:30'
external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER_GOES_HERE
location_id: 12345
'400':
description: 'Bad Request
- Invalid or missing location_id'
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
client: Required parameter missing or value empty.
properties:
errors:
type: object
required:
- client
properties:
client:
type: string
minLength: 1
examples:
- Required parameter missing or value empty.
required:
- errors
examples:
example:
value:
errors:
client: Required parameter missing or value empty.
'401':
description: Unauthorized
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
properties:
errors:
type: object
required:
- unauthorized
properties:
unauthorized:
type: array
items:
type: string
examples:
- An active access token must be used to query information about the current
user.
required:
- errors
examples:
example:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
'412':
description: Precondition Failed
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
properties:
errors:
type: object
required:
- invalid_signature
properties:
invalid_signature:
type: array
items:
type: string
examples:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
required:
- errors
examples:
example:
value:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
x-examples:
example-1:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
properties:
errors:
type: object
properties:
disabled_feature:
type: string
minLength: 1
examples:
- Your current loyalty program configuration does not support this feature. Please
connect with your Customer Success representative for resolution of the issue.
required:
- errors
examples:
Subscription Feature is not configured:
value:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
Invalid Plan ID:
value:
errors:
invalid_request: Invalid Plan ID
Auto renewal is set as true for a single use subscription:
value:
errors:
base:
- This is a single use subscription and cannot be renewed automatically. Please
check request to send 'auto_renewal' as 'false'.
Purchase price Null or Negative:
value:
errors:
price: Price must be greater than or equal to 0
Start time Null:
value:
errors:
start_time: Start time cannot be blank
End time is Null:
value:
errors:
end_time: End time cannot be blank
Purchase call made is past the signup end time or end time of the plan:
value:
errors:
plan_expired: Plan has expired
Recurring payments option is disabled:
value:
errors:
recurring_payment_off_for_adapter:
- Payment Service not available.
description: 'This API supports the purchase of a subscription plan created in the Punchh platform.
If the Single Use setting is enabled for the subscription plan, and if you send auto_renewal as
`true` in the Purchase Subscription API, then the API returns an error: This is a single use subscription
and cannot be renewed automatically. Please check the request to send auto_renewal as false.'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/x-pch-digest'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Accept-Language-2'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 3d3dba2eeed74
requestBody:
content:
application/json:
schema:
type: object
x-examples:
example-1:
plan_id: 23
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-05-28T13:59:47+05:30'
purchase_price: '23.34'
auto_renewal: 'true'
properties:
client:
type: string
description: OAuth client ID provided by the business
examples:
- CLIENT_GOES_HERE
plan_id:
type: integer
description: System-generated unique ID of a subscription plan created in the Punchh
platform. A subscription based on this plan ID will be issued to the guest when a
purchase call is made.
examples:
- 23
external_plan_identifier:
type: string
description: UPC/SKU of the subscription plan as present on third-party applications
of enterprise businesses and is configured on this subscription plan. This will be
stored in the database, and the business can use it for analytics purposes. This value
can be used to make the purchase of the subscription plan instead of using the “plan_id”.
start_time:
type: string
minLength: 1
format: date-time
description: 'Date and time (in ISO 8601 format) from which the subscription being issued
will become active '
examples:
- '2021-04-28T13:59:47+05:30'
end_time:
type: string
minLength: 1
format: date-time
description: 'Date and time (in ISO 8601 format) until which the subscription being
issued will remain active '
examples:
- '2021-04-28T13:59:47+05:30'
purchase_price:
type: number
format: float
description: Price at which one unit of the subscription plan is purchased
examples:
- 23.45
auto_renewal:
type: boolean
default: false
description: A guest’s preference of having a newly purchased subscription plan get
automatically renewed per the plan's schedule. Third parties where auto renewal is
considered default should send this value as "true". The mobile application uses the
value in the auto_renewing response parameter in the [Fetch Active Purchasable Subscription
Plans](/docs/dev-portal-mobile/9ad35b024c337-fetch-active-purchasable-subscription-plans)
API to determine if the auto-renewal of a subscription should be sent as true or false
during the subscription purchase.
location_id:
type: integer
x-stoplight:
id: albq3ca1wecfx
description: ID of the location where the subscription plan is purchased. It identifies
the origin of the subscription purchase for the loyalty guest. If an invalid or missing
location_id is passed, the API returns a 400 Bad Request error with the message "Invalid
or missing location_id".
payment_card_uuid:
type: string
description: Unique digital identifier/token of the user's credit card can be referred
to as the uuid of the saved payment card, required if a saved payment card is used
for payments. The transaction token is issued by a payment processor used by a business.
required:
- client
- plan_id
- start_time
- end_time
- purchase_price
- auto_renewal
- location_id
examples:
example:
value:
client: CLIENT_GOES_HERE
plan_id: 23
start_time: '2021-04-28T13:59:47+05:30'
end_time: '2021-04-28T13:59:47+05:30'
purchase_price: '23.09'
auto_renewal: true
payment_card_uuid: PAYMENT_CARD_UUID_GOES_HERE
external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER_GOES_HERE
location_id: 12345
description: ''
/api2/mobile/user_subscriptions:
get:
summary: Fetch Subscription Plans for a User
operationId: post-api2-mobile-subscriptions
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
x-examples:
example-1:
subscriptions:
- subscription_id: 19
start_time: '2021-05-18T21:09:38+05:30'
end_time: '2021-06-03T21:09:38+05:30'
plan_id: 9
image: test-image.png
name: fuel_price
description: ''
miscellaneous: ''
status: Active
benefits:
- benefit_id: 3
discounts:
- discount_id: 7
threshold: 40
discounted_value: 80
discounted_quantity: 40
- discount_id: 8
threshold: 1000
discounted_value: 1000
discounted_quantity: 1000
properties:
has_any_subscriptions:
type: boolean
x-stoplight:
id: ckkpgl22k7pqr
description: 'Indicates whether or not a user''s account currently has an active subscription
or has ever had an active subscription. This parameter can be used by developers
to customize the app experience as per the needs of the business. Possible values:
true, false'
subscriptions:
type: array
uniqueItems: true
minItems: 1
description: Array object containing different subscriptions issued to the guest
items:
type: object
properties:
subscription_id:
type: number
description: System-generated unique ID of the subscription that is issued to
the guest
start_time:
type: string
minLength: 1
description: Date and time (in ISO 8601 format) from which this current subscription
becomes active for a guest
end_time:
type: string
minLength: 1
description: Date and time (in ISO 8601 format) until which this current subscription
remains active for a guest
plan_id:
type: number
description: System-generated unique ID of the plan against which this subscription
is issued for the guest
image:
type: string
minLength: 1
description: Cover image of a subscription plan uploaded at the time of subscription
plan creation
cancellation_reason:
type: string
description: Reason for cancellation as sent to Punchh at the time of cancellation
cancelled_at:
type: string
format: date-time
description: Date and time (in ISO 8601 format) when the subscription is cancelled
name:
type: string
minLength: 1
description: 'Name of the subscription plan as provided by the admin at the
time of subscription plan creation.
Note: The subscription `name` is returned in the language specified in the
Accept-Language request header, provided the name has been translated into
the relevant language in the Punchh platform. If the translation is not available,
then no value is returned for this parameter in the API response. For example,
if the header specifies “fr” (French), the subscription name is returned in
French only if a French translation for the name is configured in the Punchh
platform.
'
description:
type: string
description: 'Text description of the subscription plan as configured by the
admin on the subscription plan. This is used to explain the offerings of the
subscription plan to guests.
Note: The subscription `description` is returned in the language specified
in the Accept-Language request header, provided the description has been translated
into the relevant language in the Punchh platform. If the translation is not
available, then no value is returned for this parameter in the API response.
For example, if the header specifies “fr” (French), the subscription description
is returned in French only if a French translation for the description is
configured in the Punchh platform.
'
miscellaneous:
type: string
description: 'Free-form text field that can be used by businesses to enter additional
information or a JSON code snippet for greater customization in the mobile
app.
Note: The subscription `miscellaneous` information is returned in the language
specified in the Accept-Language request header, provided it has been translated
into the relevant language in the Punchh platform. If the translation is not
available, then no value is returned for this parameter in the API response.
For example, if the header specifies “fr” (French), the subscription miscellaneous
information is returned in French only if a French translation for the miscellaneous
is configured in the Punchh platform.
'
status:
type: string
minLength: 1
description: "Subscriptions issued to a guest can have multiple statuses. Currently\
\ supported statuses are:\n1. active: The subscription is active and the guest\
\ can enjoy the benefits until its end_time.\n2. expired: The subscription\
\ is not renewed and expired. The end_time of the subscription is in the past,\
\ and it was not cancelled before its expiration.\n3. soft_cancelled: The\
\ subscription is cancelled either by the guest or by an admin. The benefits\
\ remain valid until the end_time. \n4. hard_cancelled: The subscription is\
\ cancelled by an admin and the benefits become invalid immediately from the\
\ time of cancellation.\n5. renewed: The subscription is renewed.\n"
benefits:
type: array
uniqueItems: true
minItems: 1
maxItems: 5
description: 'A subscription plan may contain multiple benefits. This object
includes the details of benefits available to the guest for this subscription
ID. '
items:
type: object
properties:
benefit_id:
type: number
description: System-generated unique ID of the benefit that is configured
on the subscription plan and is issued to the guest for this subscription
benefit_name:
type: string
description: 'Name of the individual benefit, set in Benefits & Rules
(Wallet and Passes > Subscription Plans) in the Punchh platform. Up
to 5 benefits per plan. Note: This parameter is returned when enabled
for the business. Contact your Punchh representative to update this
platform configuration.'
benefit_description:
type: string
description: 'Description of the individual benefit, set in Benefits &
Rules (Wallet and Passes > Subscription Plans) in the Punchh platform.
Note: This parameter is returned when enabled for the business. Contact
your Punchh representative to update this platform configuration.'
benefit_priority:
type: integer
description: 'Sets the order in which benefits are applied to a transaction
and displayed in the mobile app within a multi-benefit subscription
plan. Lower value = higher priority (starts at 1 and goes up to the
number of benefits in the plan). Priority ordering matters when benefits
can affect each other''s eligibility — for example, applying a free
item first might drop the bill below a threshold needed for a percentage
discount. The benefit priority order is locked once the plan becomes
visible to customers. Note: This parameter is returned when enabled
for the business. Contact your Punchh representative to update this
platform configuration.'
benefit_type:
type: string
description: Type of the benefit
examples:
- sku_discounting
discounts:
type: array
uniqueItems: true
minItems: 1
description: A benefit may contain multiple discounts. This object contains
the details of different discounts issued to the guest for this subscription.
items:
type: object
properties:
discount_id:
type: number
description: System-generated unique ID of the discounting rule
configured under the benefit.
occurrence:
type: number
x-nullable: true
description: 'The number of times this discount can be applied.
A null value means no specific occurrence limit is set. Note:
This parameter is returned when enabled for the business. Contact
your Punchh representative to update this platform configuration.'
gap_units:
type: number
x-nullable: true
description: 'The number of time units (defined by gap_unit_type)
that must elapse between consecutive uses of this discount. A
null value means no gap restriction. Note: This parameter is returned
when enabled for the business. Contact your Punchh representative
to update this platform configuration.'
gap_unit_type:
type: string
description: 'The unit of time for the gap_units value (e.g., "hours").
Defines the cooldown period type between discount usages. Note:
This parameter is returned when enabled for the business. Contact
your Punchh representative to update this platform configuration.'
start_time:
type: string
format: date-time
x-nullable: true
description: 'The start date/time from which this discount becomes
active. A null value means no specific start time constraint —
the discount is available from the subscription''s start. Note:
This parameter is returned when enabled for the business. Contact
your Punchh representative to update this platform configuration.'
end_time:
type: string
format: date-time
x-nullable: true
description: 'The end date/time after which this discount expires.
A null value means no specific end time constraint — the discount
remains valid until the subscription ends. Note: This parameter
is returned when enabled for the business. Contact your Punchh
representative to update this platform configuration.'
threshold:
type: number
description: 'Maximum number of units that can be discounted for
this particular discounting rule. '
threshold_discount:
type: number
description: 'The maximum discount value that can be applied per
use of this discounting rule (e.g., 100.0 means up to 100 units
of % or $, depending on discount_type). Note: This parameter is
returned when enabled for the business. Contact your Punchh representative
to update this platform configuration.'
discount_type:
type: string
description: 'The type of discounting rule configured under the
benefit. Common values include "%_or_$_off" (percentage or dollar
amount off), "sku_discounting" (item-level discount), "target_price_bundle_advanced"
(bundle pricing), and "receipt_level_discount" (order-level discount).
Note: This parameter is returned when enabled for the business.
Contact your Punchh representative to update this platform configuration.'
discounted_value:
type: number
description: Value of discounts given as per this discounting rule.
discounted_quantity:
type: number
description: Number of units discounted as per this discounting
rule.
external_plan_identifier:
type: string
description: UPC/SKU of the subscription plan as present on third-party applications
of enterprise businesses and is configured on this subscription plan. This
will be stored in the database, and the business can use it for analytics
purposes. This value can be used to make the purchase of the subscription
plan instead of using the “plan_id”.
plan_image_url:
type: string
description: URL of the image that is configured for a specific subscription
plan
renewed_on:
type: string
description: Date and time when the subscription was renewed on
format: date-time
upcoming_renewal:
type: string
description: Date and time of next renewal of the subscription
format: date-time
examples:
- '2023-05-11T05:00:00+05:30'
purchase_price:
type: integer
description: amount paid for the subscription
auto_renewal:
type: boolean
description: A guest’s preference of having a newly purchased subscription plan
get automatically renewed per the plan's schedule. Third parties where auto
renewal is considered default should send this value as "true".
default: true
payment_card:
type: object
description: The object shows payment card settings
properties:
uuid:
type: string
description: Saved payment card UUID
nickname:
type: string
description: Payment card nickname as set by the user
preferred:
type: boolean
description: Whether this card will be selected as the default card or not
when the user makes a payment through the mobile app. If the value is
set to true, this card will be selected as the default card for payments.
card_details:
type: object
description: The object shows payment card details
properties:
name_on_card:
type: string
description: Cardholder name
' card_type':
type: string
description: Card type like VISA, Mastercard, Amex, etc
cc_4:
type: string
description: Last 4 digits of the card
expiry_month:
type: string
description: Expiry month of the card
expiry_year:
type: string
description: Expiry year of the card
cancellation_feedback:
type: string
description: Subjective feedback that a guest provides when cancelling a subscription
from the mobile application, or the feedback that an administrator provides
when cancelling a subscription from the Punchh platform.
examples:
Success:
value:
has_any_subscriptions: true
subscriptions:
- subscription_id: 19
start_time: '2021-05-18T21:09:38+05:30'
end_time: '2021-06-03T21:09:38+05:30'
plan_id: 9
image: test-image.png
cancellation_reason: Found better alternative
cancelled_at: null
name: fuel_price
description: ''
miscellaneous: ''
status: Active
external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER_GOES_HERE
plan_image_url: PLAN_IMAGE_URL_GOES_HERE
renewed_on: '2023-04-10T05:00:00+05:30'
upcoming_renewal: '2023-05-11T05:00:00+05:30'
purchase_price: 100
auto_renewal: true
benefits:
- benefit_id: 3
benefit_type: sku_discounting
benefit_name: Free Coffee
benefit_description: Get a free coffee on your next visit
benefit_priority: 1
discounts:
- discount_id: 7
occurrence: 5
gap_units: 24
gap_unit_type: hours
start_time: '2023-05-18T00:00:00+05:30'
end_time: '2023-06-03T23:59:59+05:30'
threshold: 40
threshold_discount: 100
discount_type: sku_discounting
discounted_value: 80
discounted_quantity: 40
- discount_id: 8
occurrence: null
gap_units: null
gap_unit_type: hours
start_time: null
end_time: null
threshold: 1000
threshold_discount: 100
discount_type: sku_discounting
discounted_value: 1000
discounted_quantity: 1000
- benefit_id: 4
benefit_type: sku_discounting
benefit_name: Fuel Discount
benefit_description: Get 10% off on fuel purchases
benefit_priority: 2
discounts:
- discount_id: 7
occurrence: 10
gap_units: null
gap_unit_type: hours
start_time: null
end_time: null
threshold: 40
threshold_discount: 50
discount_type: '%_or_$_off'
discounted_value: 80
discounted_quantity: 40
- discount_id: 8
occurrence: null
gap_units: null
gap_unit_type: hours
start_time: null
end_time: null
threshold: 1000
threshold_discount: 100
discount_type: receipt_level_discount
discounted_value: 1000
discounted_quantity: 1000
payment_card:
uuid: SAVED_CARD_UUID
nickname: My card
card_details:
name_on_card: CARDHOLDER_NAME_GOES_HERE
cc_4: '1111'
card_type: Visa
expiry_month: 09
expiry_year: '23'
cancellation_feedback: Found better alternative
'400':
description: 'Bad Request: Sending an invalid/empty client'
content:
application/json:
schema:
type: object
x-examples:
example-1:
errors:
client: Required parameter missing or the value is empty.
properties:
errors:
type: object
properties:
client:
type: string
minLength: 1
examples:
- Required parameter missing or the value is empty.
examples:
Sending an invalid/empty client:
value:
errors:
client: Required parameter missing or the value is empty.
'401':
description: 'Unauthorized: Sending an invalid/empty access token'
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
- An active access token must be used to query information about the current
user.
examples:
- An active access token must be used to query information about the current user.
examples:
Sending an invalid/empty access token:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
'412':
description: 'Precondition Failed: Invalid Signature'
content:
application/json:
schema:
type: object
x-examples:
example-1:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
properties:
errors:
type: object
properties:
invalid_signature:
type: array
items:
type: string
examples:
Invalid Signature:
value:
errors:
invalid_signature:
- Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
'422':
description: Unprocessable Entity
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
properties:
errors:
type: object
properties:
disabled_feature:
type: string
minLength: 1
examples:
- Your current loyalty program configuration does not support this feature. Please
connect with your Customer Success representative for resolution of the issue.
examples:
example:
value:
errors:
disabled_feature: Your current loyalty program configuration does not support this
feature. Please connect with your Customer Success representative for resolution
of the issue.
description: "This API returns the subscriptions attached to a guest's profile. While the response\
\ can be filtered based on \"status\" and \"past_subscriptions\", the default response will include\
\ subscriptions that are either \"active\" or \"soft_cancelled\" and have their end time in the\
\ future.\n "
parameters:
- $ref: '#/components/parameters/x-pch-digest'
- $ref: '#/components/parameters/Authorization'
- schema:
type: string
in: query
name: filter
description: 'Filter subscription by status and past_subscriptions.
If the status is
not sent, the API returns subscriptions that are `active`, `soft_cancelled`, and have an end_time
that is not in the past. Supported "filter” values are ''''active'''', ''''expired'''', and
''''cancelled''''.
When the API call is made using the past_subscriptions filter, the
response returns only such subscriptions that have their end date/time in the past. The status
against each subscription can have these values: ‘expired’, ‘renewed’, ‘soft_cancelled’, and
‘hard_cancelled’.'''
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Accept'
x-stoplight:
id: e11913b8ff70c
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
description: ''
parameters: []
/api2/mobile/redemptions/subscription:
post:
summary: Generate a Redemption Code for Subscription Redemption
operationId: post-api2-mobile-redemptions-subscription
responses:
'200':
description: Success response if a redemption code is generated for the subscription redemption
content:
application/json:
schema:
type: object
x-examples: null
properties:
redemption_status:
type: string
description: 'Status of the redemption. Any one of these values is returned:
* redeemable: The redemption can be redeemed at the POS.
* expired: The redemption has expired and becomes unusable for the user.
* honoured: The redemption has already been processed successfully and redeemed
by the user at the POS.
* cancelled: The redemption can be voided by a user by approaching the POS in case
a redemption is done by mistake and the user wants to cancel it.'
created_at:
type: string
description: Date and time when the redemption was created in the system
format: date-time
examples:
- '2023-05-09T07:44:38Z'
redeemable_id:
type: integer
description: Unique ID of the redeemable
location_id:
type: integer
description: Location ID associated with redemption at which the redemption code is
generated. If no location ID is provided, then it returns the location ID for the
default location.
redemption_image_url:
type: string
description: URL of the image depicting the redeemable. It can be displayed in the
mobile app.
redemption_message:
type: string
description: A descriptive message that tells the user what the user has redeemed
updated_at:
type: string
format: date-time
description: Date and time when the redemption was updated in the system
examples:
- '2023-05-09T07:44:38Z'
redeemable_description:
type: string
description: Description of the redeemable
redeemable_image_url:
type: string
description: URL of the image depicting the redeemable. It can be displayed in the
mobile app.
redemption_id:
type: integer
format: int64
description: Unique ID of the redemption that has been created
redemption_tracking_code:
type: string
description: Code that a user must provide at the POS to receive the redeemed reward
expiring_at:
type: string
format: date-time
description: Date and time when the redemption_tracking_code expires and the user
cannot use it at the POS
examples:
- '2023-05-09T07:54:38Z'
redeemable_name:
type: string
description: Name of the redeemable
redeemed_value:
type: string
description: '* In the case of a business with banked_currency, a currency value will
be returned. For example, 10 would mean $10.
* In the case of a business without banked_currency, points will be returned. For
example, 10 would mean 10 points.
* For subscriptions, a null value will be returned.'
subscription_id:
type: string
description: Unique ID of the subscription for which redemption is done
subscription_plan_id:
type: integer
description: System-generated unique ID of a subscription plan created in the Punchh
platform
subscription_plan_name:
type: string
description: Name of the subscription plan from which the subscription is issued
subscription_plan_description:
type: string
description: Description of the subscription plan from which the subscription is issued
subscription_plan_image_url:
type: string
description: Image URL of the subscription plan from which the subscription is issued
redemption_type:
type: string
description: 'The parameter value helps the mobile application differentiate between
older redemption types and subscription redemption. Valid value: SubscriptionRedemption'
examples:
example:
value:
redemption_status: redeemable
created_at: '2023-05-09T07:44:38Z'
redeemable_id: null
location_id: 304252
redemption_image_url: REDEMPTION_IMAGE_URL_GOES_HERE
redemption_message: ''
updated_at: '2023-05-09T07:44:38Z'
redeemable_description: null
redeemable_image_url: REDEEMABLE_IMAGE_URL_GOES_HERE
subscription_id: '498699'
subscription_plan_id: 44
subscription_plan_name: Super Value Subscription
subscription_plan_description: 10% discount on entire receipt amount (capped at $20)
| Redeemable Once Per Day
subscription_plan_image_url: SUBSCRIPTION_PLAN_IMAGE_URL_GOES_HERE
redemption_type: SubscriptionRedemption
redemption_id: 515404156
redemption_tracking_code: '8066490'
expiring_at: '2023-05-09T07:54:38Z'
redeemable_name: REDEEMABLE_NAME_GOES_HERE
redeemed_value: null
'400':
description: Bad Request
content:
application/json:
schema:
type: object
x-examples: null
properties:
errors:
type: object
required:
- client
properties:
client:
type: string
minLength: 1
examples:
- Required parameter missing or value empty.
required:
- errors
examples:
example:
value:
errors:
client: Required parameter missing or value empty.
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
example:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
'412':
description: Precondition Failed
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_signature:
type: array
items:
type: string
examples:
example:
value:
errors:
invalid_signature:
- Signature doesn't match. For information about generating the x-pch-digest header,
see https://developers.punchh.com.
'422':
description: 'Unprocessable Entity: Invalid Subscription ID'
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Invalid Subscription ID:
value:
error: Invalid User Subscription
description: This API generates a subscription-related redemption code within the mobile application.
Using this API, guests can generate the subscription-related redemption code from the mobile application
and use it at the POS or in the online ordering app to redeem subscription-related benefits.
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/x-pch-digest'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Accept-Timezone'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Accept-Language-2'
x-stoplight:
id: 99afe0f5c2a1b
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
subscription_id:
type: string
description: ID of the subscription for which the redemption code has to be generated
required:
- client
- subscription_id
examples:
default:
value:
client: CLIENT_GOES_HERE
subscription_id: '23'
parameters: []
/api2/mobile/subscriptions/cancel:
put:
summary: Cancel Subscription (Turn off Auto Renewal)
operationId: put-api2-mobile-subscriptions-cancel
responses:
'200':
description: Successful Response | 200 OK
content:
application/json:
schema:
type: array
items:
type: string
default: Subscription auto renewal canceled.
minLength: 1
examples:
default:
value:
- Subscription auto renewal canceled.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
parameter_name:
type: string
minLength: 1
examples:
- cancellation_reason_id
examples:
Sending an invalid/blank client:
value:
errors:
client: Required parameter missing or the value is empty.
Sending an invalid/blank cancellation reason ID:
value:
errors:
cancellation_reason_id: Required parameter missing or the value is empty.
'401':
description: 'Unauthorized: Sending an invalid/empty access token'
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
Sending an invalid/empty access token:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
'412':
description: 'Precondition Failed: Invalid Signature'
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_signature:
type: string
examples:
- invalid_signature
examples:
Invalid Signature:
value:
errors:
invalid_signature:
- Signature doesn't match. For information about generating the x-pch-digest header,
see https://developers.punchh.com.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
error_name:
type: array
items:
type: string
examples:
- already_canceled
examples:
- already_canceled
examples:
Cancelling an already renewed subscription:
value:
errors:
cancel_renewed_subscription:
- This subscription is already renewed. You can cancel the newly issued Subscription
which will remain valid till its end date.
Cancelling an already cancelled subscription:
value:
errors:
already_canceled:
- Subscription is already canceled.
Sending an invalid subscription ID:
value:
errors:
invalid_subscription:
- Invalid User Subscription.
description: This API allows the user to cancel an active subscription (turn off auto renewal for
the subscription). This is a soft cancellation wherein the benefits remain valid until the end
time of the subscription.
parameters:
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Accept-Language-2'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-pch-digest'
x-stoplight:
id: 0a7820db68f94
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
minLength: 1
subscription_id:
type: string
description: System-generated unique ID of the subscription of the guest that needs
to be cancelled
examples:
- '26'
cancellation_reason_id:
type: integer
description: Unique ID of the business-configured cancellation reason that a guest selects
when cancelling a subscription. You can find cancellation reason IDs under the subscriptions
object in the [Program Meta API](/docs/dev-portal-mobile/2617bed9b0e8e-program-meta-api)
response.
cancellation_feedback:
type: string
description: Subjective feedback that can be captured from guests when they cancel a
subscription from the mobile application. The maximum length supported is 225 characters.
required:
- client
- subscription_id
- cancellation_reason_id
- cancellation_feedback
examples:
default:
value:
subscription_id: '1'
cancellation_feedback: ''
cancellation_reason_id: 1
x-stoplight:
id: 07e110e1097d2
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
schemas: {}
parameters:
User-Agent:
schema:
type: string
default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
name: User-Agent
in: header
required: true
description: Used to identify the software, device, and application initiating the request, providing
information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
Accept-Language:
schema:
type: string
default: en
name: Accept-Language
in: header
required: false
description: 'Preferred language. Punchh supports multiple languages for the subscription plan `name`,
`description`, and `miscellaneous` parameters in the API response as per the locale specified
in the Accept-Language request header. Possible values: es for Spanish, fr for French, fr-ca for
French-Canada, en-CY for English-Cyprus, ro for Romania, es-US for Spanish United States, etc.
The locales for a business are configured in the Punchh platform under Administration > Business
Profile > Address > Alternate Languages. Administrators have to configure Name, Description,
and Miscellaneous fields in the relevant language(s) on the subscription plan in the Punchh platform
under Wallet and Passes > Subscription Plans. If these fields are not configured in Punchh
in the language specified in the Accept-Language request header, then the API response will include
the subscription plan `name`, `description`, and `miscellaneous` parameters with empty values. '
x-pch-digest:
schema:
type: string
name: x-pch-digest
in: header
required: true
description: Signature generated using the request path, body, and OAuth secret provided by the
business. For details, see [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256).
Accept:
schema:
type: string
default: application/json
name: Accept
in: header
required: true
description: Advertises which content types the client can understand
Authorization:
schema:
type: string
default: Bearer ACCESS_TOKEN_GOES_HERE
name: Authorization
in: header
required: true
description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
Content-Type:
schema:
type: string
default: application/json
name: Content-Type
in: header
required: true
description: Set this header to application/json
Accept-Timezone:
schema:
type: string
default: Etc/UTC
name: Accept-Timezone
in: header
required: false
description: Used to indicate the time zone in which you would like the date and time information
in the response to be formatted
Accept-Language-2:
schema:
type: string
default: en
name: Accept-Language
in: header
required: false
description: Preferred language
securitySchemes: {}
x-ext-urls: {}