Punchh Redemptions 1.0 (Legacy) API - Mobile
For more information, see Online Ordering Module 5 - Redemptions. Published by PAR on the mobile section of the PAR developer portal; 6 operations. Certification required.
OpenAPI Specification
info:
title: Redemptions 1.0 (Legacy) API - Mobile
version: '1.0'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
description: For more information, see [Online Ordering Module 5 - Redemptions](/docs/dev-portal-online-ordering/80afbc759ded2-online-ordering-api-certification-tutorial-module-5-redemptions-overview).
paths:
/api2/mobile/redemptions/{redemption_id}:
delete:
summary: Cancel Redemption (Redemptions 1.0)
operationId: delete-api2-mobile-redemptions
responses:
'200':
description: OK - Redemption successfully cancelled
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
errors:
type: string
x-stoplight:
id: m5t0iepx0dqg5
examples:
Sending an invalid redemption ID:
value:
errors: This Redemption is an invalid redemption or It is not for this guest
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: string
x-stoplight:
id: p3shfxdabejn2
examples:
' Cancelling an expired redemption':
value:
errors: This Redemption cannot be cancelled because the Redemption code has been expired
Cancelling a cancelled redemption:
value:
errors: Redemption cancellation failed. This redemption has already been cancelled.
Cancelling an honored redemption:
value:
errors: This Redemption cannot be cancelled because the Redemption code has been honoured
/ redeemed
description: "Allows users to cancel their redemption if it has not been processed, enabling them\
\ to select a new one without waiting for the redemption code to expire. Once the redemption is\
\ processed, the user cannot cancel it.\n\nThe `cancel_redemption` response parameter in the [Program\
\ Meta](/docs/dev-portal-mobile/2617bed9b0e8e-program-meta) API indicates whether the user can\
\ revoke (cancel) the generated redemption code from the brand's app. This is controlled by hiding\
\ or displaying the cancel redemption button on the brand's app. Contact your Punchh representative\
\ to update this Punchh platform configuration.\n<!--Whitelabel > Mobile Configuration > Loyalty\
\ > Cancel Redemption-->\n\n<b> Cancel Redemption Failure Scenarios</b>\n\nThe API returns an\
\ error if the discount associated with the redemption you want to cancel is invalid, already\
\ redeemed/honored, cancelled, or expired. \n\n<b>View Cancelled Redemption Status </b>\n\nThe\
\ Punchh platform displays the cancelled redemption on the user’s timeline and in the Account\
\ History tab. \n\nIf you have a redemption code for the cancelled redemption, you can use the\
\ [Search Redemption Code](/docs/dev-portal-platform-functions/ac8e06639a62c-search-redemption-code)\
\ API to verify the status of the cancelled redemption. "
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept-Language'
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
x-stoplight:
id: htkodzobkpi6f
description: OAuth client ID provided by the business
required:
- client
examples:
Example:
value:
client: CLIENT_GOES_HERE
redemption_id: 490636366
description: ''
parameters:
- schema:
type: integer
format: int64
name: redemption_id
in: path
required: true
description: Redemption ID returned when the redemption is created
x-stoplight:
id: 90fd89b67ddc1
/api2/mobile/redemptions/banked_currency:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/redemption_details'
examples:
default:
value:
redemption_status: redeemable
created_at: '2016-05-25T06:41:37-04:00'
redeemable_id: null
location_id: 304361
redemption_image_url: IMAGE_URL_GOES_HERE
redemption_message: Message associated with the redemption.
updated_at: '2016-05-25T06:41:37-04:00'
redeemable_description: ''
redemption_id: 1822896
redemption_tracking_code: '7246338'
expiring_at: '2016-05-25T08:41:37-04:00'
redeemable_name: null
campaign_name: Mass Campaign Offer
redeemed_value: '10'
'400':
description: ''
summary: Create Redemption Using Banked Currency (Redemptions 1.0)
description: Creates a redemption using a currency amount. The amount is deducted from a user's
available banked currency.
operationId: mobile_create_redemption_using_banked_currency
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/punchh-app-device-id'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: a7be5bbb2906d
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
banked_currency:
type: number
format: double
description: The amount of banked currency with which a redemption code has to be created
location_id:
type: integer
description: Location ID at which the redemption code is generated. If no location ID
is provided, then it returns the ID of the default location.
latitude:
type: string
description: Latitude coordinate of the redemption location
longitude:
type: string
description: Longitude coordinate of the redemption location
gps_accuracy:
type: integer
description: Accuracy of a user's device GPS
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
banked_currency: 10
location_id: 304155
latitude: '26.9167509'
longitude: '75.8136926'
gps_accuracy: 27
/api2/mobile/redemptions/visits:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/redemption_details'
examples:
default:
value:
redemption_status: redeemable
created_at: '2016-05-25T06:41:37-04:00'
redeemable_id: null
location_id: 304361
redemption_image_url: IMAGE_URL_GOES_HERE
redemption_message: Message associated with the redemption.
updated_at: '2016-05-25T06:41:37-04:00'
redeemable_description: ''
redemption_id: 1822896
redemption_tracking_code: '7246338'
expiring_at: '2016-05-25T08:41:37-04:00'
redeemable_name: null
campaign_name: Mass Campaign Offer
redeemed_value: '10'
'400':
description: ''
summary: Create Redemption Using Visits (Redemptions 1.0)
description: Creates a redemption for an unredeemed card. This is for use with visit-based businesses.
operationId: mobile_create_redemption_using_visits
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
x-stoplight:
id: 1ae3d27ce6a88
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
location_id:
type: integer
description: Location ID at which a user wants to do the redemption. If a particular
location ID is provided in the request, the redemption will be valid only at that
location and will not be possible at any other.
latitude:
type: string
description: Latitude coordinate of the redemption location. Must be provided if location_id
is not passed as a parameter.
longitude:
type: string
description: Longitude coordinate of the redemption location. Must be provided if location_id
is not passed as a parameter.
gps_accuracy:
type: integer
description: Accuracy of a user's device GPS
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
location_id: '304155'
latitude: 26.9167509
longitude: 75.8136926
gps_accuracy: 27
/api2/mobile/redemptions/redeemable:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/redemption_details'
examples:
default:
value:
redemption_status: redeemable
created_at: '2016-05-25T06:50:02-05:00'
redeemable_id: 41
location_id: 304361
redemption_image_url: IMAGE_URL_GOES_HERE
redemption_message: Redeem your free Sandwich, with purchase of chips and drink
updated_at: '2016-05-25T06:50:02-05:00'
redeemable_description: ''
redemption_id: 1818919
redemption_tracking_code: '8723640'
expiring_at: '2016-05-25T08:50:02-05:00'
redeemable_name: The Sandwich
campaign_name: Mass Campaign Offer
redeemed_value: '0'
'400':
description: ''
summary: Create Redemption Using Redeemable (Redemptions 1.0)
description: Creates a redemption for a redeemable based on a user's available loyalty points
operationId: mobile_create_redemption_using_redeemable
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
x-stoplight:
id: d491967b73fc7
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
reedemable_id:
type: number
format: double
description: ID of the redeemable used to create a redemption code
location_id:
type: integer
description: Location ID at which a user wants to do the redemption. If a particular
location ID is provided in the request, the redemption will be valid only at that
location and will not be possible at any other.
latitude:
type: string
description: Latitude coordinate of the redemption location. Must be provided if location_id
is not passed as a parameter.
longitude:
type: string
description: Longitude coordinate of the redemption location. Must be provided if location_id
is not passed as a parameter.
gps_accuracy:
type: integer
description: Accuracy of a user's device GPS
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
redeemable_id: 1102
location_id: '304155'
latitude: 26.9167509
longitude: 75.8136926
gps_accuracy: 27
/api2/mobile/redemptions/reward:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/redemption_details'
examples:
default:
value:
redemption_status: redeemable
created_at: '2016-05-25T06:55:04-05:00'
redeemable_id: 75
location_id: 304361
redemption_image_url: IMAGE_URL_GOES_HERE
redemption_message: Redeem your Free Bag of Chips
updated_at: '2016-05-25T06:55:04-05:00'
redeemable_description: ''
redemption_id: 1818920
redemption_tracking_code: '1809897'
expiring_at: '2016-05-25T08:55:04-05:00'
redeemable_name: Bag of Chips
campaign_name: Mass Campaign Offer
redeemed_value: null
'400':
description: ''
summary: Create Redemption Using Reward ID (Redemptions 1.0)
description: Creates a redemption for a reward that has been given to a user (e.g., through a campaign).
operationId: mobile_create_redemption_using_reward_id
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
x-stoplight:
id: 2969c78154a17
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
reward_id:
type: integer
description: 'The ID of the reward for which the redemption code has to be created
'
format: int64
location_id:
type: integer
description: Location ID at which a user wants to do the redemption. If a particular
location ID is provided in the request, the redemption will be valid only at that
location and will not be possible at any other.
latitude:
type: string
description: Latitude coordinate of the redemption location. Must be provided if a location_id
is not passed as a parameter.
longitude:
type: string
description: Longitude coordinate of the redemption location. Must be provided if a
location_id is not passed as a parameter.
gps_accuracy:
type: integer
description: Accuracy of a user's device GPS
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
reward_id: 5167827
location_id: '304155'
latitude: 26.9167509
longitude: 75.8136926
gps_accuracy: 27
/api2/mobile/redemptions/applicable_offers:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
menu_items:
$ref: '#/components/schemas/Menu-items'
discount_amount:
type: integer
description: Discount amount associated with the reward
reward:
type: object
properties:
created_at:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward was created for a user in the system
end_date_tz:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward offer ends
start_date_tz:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward offer starts
updated_at:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward offer was udpated
id:
type: integer
format: int64
description: Unique ID of the reward
image:
type: string
description: URL of the image depicting the reward
status:
type: string
description: Status of the reward (e.g., "unredeemed", "honoured", "expired")
points:
type: integer
description: Points needed for the reward
discount_amount:
type: integer
description: Discount amount associated with the reward
description:
type: string
description: Description of the reward
name:
type: string
description: Name of the reward
redeemable_properties:
type: string
description: Properties of the redeemable
required:
- name
examples:
default:
value:
- menu_items:
- item_name: Adult
item_qty: 1
item_amount: 100
menu_item_type: M
menu_item_id: '1'
menu_family: '1'
menu_major_group: '1'
serial_number: '1.1'
discount_amount: 2
reward:
created_at: '2019-04-02T22:46:32-07:00'
end_date_tz: null
start_date_tz: '2019-04-02T22:46:32-07:00'
updated_at: '2019-04-02T22:46:32-07:00'
id: 2
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 0
description: ''
name: 2% off Subtotal Amount
redeemable_properties: ''
- menu_items:
- item_name: Adult
item_qty: 1
item_amount: 100
menu_item_type: M
menu_item_id: '1'
menu_family: '1'
menu_major_group: '1'
serial_number: '1.1'
discount_amount: 2
reward:
created_at: '2019-04-04T04:00:34-07:00'
end_date_tz: null
start_date_tz: '2019-04-04T04:00:34-07:00'
updated_at: '2019-04-04T04:00:34-07:00'
id: 3
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 2
description: $2 Off Your Order. Participating locations only.
name: $2 Off Your Order
redeemable_properties: ''
- menu_items:
- item_name: Adult
item_qty: 1
item_amount: 100
menu_item_type: M
menu_item_id: '1'
menu_family: '1'
menu_major_group: '1'
serial_number: '1.1'
discount_amount: 2
reward:
created_at: '2019-04-04T04:01:03-07:00'
end_date_tz: null
start_date_tz: '2019-04-04T04:01:03-07:00'
updated_at: '2019-04-04T04:01:03-07:00'
id: 4
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 0
description: ''
name: 2% off Subtotal Amount
redeemable_properties: ''
- menu_items:
- item_name: Adult
item_qty: 1
item_amount: 100
menu_item_type: M
menu_item_id: '1'
menu_family: '1'
menu_major_group: '1'
serial_number: '1.1'
discount_amount: 2
reward:
created_at: '2019-04-15T10:48:40-07:00'
end_date_tz: null
start_date_tz: '2019-04-15T10:48:40-07:00'
updated_at: '2019-04-15T10:48:40-07:00'
id: 14
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 0
description: ''
name: 2% off Subtotal Amount
redeemable_properties: ''
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
location_id:
type: string
examples:
default:
value:
errors:
location_id: Required parameter missing or the value is empty.
summary: List Applicable Offers (Redemptions 1.0)
description: Returns applicable offers based on the check details.
operationId: mobile_list_applicable_offers
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/punchh-app-device-id'
x-stoplight:
id: f09cf9b1e970a
requestBody:
content:
application/json:
schema:
type: object
properties:
menu_items:
$ref: '#/components/schemas/menu-items'
client:
type: string
description: OAuth client ID provided by the business
amount:
type: string
description: Order amount based on items added to the cart
location_id:
type: string
description: Location ID of the store
channel:
type: string
x-stoplight:
id: zazefztzioqd5
description: 'Channel through which the order was placed. If a channel is defined in
the Receipt Qualifier condition under Offers > Qualification Criteria in the Punchh
platform, the API returns the list of offers applicable to the transaction after evaluating
the value set for the channel. Possible values: mobile, chatbot.'
enum:
- ' mobile'
- ' chatbot'
required:
- client
- channel
examples:
default:
value:
client: CLIENT_GOES_HERE
menu_items:
- item_name: Adult
item_qty: 1
item_amount: 100
menu_item_type: M
menu_item_id: '1'
menu_family: '1'
menu_major_group: '1'
serial_number: '1.1'
amount: '100'
location_id: LOCATION_GOES_HERE
channel: mobile
description: ''
x-stoplight:
id: 09d60f8827030
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
schemas:
menu-items:
type: array
title: Menu Items (Array Object)
x-stoplight:
id: 9.481325062e+24
description: This object used in the API request contains one or more menu items added to an order.
It is mandatory to provide an array of menu items. See [How To Send Menu Items to Punchh](/docs/dev-portal-pos/5277d762b8c6d-how-to-send-menu-items-to-punchh)
items:
x-stoplight:
id: nm03po2b4r93z
type: object
properties:
item_name:
type: string
x-stoplight:
id: jmflbednli6v9
description: Name of the menu item
item_qty:
type: integer
x-stoplight:
id: 408cfdtcyc797
description: Quantity ordered by the customer. If the item is a modifier (such as extra cheese
on a pizza base item), make sure the quantity reflects the total number of base items included.
For example, if you have a pizza base item with a certain item ID and a quantity of two,
and the pizzas each have an extra cheese modifier added to them, then the modifier quantity
should be two to account for the modifier across both pizzas. This applies only to base
items of the same ID. If different base items include the same modifier, you do not need
to sum the modifiers.
item_amount:
type: integer
x-stoplight:
id: m45aidhdgirx2
description: The total price of the line item or the amount of the discount that you applied
to an item. In case of multiple quantities, this means the sum total of all item amounts.
Always represent this value as a positive number, even when the item is a discount.
menu_item_type:
type: string
x-stoplight:
id: jcukxr2staydg
description: 'The classification of the item. Choose from the following types based on the
item:
M - Menu item ( + or - )
D - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless
of the sign assigned in the API call
S - Service item. Any item representing money received that is not a sale. For example,
service charges, delivery fees, tips, purchase of gift cards/certificates, etc.
T - Tax item. Taxes of all sorts
P - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the
order)'
menu_item_id:
type: string
x-stoplight:
id: u2a3mb0k3cdkd
description: Unique identifier for the item
menu_family:
type: string
x-stoplight:
id: fkaavtr3h7fh0
description: The family that the item belongs to. The family is the subcategory for the item.
Even though the parameter is required, you can pass it in the request with a blank value.
You can leave this blank if the item does not belong to a family.
menu_major_group:
type: string
x-stoplight:
id: y8u5yhex6g0my
description: The major group that the item belongs to. The major group is the parent category
for the item. Even though the parameter is required, you can pass it in the request with
a blank value. You can leave this blank if the item does not belong to a major group.
serial_number:
type: string
x-stoplight:
id: zjbamqkfait4d
description: A serialized number that differentiates distinct menu items on a receipt. The
purpose of this field is to identify which items on the receipt are base items and which
items are modifiers to the base items. For example, a main menu item (such as pizza) may
have serial number "1.0", and the associated modifiers (such as "extra cheese", "olives",
and "jalapenos") may have serial numbers "1.1", "1.2", and "1.3" respectively. Serialization
is limited to one decimal point, so you can only modify the base item. You cannot modify
a modifier with 1.x.x, and so on
required:
- item_name
- item_qty
- item_amount
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-mobile-redemptions-legacy-openapi.yml