info:
title: Redemptions 1.0 (Legacy) API - Online Ordering
version: '1.0'
description: 'For more information, see [Online Ordering Module 5: Redemptions](/docs/dev-portal-online-ordering/tutorials/modules/5-redemptions/overview).'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
paths:
/api/auth/redemptions/online_order:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Message that explains if the customer's redemption was successfully completed
or not
redemption_amount:
type: integer
description: Total redemption amount that can be applied on the order
category:
type: string
description: 'Category returned for redemption requested where values can be: `redeemable`,
`processed`, `expired`, `invalid`, `unassigned`. Consider redemption valid only
when the category is returned as `redeemable`.'
qualified_menu_items:
$ref: '#/components/schemas/Menu-items'
discount_distribution_items:
$ref: '#/components/schemas/discount_distribution_items'
redemption_id:
type: integer
format: int64
description: Unique ID associated with the redemption. Save this in your system for
future reference.
redemption_code:
type: string
description: Redemption code associated with redemption
max_applicable_quantity:
type: number
description: 'Maximum quantity that can be discounted. Note: This parameter will be
returned for offers related to Price Rollback.'
campaign_name:
type: string
x-stoplight:
id: 7s3sui5p01net
description: Name of the campaign through which the guest received the offer
qualifying_conditions:
type: object
x-stoplight:
id: ox2f9fs82bs54
description: The object lists all qualification criteria (both receipt-level and line-item)
for submitted offers that failed while processing the redemption. This object is
returned in the response only if the option to return the qualifying conditions
for Redemption 1.0 APIs is enabled for the business in the Punchh platform. See
the `data` object under [Get Qualification Criteria Response](https://developers.partech.com/docs/dev-portal-platform-functions/97ec083d6cf57-get-qualification-criteria-qc-list#response-body)
in Platform Functions for descriptions of the parameters in `qualifying_conditions`.
examples:
default:
value:
status: Redeemed at Feb 26, 2026 10:49 by FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE
at Naperville. Please HONOR it.
redemption_amount: 8
category: redeemable
qualified_menu_items:
- item_name: Sandwich
item_qty: 1
item_amount: 5
menu_item_type: M
menu_item_id: '102000'
menu_family: Sandwich
menu_major_group: Sandwich
serial_number: '1.0'
- item_name: Coke
item_qty: 1
item_amount: 7
menu_item_type: M
menu_item_id: '102000'
menu_family: Coke
menu_major_group: Coke
serial_number: '2.0'
discount_distribution_items:
- item_name: Sandwich DISCOUNT
item_qty: 1
item_amount: -3
menu_item_type: R
menu_item_id: '102000'
menu_family: Sandwich
menu_major_group: Sandwich
serial_number: 1
- item_name: Coke DISCOUNT
item_qty: 1
item_amount: -5
menu_item_type: R
menu_item_id: '102000'
menu_family: Coke
menu_major_group: Coke
serial_number: 2
max_applicable_quantity: 1
campaign_name: Mass Campaign Offer
redemption_id: 21762
redemption_code: REDEMPTION_CODE_GOES_HERE
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
'422':
description: ''
content:
application/json:
examples:
default:
value:
- Given reward is not accessible for this guest
description: "Redeems a card, reward, redeemable, or discount specified in the `discount_type` parameter\
\ against a receipt.\n\nPunchh evaluates eligibility during the Possible Redemptions call using\
\ the receipt details provided (item name, price, quantity, identifiers, etc.). During the Create\
\ Online Redemption API call, Punchh revalidates the same receipt to ensure the qualifying conditions\
\ are still met before honoring the redemption. \n\nIf any item attributes change between the\
\ two calls, Punchh may be unable to match the qualifying items, which can cause the Create Online\
\ Redemption API call to fail or return a different result—even if the Possible Redemptions call\
\ was successful.\n\n**NOTE**: **When processing a redemption, DO NOT include the `query` parameter\
\ in the API request.** Use this parameter only to check for possible redemptions. "
summary: Create Online Redemption (Redemptions 1.0)
operationId: sso_create_online_redemption
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 60069336e34d4
requestBody:
content:
application/json:
schema:
type: object
properties:
authentication_token:
type: string
description: The authentication token of the user. You can retrieve this from the response
of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
query:
type: boolean
description: Include this parameter only if you want to make a possible redemptions
call. The parameter value must be true. If you want to process a redemption, do not
include this parameter in the request.
cc_last4:
type: string
description: Last 4 digits of credit card number
employee_id:
type: string
description: Employee ID
employee_name:
type: string
description: Employee name
store_number:
type: string
description: The location where the redemption must be redeemed
menu_items:
$ref: '#/components/schemas/menu_items'
receipt_amount:
type: number
format: double
description: Order amount before taxes, calculated as the sum of all item amounts minus
any discounts. This is the amount used to calculate loyalty points/visits. The value
of this parameter should match `subtotal_amount`. For example, if the order amount
is $10, both `receipt_amount` and `subtotal_amount` will be 10. If a $2 discount is
applied, both will be 8.
subtotal_amount:
type: number
format: double
description: Order amount before taxes (sum of all item amounts minus any discounts).
Same as `receipt_amount`. For historical reasons, include this parameter along with
`receipt_amount` in the API request.
receipt_datetime:
type: string
description: Timestamp of receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format
transaction_no:
type: string
description: Receipt number or transaction number on the receipt
external_uid:
type: string
description: 'Unique ID generated by your system. We use this to prevent duplicates
in case the same transaction gets triggered twice.
'
client:
type: string
description: Client key of the business
channel:
type: string
enum:
- pos
- web
- online_order
- mobile
- dashboard
- chatbot
- kiosk
description: 'Channel through which the redemption was requested. Possible values are:
online_order, pos, web, mobile, dashboard, chatbot, and kiosk.
'
state:
type: string
description: 'The current state of the check-in. Possible values are: committed, pending,
or void'
discount_type:
type: string
enum:
- reward
- card_completion
- redeemable
- discount_amount
- redemption_code
- subscription
description: 'Any one of these values: card_completion || reward || redeemable || discount_amount
|| redemption_code || subscription. For details, see [Getting Started With Online
Ordering APIs](/docs/dev-portal-online-ordering/0130fe9413a97-getting-started-with-online-ordering-ap-is).'
reward_id:
type: integer
description: Send this value when discount_type is reward. This is the ID of the reward
the user wants to redeem.
format: int64
redeemable_id:
type: string
description: Send this value when discount_type is redeemable. This is the ID of the
redeemable the user wants to redeem.
redeemed_points:
type: string
description: Send this value when discount_type is discount_amount. This is the amount
of the banked rewards the user wants to redeem.
redemption_code:
type: string
description: Send this value when discount_type is redemption_code. This is the redemption
code or Punchh coupon code that is associated with redemption.
subscription_id:
type: string
description: Send this value when discount_type is subscription. This is a system-generated
unique ID of the subscription that is issued to the guest.
email:
type: string
description: Email address of the user (required to be sent only in case of coupons
and promos)
required:
- store_number
- receipt_amount
- subtotal_amount
- receipt_datetime
- transaction_no
- client
- discount_type
/api/auth/redemptions:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
internal_tracking_code:
type: integer
description: Internal tracking code generated on the redemption
expiry_hours:
type: integer
description: Total number of hours after which the redemption code will expire
examples:
default:
value:
internal_tracking_code: '2142353'
expiry_hours: '24'
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
'422':
description: Sending invalid Entity
summary: Fetch Redemption Code (Redemptions 1.0)
description: 'This endpoint generates an internal tracking code, which can be used to [look up a
user on the POS system](/docs/dev-portal-pos/b3A6NTAyODM5MTc-user-lookup-and-fetch-balance) and
[redeem the selected reward or banked currency at the POS](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0).
To generate an internal tracking code via this endpoint, you must supply either a reward ID in
the **reward_id** parameter or a value for the banked currency to redeem in the **redeemed_points**
parameter. While the internal tracking code is active, the selected reward or banked currency
value is eligible for redemption at the POS using the value of the internal tracking code as the
**redemption_code** in the [POS Redemption API endpoint](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0).
>User authentication required
>
>This API requires authentication_token to be supplied as `HTTP_AUTHORIZATION` header or in the
`authentication_token` parameter.'
operationId: sso_fetch_redemption_code
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Authorization'
x-stoplight:
id: 85f9cf163d423
requestBody:
content:
application/json:
schema:
type: object
properties:
authentication_token:
type: string
default: AUTHENTICATION_TOKEN_GOES_HERE
description: The authentication token of the user. You can retrieve this from the response
of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
client:
type: string
description: Client key of the business
location_id:
type: integer
format: int32
description: Location ID of the redemption
locale:
type: string
description: Locale used for language
longitude:
type: string
description: Longitude of the redemption location
latitude:
type: string
description: Latitude of the redemption location
redeemed_points:
type: number
format: double
description: Value of banked currency to redeem. Use this field only if you have a Points
Convert to Currency program type and you are trying to redeem banked currency. Otherwise,
use the **reward_id** field only.
reward_id:
type: integer
format: int64
description: Reward ID (required if redeemed_points is not provided)
gps_accuracy:
type: integer
description: 'GPS accuracy
'
store_number:
type: string
description: 'Store number of the location. This can be used as an alternative to specify
the location if location_id/latitute/longitude are not provided.
'
required:
- client
- redeemed_points
- reward_id
examples:
default:
value:
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
client: CLIENT_GOES_HERE
location_id: 304155
locale: ''
longitude: '75.8136926'
latitude: '26.9167509'
redeemed_points: null
reward_id: 12345
gps_accuracy: 27
store_number: '12'
description: ''
delete:
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties: {}
summary: Void Processed Redemption (Redemptions 1.0)
description: 'Voids a processed redemption. After a redemption is voided successfully, the offer
tied to the redemption is returned to the guest''s account.
<b>Note</b>: The Void Redemption API allows you to cancel a redemption without any time restrictions
for most types of redemptions. However, for coupons and promos, redemptions can only be voided
within 24 hours of the redemption process.'
operationId: sso_void_processed_redemption
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Authorization'
x-stoplight:
id: b7e6468ce7ed7
requestBody:
content:
application/json:
schema:
type: object
properties:
redemption_id:
type: integer
format: int64
description: ID of the redemption that you want to delete
authentication_token:
type: string
description: The authentication token of the user. You can retrieve this from the response
of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
client:
type: string
description: Client key of the business
reason:
type: string
description: Why the redemption is being deleted
redemption_code:
type: string
description: To be entered if the redemption ID is not provided. If both redemption_id
and redemption_code are provided, then only redemption_id will be processed.
required:
- redemption_id
- client
examples:
default:
value:
redemption_id: 323242
authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
client: CLIENT_GOES_HERE
/api/auth/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 applied to the order for an applicable offer or 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, in YYYY-MM-DD format
end_date_tz:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward will expire, in YYYY-MM-DD format
start_date_tz:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward becomes available, in YYYY-MM-DD format
updated_at:
type: string
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
description: Date/time when the reward was updated, in YYYY-MM-DD format
id:
type: integer
format: int64
description: ID of the reward
image:
type: string
description: Image of the reward
status:
type: string
description: 'Status of the reward (e.g., "unreedemmed", "expired") '
points:
type: integer
description: Points needed to redeem the reward
discount_amount:
type: integer
description: Discount amount of the reward
description:
type: string
description: Description of the reward
name:
type: string
description: Name of the reward
redeemable_properties:
type: string
description: Reedemable properties of the reward. Properties such as "Merchandise",
"Food Item", etc. added to a particular redeemable.
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: '3.0'
discount_amount: 2
reward:
created_at: '2023-04-03T05:42:02Z'
end_date_tz: null
start_date_tz: '2023-04-03T05:42:02Z'
updated_at: '2023-04-03T05:42:02Z'
id: 1
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 2
description: $2 Off Your Order. Participating locations only.
name: Redeemable - $2 Off Your Order
redeemable_properties: null
- 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: '3.0'
discount_amount: 2
reward:
created_at: '2023-04-03T05:46:32Z'
end_date_tz: null
start_date_tz: '2023-04-03T05:46:32Z'
updated_at: '2023-04-03T05:46:32Z'
id: 2
image: IMAGE_URL_GOES_HERE
status: unredeemed
points: 0
discount_amount: 2
description: ''
name: 2% off Subtotal Amount
redeemable_properties: null
'401':
description: Sending invalid credentials
'412':
description: Sending invalid Signature
'422':
description: The given reward can't be applied to the given receipt details
summary: Applicable Offers (Redemptions 1.0)
description: Returns all applicable rewards available to the user per the items added to the check
operationId: sso_applicable_offers
parameters:
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/content type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
- $ref: '#/components/parameters/Authorization'
x-stoplight:
id: ae5f635ab632f
requestBody:
content:
application/json:
schema:
type: object
properties:
authentication_token:
type: string
description: The authentication token of the user. You can retrieve this from the response
of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
client:
type: string
description: Client key of the business
receipt_amount:
type: number
format: double
description: Order amount before taxes, calculated as the sum of all item amounts minus
any discounts. This is the amount used to calculate loyalty points/visits. The value
of this parameter should match `subtotal_amount`. For example, if the order amount
is $10, both `receipt_amount` and `subtotal_amount` will be 10. If a $2 discount is
applied, both will be 8.
subtotal_amount:
type: number
format: double
description: Order amount before taxes (sum of all item amounts minus any discounts).
Same as `receipt_amount`. For historical reasons, include this parameter along with
`receipt_amount` in the API request.
receipt_datetime:
type: string
format: date-time
description: Timestamp of the receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format
store_number:
type: string
description: Location where the redemption must be redeemed
menu_items:
$ref: '#/components/schemas/menu_items'
channel:
type: string
x-stoplight:
id: tfd4xyagg7i9x
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: online_order, web.'
enum:
- online_order
- web
required:
- client
- receipt_amount
- subtotal_amount
- receipt_datetime
- channel
x-stoplight:
id: a417170d64e9b
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
schemas:
background-content:
type: object
properties:
type:
type: string
description: 'The type of the background content. It can be an image or a color.
'
url:
type: string
description: 'The URL of the image that will be used as the background
'
alt_text:
type: string
description: 'Alternate text that appears if the app cannot render the background content of
the message
'
initial_frame:
type: string
description: The initial frame or first frame is what appears behind the play button before
a user taps it to start playing the video.
description: "This is the content that makes the background of the message.\n\n```\n{\n \"type\"\
: \"image\",\n \"url\": \"IMAGE_URL\",\n \"alt_text\": \"Black Background Image\",\n \
\ \"initial_frame\": \"\"\n}\n```"
title: Background Content (Object)
x-stoplight:
id: 2aaafe87b4797
cta:
type: array
items:
type: object
properties:
type:
type: string
description: 'Three possible values can be returned to the mobile client:
- web_link: The cta button prompts the user to open the link in a web browser available
on the mobile client.
- deep_link: The cta button takes the user to a particular deep link specified in the app.
- drill_down: The cta button opens the detailed view of the rich message received by the
app.'
link:
type: string
description: The URL to which the user will be directed, depending on the type of the cta
label:
type: string
description: The text that appears on the cta button in the app
cta_type:
type: string
description: 'More than one cta object can be returned to the app. The cta_type can have two
possible values: primary and secondary. The primary cta is higher priority and is the main
cta button. The secondary cta can be something like a terms and conditions link that can
be rendered appropriately in the app.'
title: CTA (Object)
x-stoplight:
id: d23e01d757cab
discount_distribution_items:
type: array
title: Discount Distribution Items (Array Object)
description: 'An array containing details of how the applied discount is distributed across individual
menu items. Each object represents one line item that receives a portion of the discount.
'
items:
type: object
properties:
item_name:
type: string
description: Name of the discounted menu item as it displays in the POS catalog
menu_item_id:
type: string
description: Unique identifier that your POS system uses for the discounted menu item
item_qty:
type: number
description: Quantity associated with the discounted item.
item_amount:
type: number
description: A negative amount that indicates a reduction in price. The sum of all `item_amount`
values across the array equals the total discount applied.
menu_item_type:
type: string
description: 'The classification
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-online-ordering-redemptions-legacy-openapi.yml