x-stoplight:
id: 4hx3pypgeb59y
info:
title: Offers Ingestion API - Platform Functions
version: '1.0'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
description: 'Create and update in bulk and list Line Item Selectors (LIS), Qualification Criteria (QC),
and Reedemables through Offers Ingestion API calls.
For more information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)'
paths:
/api2/dashboard/offers/lis:
get:
summary: Get Line Item Selector (LIS) List
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/lis_data_output'
examples:
Example:
value:
data:
- external_id: EXTERNAL_ID_GOES_HERE
name: LIS
filter_type: base_and_modifiers
exclude_non_payable: true
base_items:
clauses:
- attribute: item_name
operator: like
value: White Rice
modifiers:
clauses:
- attribute: item_name
operator: like
value: curry Rice
processing_method: max_price
max_discount_units: 2
- external_id: EXTERNAL_ID_GOES_HERE
name: LIS 2
filter_type: base_only
exclude_non_payable: true
base_items:
clauses:
- attribute: item_name
operator: like
value: White Rice
meta:
page: 1
per_page: 2
total_records: 10
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
operationId: get-api2-dashboard-offers-lis
description: "Pulls a list of line item selectors available and defined at the business level. \n\
\nTo call this API, the offers ingestion option must be enabled for the business on the Punchh\
\ platform. Contact your Punchh representative to update this Punchh platform configuration.\n\
\n\nLine item selector\
\ search is on a business level, and the request can:\n* Set search limits and order by descending\
\ search\n* Filter based on name and other attributes, for example, name or recency \n\nFor more\
\ information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)"
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
x-stoplight:
id: w6062fx4u3k3y
description: Define the search string on the lis name column
page:
type: integer
x-stoplight:
id: 695gq12y76fz1
description: Number of pages to retrieve. If the requested number exceeds the available
pages, the system will retrieve up to the last valid page. If the `page` value is
not provided, the default value is used.
default: 1
per_page:
type: integer
x-stoplight:
id: 3cb4kthxtmsc0
description: Number of records per page. If the `per_page` value is not provided, the
default value is used. The maximum `per_page` value is enforced based on the OFFERS_LIST_MAX_PER_PAGE
environment variable.
default: 20
examples:
Example:
value:
query: free
page: 1
per_page: 20
x-stoplight:
id: f471f9f9b598d
post:
summary: Create Line Item Selector (LIS)
operationId: post-api2-dashboard-offers-lis
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/lis_results'
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings: {}
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
warnings: {}
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings:
base_items:
clauses:
- message: 'Required parameters missing or invalid: attribute'
item:
attribute: item
operator: like
value: White Rice
modifiers:
clauses:
- message: 'Required parameter is duplicate: attribute'
item:
attribute: item_name
operator: like
value: '123456'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
description: "Allows a business to define one or more line item selectors (LIS). You can bulk create\
\ a maximum of 20 line item selectors per API call. If the request input contains more than 20\
\ LIS, only the first 20 are created, and the remaining are ignored. \n\nFor more information,\
\ see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)\n\
\nTo call this API, the offers ingestion option must be enabled for the business on the Punchh\
\ platform. Contact your Punchh representative to update this Punchh platform configuration.\n\
\nFor more information on LIS settings, see the [Line Item Selectors](https://support.punchh.com/s/article/Line-Item-Selectors)\
\ article on the Support Portal. \n\nNote: To view the Punchh product documentation on the Punchh\
\ Support Portal, you must log in to a Punchh platform production environment. If you already\
\ have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
x-stoplight:
id: ed2d43a0eb4b2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/lis_data_input'
examples:
Example:
value:
data:
- name: Test LIS
external_id: EXTERNAL_ID_GOES_HERE
filter_item_set: base_and_modifiers
exclude_non_payable: true
base_items:
clauses:
- attribute: item_name
operator: like
value: White Rice
- attribute: item_id
operator: like
value: '123456'
- attribute: quantity
operator: like
value: '1'
- attribute: item_family
operator: like
value: '123'
- attribute: item_major_group
operator: like
value: '123'
- attribute: item_serial_number
operator: like
value: '1'
- attribute: line_item_type
operator: like
value: M
- attribute: item_total_amount
operator: like
value: '12.96'
modifiers:
max_discount_units: 2
processing_method: max_price
clauses:
- attribute: item_name
operator: like
value: White Rice
- attribute: item_id
operator: like
value: '123456'
- attribute: quantity
operator: like
value: '1'
- attribute: item_family
operator: like
value: '123'
- attribute: item_major_group
operator: like
value: '123'
- attribute: item_serial_number
operator: like
value: '1'
- attribute: line_item_type
operator: like
value: M
- attribute: item_total_amount
operator: like
value: '12.96'
description: ''
patch:
summary: Update Line Item Selector (LIS)
operationId: patch-api2-dashboard-offers-lis
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
x-stoplight:
id: zow9b0t2ujqwn
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: 2wroli21yi8t5
type: object
properties:
external_id:
type: string
x-stoplight:
id: cd0mxgcg0ubg1
description: Unique ID (UUID) sent by the external system to track if a particular
entity is successfully created in the Punchh system
success:
type: boolean
x-stoplight:
id: yq3bria838gmc
description: 'Status of a specific entity created in the system. Possible values:
true, false'
errors:
type: array
x-stoplight:
id: gsy4pbhsnrfis
description: A list of error messages explaining why a specific entity was not
created in the system
items:
x-stoplight:
id: wud6bsbkmnl8w
type: string
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
description: "Allows a business to update one or more Line Item Selectors. You can bulk update a\
\ maximum of 20 line item selectors per API call. If the request input contains more than 20 LIS,\
\ only the first 20 are created, and the remaining are ignored.\n\nFor more information, see [Offers\
\ Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)\n\
\n#### Update Rules for Filter Item Set in LIS\n\n1\\. All clauses of the defined filter item\
\ set are updated in the update request. If the filter item set is \"Only Base\", you must provide\
\ the entire set of clauses for the \"Base\" to update the LIS.\n\n2\\. If the filter item set\
\ is \"Base and Modifiers\", you can send either the base clause or the modifier clause in the\
\ update request. The LIS is updated based on the received clause.\nFor example: In the \"Base\
\ and Modifiers\" filter item set, if the user sends a request with a modifier clause, the existing\
\ modifier will be updated while the base remains in its original configuration.\n\n3\\. The same\
\ validation rules applied during LIS creation are followed. If the LIS is created with \"Only\
\ Modifiers\", you must provide both base and modifier clauses as per the system design. However,\
\ while updating, the user can send only the modifier clause or only the base clause to update\
\ the LIS definition.\n\nAn index has been added to the business_id and external_id columns because\
\ the LIS is fetched by business_id and external_id.\n\nTo call this API, the offers ingestion\
\ option must be enabled for the business on the Punchh platform. Contact your Punchh representative\
\ to update this Punchh platform configuration.\n\n\nFor more information on line item selector (LIS) settings, see\
\ the [Line Item Selectors](https://support.punchh.com/s/article/Line-Item-Selectors) article\
\ on the Support Portal. \n\nNote: To view the Punchh product documentation on the Punchh Support\
\ Portal, you must log in to a Punchh platform production environment. If you already have access\
\ to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
x-stoplight:
id: 9c5bd52c8a10f
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/lis_data_input'
examples:
Example:
value:
data:
- name: Test LIS
external_id: EXTERNAL_ID_GOES_HERE
filter_item_set: base_and_modifiers
exclude_non_payable: true
base_items:
clauses:
- attribute: item_name
operator: like
value: White Rice
- attribute: item_id
operator: like
value: '123456'
- attribute: quantity
operator: like
value: '1'
- attribute: item_family
operator: like
value: '123'
- attribute: item_major_group
operator: like
value: '123'
- attribute: item_serial_number
operator: like
value: '1'
- attribute: line_item_type
operator: like
value: M
- attribute: item_total_amount
operator: like
value: '12.96'
modifiers:
max_discount_units: 2
processing_method: max_price
clauses:
- attribute: item_name
operator: like
value: White Rice
- attribute: item_id
operator: like
value: '123456'
- attribute: quantity
operator: like
value: '1'
- attribute: item_family
operator: like
value: '123'
- attribute: item_major_group
operator: like
value: '123'
- attribute: item_serial_number
operator: like
value: '1'
- attribute: line_item_type
operator: like
value: M
- attribute: item_total_amount
operator: like
value: '12.96'
/api2/dashboard/offers/qc:
get:
summary: Get Qualification Criteria (QC) List
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/qc_data_output'
examples:
Example:
value:
data:
- name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: '3'
percentage_of_processed_amount: '10'
qc_processing_function: sum_amounts
rounding_rule: ceil
max_discount_units: 2
target_price: 1
effective_location: location:1234
stack_discounting: false
reuse_qualifying_items: false
line_item_filters:
- line_item_selector:
name: Test LIS
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_and_modifiers
base_items:
clauses:
- attribute: line_item_type
operator: ==
value: M
- attribute: item_id
operator: in
value: '101'
modifiers:
clauses:
- attribute: item_name
operator: like
value: modified
processing_method: max_price
max_discount_units: 12
processing_method: max_price
quantity: 5
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector:
name: Test LIS
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_and_modifiers
base_items:
clauses:
- attribute: line_item_type
operator: ==
value: M
- attribute: item_id
operator: in
value: '101'
modifiers:
clauses:
- attribute: item_name
operator: like
value: modified
processing_method: max_price
max_discount_units: 12
net_value: null
receipt_qualifier:
- attribute: total_amount
operator: '>='
value: '10'
meta:
page: 1
per_page: 1
total_records: 10
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
operationId: get-api2-dashboard-offers-qc
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
description: "Pulls a list of all qualification criteria (QC) available and defined at the business\
\ level. \n\nTo call this API, the offers ingestion option must be enabled for the business on\
\ the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.\n\
\n\nQualification criteria\
\ search is on a business level, and the request can:\n* Set search limits and order by descending\
\ search\n* Filter based on name and other attributes, for example, name or recency\n\nFor more\
\ information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)"
x-stoplight:
id: 97ec083d6cf57
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
x-stoplight:
id: wlrsupv9spzax
description: Define the search string on the qc name column
page:
type: integer
x-stoplight:
id: ods5kg0qeo99k
description: Number of pages to retrieve. If the requested number exceeds the available
pages, the system will retrieve up to the last valid page. If the `page` value is
not provided, the default value is used.
default: 1
per_page:
type: integer
x-stoplight:
id: 1yyd4a7lja773
default: 20
description: Number of records per page. If the `per_page` value is not provided, the
default value is used. The maximum `per_page` value is enforced based on the OFFERS_LIST_MAX_PER_PAGE
environment variable.
examples:
Example:
value:
query: free
page: 1
per_page: 20
post:
summary: Create Qualification Criteria (QC)
operationId: post-api2-dashboard-offers-qc
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
x-stoplight:
id: chw2a0ypyb9oc
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: krv7k3bplrg8o
type: object
properties:
external_id:
type: string
x-stoplight:
id: 6hj948u985fjg
description: Unique ID (UUID) sent by the external system to track if a particular
entity is successfully created in the Punchh system
success:
type: boolean
x-stoplight:
id: mbwubmhn5zxes
description: 'Status of a specific entity created in the system. Possible values:
true, false'
errors:
type: array
x-stoplight:
id: tcz6brrkd8i8l
description: A list of error messages explaining why a specific entity is not
created in the system
items:
x-stoplight:
id: 2g5otalh9m31j
type: string
warnings:
type: object
x-stoplight:
id: yncdeywztferl
description: A list of warning messages indicating potential issues found during
the creation of the qualification criteria (QC). These warnings do not prevent
the qualification criteria (QC) from being created but may require attention.
These warnings were ignored as they did not trigger any validation errors.
properties:
line_item_filters:
$ref: '#/components/schemas/warnings_line_item_filters'
item_qualifiers:
$ref: '#/components/schemas/warnings_item_qualifiers'
receipt_qualifiers:
$ref: '#/components/schemas/warnings_receipt_qualifiers'
qualifying_expressions_operator:
$ref: '#/components/schemas/warnings_qualifying_expressions_operator'
item_filter_expressions_operator:
$ref: '#/components/schemas/warnings_item_filter_expressions_operator'
discount_evaluation_strategy:
$ref: '#/components/schemas/warnings_discount_evaluation_strategy'
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings:
line_item_filters:
- message: 'Required parameters missing or invalid: line_item_selector_id, processing_method'
item:
line_item_selector_id: ''
processing_method: max
quantity: 5
- message: 'Required parameters missing or invalid: line_item_selector_id'
item:
line_item_selector_id: invalid
processing_method: max_price
quantity: 5
item_qualifiers:
- message: 'Required parameters missing or invalid: line_item_selector_id, expression_type'
item:
expression_type: ''
line_item_selector_id: invalid
net_value: 1
receipt_qualifiers:
- message: 'Required parameters missing or invalid: attribute'
item:
attribute: total
operator: '>='
value: '10'
- message: 'Required parameter is duplicate: attribute'
item:
attribute: total_amount
operator: in
value: '1'
qualifying_expressions_operator:
- message: 'Required parameters missing or invalid: qualifying_expressions_operator'
item:
qualifying_expressions_operator: an
item_filter_expressions_operator:
- message: 'Required parameters missing or invalid: item_filter_expressions_operator'
item:
item_filter_expressions_operator: an
discount_evaluation_strategy:
- message: 'Required parameters missing or invalid: discount_evaluation_strategy'
item:
discount_evaluation_strategy: ma
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
warnings: {}
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
description: "Allows a business to define one or more qualification criteria (QC). You can bulk\
\ create a maximum of 20 qualification criteria per API call. If the request input contains more\
\ than 20 QC, only the first 20 are created, and the remaining are ignored.\n\nQC define the rules\
\ and conditions under which offers can be redeemed. It involves various processing functions\
\ that determine how offers are applied based on specific criteria, such as customer behavior,\
\ purchase details, or transaction data. QC play a crucial role in managing complex offer logic,\
\ ensuring that only eligible transactions or actions qualify for discounts or rewards.\n\n\n\
For more information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)\n\
\nTo call this API, the offers ingestion option must be enabled for the business on the Punchh\
\ platform. Contact your Punchh representative to update this Punchh platform configuration.\n\
\n\nFor more information\
\ on QC settings, see the [Qualification Criteria](https://support.punchh.com/s/article/Qualification-Criteria)\
\ article on the Support Portal. \n\nNote: To view the Punchh product documentation on the Punchh\
\ Support Portal, you must log in to a Punchh platform production environment. If you already\
\ have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal.\n"
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/qc_data_input'
examples:
Effective location as an array of strings:
value:
data:
- name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location:
- location:1234
- tag:456
stack_discounting: false
reuse_qualifying_items: false
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
- attribute: receipt_week_day
operator: in
value: '1'
- attribute: receipt_day
operator: in
value: '10'
- attribute: subtotal_amount
operator: '>='
value: '10'
- attribute: receipt_month
operator: ==
value: '10'
- attribute: receipt_year
operator: ==
value: '2024'
- attribute: revenue_code
operator: in
value: Online
- attribute: revenue_id
operator: in
value: '10'
- attribute: employee_id
operator: in
value: '10'
- attribute: employee_name
operator: in
value: john
- attribute: receipt_week
operator: ==
value: '10'
- attribute: receipt_minute
operator: in
value: '10'
- attribute: channel
operator: in
value: POS
- attribute: transaction_no
operator: mod
value: '1001'
Example:
value:
data:
- name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location: location:1234
stack_discounting: false
reuse_qualifying_items: false
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
- attribute: receipt_week_day
operator: in
value: '1'
- attribute: receipt_day
operator: in
value: '10'
- attribute: subtotal_amount
operator: '>='
value: '10'
- attribute: receipt_month
operator: ==
value: '10'
- attribute: receipt_year
operator: ==
value: '2024'
- attribute: revenue_code
operator: in
value: Online
- attribute: revenue_id
operator: in
value: '10'
- attribute: employee_id
operator: in
value: '10'
- attribute: employee_name
operator: in
value: john
- attribute: receipt_week
operator: ==
value: '10'
- attribute: receipt_minute
operator: in
value: '10'
- attribute: channel
operator: in
value: POS
- attribute: transaction_no
operator: mod
value: '1001'
x-stoplight:
id: 009524a9d88ae
patch:
summary: Update Qualification Criteria (QC)
operationId: patch-api2-dashboard-offers-qc
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
x-stoplight:
id: qdraz7w495xmu
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: qcg1975w5ouc7
type: object
properties:
external_id:
type: string
x-stoplight:
id: jsrkoj3vg7ywp
description: Unique ID (UUID) sent by the external system to track if a particular
entity is successfully created in the Punchh system
success:
type: boolean
x-stoplight:
id: 2h5bxjsdi09ys
description: 'Status of a specific entity created in the system. Possible values:
true, false'
errors:
type: array
x-stoplight:
id: 2y788f3hgfwpl
description: A list of error messages explaining why a specific entity was not
created in the system
items:
x-stoplight:
id: hretsetvjpu9l
type: string
warnings:
type: object
x-stoplight:
id: s998z2nlkl5vq
properties:
line_item_filters:
$ref: '#/components/schemas/warnings_line_item_filters'
item_qualifiers:
$ref: '#/components/schemas/warnings_item_qualifiers'
receipt_qualifiers:
$ref: '#/components/schemas/warnings_receipt_qualifiers'
qualifying_expressions_operator:
$ref: '#/components/schemas/warnings_qualifying_expressions_operator'
item_filter_expressions_operator:
$ref: '#/components/schemas/warnings_item_filter_expressions_operator'
discount_evaluation_strategy:
$ref: '#/components/schemas/warnings_discount_evaluation_strategy'
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
description: "Allows a business to update one or more qualification criteria. The same validations\
\ as those in the [Create Qualification Criteria](/docs/dev-portal-platform-functions/009524a9d88ae-create-qualification-criteria-qc)\
\ API will apply. You can bulk update a maximum of 20 qualification criteria per API call. If\
\ the request input contains more than 20 QC, only the first 20 are created, and the remaining\
\ are ignored.\n\nFor more information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)\n\
\n### PATCH Requests: Partial Updates and Nested Object Replacements\nPATCH requests allow you\
\ to update specific parameters of a QC object without affecting others. You only need to include\
\ the parameters you want to modify. For example, you can update only the `percentage_of_processed_amount`\
\ parameter in a QC object.\n\nWhen updating a nested object (e.g., `line_item_filters`, `item_qualifiers`,\
\ `receipt_qualifiers`, `aggregator_grouping_attributes`), the entire nested object is replaced\
\ with the valid values provided in the request. Invalid values are ignored.\n\nAdditional rules\
\ when updating nested objects:\n* If all provided values are invalid, the existing values remain\
\ unchanged.\n* If an empty nested object is provided, the existing values are deleted.\n* If\
\ the nested object or any of its parameters is omitted, existing values remain unaffected.\n\n\
To call this API, the offers ingestion option must be enabled for the business on the Punchh platform.\
\ Contact your Punchh representative to update this Punchh platform configuration.\n\n\nFor more information on QC\
\ settings, see the [Qualification Criteria](https://support.punchh.com/s/article/Qualification-Criteria)\
\ article on the Support Portal. \n\nNote: To view the Punchh product documentation on the Punchh\
\ Support Portal, you must log in to a Punchh platform production environment. If you already\
\ have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/qc_data_input'
examples:
Effective location as an array of strings:
value:
data:
- name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location:
- location:2434
- tag:736
stack_discounting: false
reuse_qualifying_items: false
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
- attribute: receipt_week_day
operator: in
value: '1'
- attribute: receipt_day
operator: in
value: '10'
- attribute: subtotal_amount
operator: '>='
value: '10'
- attribute: receipt_month
operator: ==
value: '10'
- attribute: receipt_year
operator: ==
value: '2024'
- attribute: revenue_code
operator: in
value: Online
- attribute: revenue_id
operator: in
value: '10'
- attribute: employee_id
operator: in
value: '10'
- attribute: employee_name
operator: in
value: john
- attribute: receipt_week
operator: ==
value: '10'
- attribute: receipt_minute
operator: in
value: '10'
- attribute: channel
operator: in
value: POS
- attribute: transaction_no
operator: mod
value: '1001'
Example:
value:
data:
- name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location: location:1234
stack_discounting: false
reuse_qualifying_items: false
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
- attribute: receipt_week_day
operator: in
value: '1'
- attribute: receipt_day
operator: in
value: '10'
- attribute: subtotal_amount
operator: '>='
value: '10'
- attribute: receipt_month
operator: ==
value: '10'
- attribute: receipt_year
operator: ==
value: '2024'
- attribute: revenue_code
operator: in
value: Online
- attribute: revenue_id
operator: in
value: '10'
- attribute: employee_id
operator: in
value: '10'
- attribute: employee_name
operator: in
value: john
- attribute: receipt_week
operator: ==
value: '10'
- attribute: receipt_minute
operator: in
value: '10'
- attribute: channel
operator: in
value: POS
- attribute: transaction_no
operator: mod
value: '1001'
/api2/dashboard/offers/redeemable:
get:
summary: Get Redeemable List
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/redeemable_data_output'
examples:
Example:
value:
meta:
page: 1
per_page: 20
total_records: 171
data:
- name: Redeemable offer 51
image: IMAGE_URL_GOES_HERE
allow_for_support_gifting: true
available_as_template: false
auto_applicable: true
start_time: null
expiry_days: null
segment_definition_id: null
end_time: '2024-08-29T23:59:59Z'
timezone: Australia/Darwin
remind_before: 3
discount_channel: all
points: 12
activate_now: true
applicable_as_loyalty_redemption: false
expire_redemption_code_with_reward_end_date: false
template:
redemption_message: 'true'
short_prompt: 'true'
standard_prompt: 'true'
effective_location: null
lag_duration:
value: 2
units: days
recurrence_schedule:
occurrences: 10
days_distance: 2
meta_data: meta data here
distributable: true
alternate_locale_name:
- language: es
translation: redeemable name in ES language
- language: fr
translation: null
- language: ro
translation: null
alternate_locale_description:
- language: es
translation: description in ES language
- language: fr
translation: null
- language: ro
translation: desc ro
external_id: EXTERNAL_ID_GOES_HERE
indefinetely: false
redemption_code_expiry_mins: 4
distributable_to_all_users: true
receipt_rule:
qualifier_type: new
discount_amount: null
redeeming_criterion_id: 2999f340-26ec-4391-8256-dba634f5ec37
redeeming_criterion:
name: Redeemable offer 50-Qualifier
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
rounding_rule: floor
max_discount_units: 2
target_price: 1
effective_location: location:385421
stack_discounting: false
reuse_qualifying_items: false
enable_menu_item_aggregator: false
minimum_unit_rate: 0.01
unit_discount: 10
receipt_qualifiers:
- attribute: amount
operator: in
value: '1'
- attribute: receipt_day
operator: in
value: '10'
- attribute: subtotal_amount
operator: '>='
value: '10'
- attribute: receipt_month
operator: ==
value: '10'
- attribute: receipt_year
operator: ==
value: '2024'
- attribute: revenue_code
operator: in
value: Online
- attribute: revenue_id
operator: in
value: '10'
- attribute: employee_id
operator: in
value: '10'
- attribute: employee_name
operator: in
value: john
- attribute: receipt_week
operator: ==
value: '10'
- attribute: receipt_min
operator: in
value: '10'
- attribute: channel
operator: in
value: POS
- attribute: transaction_no
operator: mod
value: '1001'
percentage_of_processed_amount: 10
qc_processing_function: rate_rollback
line_item_filters:
- quantity: null
processing_method: max_price
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- quantity: 1
processing_method: ''
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- quantity: 5
processing_method: max_price
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- quantity: 5
processing_method: min_price
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- quantity: 5
processing_method: min_price
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
item_qualifiers:
- expression_type: net_quantity_greater_than_or_equal_to
net_value: 1
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- expression_type: net_quantity_greater_than_or_equal_to
net_value: 1
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- expression_type: net_quantity_greater_than_or_equal_to
net_value: 1
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
- expression_type: net_quantity_greater_than_or_equal_to
net_value: 1
line_item_selector:
name: Pizzaa
external_id: EXTERNAL_ID_GOES_HERE
exclude_non_payable: false
filter_item_set: base_only
base_items:
clauses:
- attribute: item_id
operator: ==
value: '219'
modifiers:
processing_method: ''
max_discount_units: null
clauses: []
aggregator_grouping_attributes:
item_name: true
item_id: false
item_major_group: false
item_family: false
line_item_type: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'422':
description: Unprocessable Entity - Invalid redeemable UUID
content:
application/json:
schema:
type: object
properties: {}
operationId: get-api2-dashboard-offers-redeemable
description: "Pulls a list of all redeemables available and defined at the business level. \n\n\
To call this API, the offers ingestion option must be enabled for the business on the Punchh platform.\
\ Contact your Punchh representative to update this Punchh platform configuration.\n\n\nRedeemable search is on a\
\ business level, and the request can:\n\n* Set search limits and order by descending search\n\
* Filter based on name and description\n\nFor more information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)"
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
x-stoplight:
id: 89ced15e862a4
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
x-stoplight:
id: s6l6sdjdb4yd6
description: Define the search string on the redeemable name column
page:
type: integer
x-stoplight:
id: ioz1moj7a61jc
description: Number of pages to retrieve. If the requested number exceeds the available
pages, the system will retrieve up to the last valid page. If the `page` value is
not provided, the default value is used.
default: 1
per_page:
type: integer
x-stoplight:
id: t6184wmxubd8b
description: Number of records per page. If the `per_page` value is not provided, the
default value is used. The maximum `per_page` value is enforced based on the OFFERS_LIST_MAX_PER_PAGE
environment variable.
default: 20
examples:
Example:
value:
query: free
page: 1
per_page: 20
description: ''
post:
summary: Create Redeemable
operationId: post-api2-dashboard-offers-redeemable
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
x-stoplight:
id: zce920cfi6rf7
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: h0zz0r30ilg0m
type: object
properties:
external_id:
type: string
x-stoplight:
id: n58wru3di7ej9
description: Unique ID (UUID) sent by the external system to track if a particular
entity is successfully created in the Punchh system
success:
type: boolean
x-stoplight:
id: jekerhke4uljm
description: 'Status of a specific entity created in the system. Possible values:
true, false'
errors:
type: array
x-stoplight:
id: wtmvgc531x9fq
description: A list of error messages explaining why a specific entity is not
created in the system
items:
x-stoplight:
id: n4musy464awyw
type: string
warnings:
type: object
x-stoplight:
id: 8gdaxji90tjmr
description: A list of warning messages indicating potential issues found during
the creation of the redeemable. These warnings do not prevent the redeemable
from being created but may require attention. These warnings were ignored
as they did not trigger any validation errors.
properties:
receipt_rule:
type: object
x-stoplight:
id: qk4fgmxj9xliv
description: List of warnings that are ignored due to validation errors
for `receipt_rule`
properties:
redeeming_criterion:
type: object
x-stoplight:
id: vzwch5h94yrfj
description: List of warnings that are ignored due to validation errors
for `redeeming_criterion`
properties:
line_item_filters:
$ref: '#/components/schemas/warnings_line_item_filters'
item_qualifiers:
$ref: '#/components/schemas/warnings_item_qualifiers'
receipt_qualifiers:
$ref: '#/components/schemas/warnings_receipt_qualifiers'
qualifying_expressions_operator:
$ref: '#/components/schemas/warnings_qualifying_expressions_operator'
item_filter_expressions_operator:
$ref: '#/components/schemas/warnings_item_filter_expressions_operator'
discount_evaluation_strategy:
$ref: '#/components/schemas/warnings_discount_evaluation_strategy'
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings:
line_item_filters:
- message: 'Required parameters missing or invalid: line_item_selector_id, processing_method'
item:
line_item_selector_id: ''
processing_method: max
quantity: 5
- message: 'Required parameters missing or invalid: line_item_selector_id'
item:
line_item_selector_id: invalid
processing_method: max_price
quantity: 5
item_qualifiers:
- message: 'Required parameters missing or invalid: line_item_selector_id, expression_type'
item:
expression_type: ''
line_item_selector_id: invalid
net_value: 1
receipt_qualifiers:
- message: 'Required parameters missing or invalid: attribute'
item:
attribute: total
operator: '>='
value: '10'
- message: 'Required parameter is duplicate: attribute'
item:
attribute: total_amount
operator: in
value: '1'
qualifying_expressions_operator:
- message: 'Required parameters missing or invalid: qualifying_expressions_operator'
item:
qualifying_expressions_operator: an
item_filter_expressions_operator:
- message: 'Required parameters missing or invalid: item_filter_expressions_operator'
item:
item_filter_expressions_operator: an
discount_evaluation_strategy:
- message: 'Required parameters missing or invalid: discount_evaluation_strategy'
item:
discount_evaluation_strategy: ma
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
warnings: {}
'400':
description: Bad Request - Required parameter missing or empty
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: ko7iaimkvggfc
examples:
Required parameter missing or empty:
value:
error: 'Required parameter missing or the value is empty: data'
'401':
description: Unauthorized - User not authenticated or created
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: 1mfimwme208rn
examples:
User not authenticated or created:
value:
error: You need to sign in or sign up before continuing.
'403':
description: Forbidden - Functionality not available
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: ls57gx4l2nog9
examples:
Functionality Not Available:
value:
error: Sorry, this functionality is not available. Please contact support@punchh.com
to enable this.
'422':
description: Unprocessable Entity - Invalid redeemable uuid
content:
application/json:
schema:
type: object
properties: {}
description: "Allows a business to define one or more redeemables. You can bulk create a maximum\
\ of 20 redeemables per API call. If the request input contains more than 20 redeemables, only\
\ the first 20 are created, and the remaining are ignored. \n\nFor more information, see [Offers\
\ Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)\n\
\nTo call this API, the offers ingestion option must be enabled for the business on the Punchh\
\ platform. Contact your Punchh representative to update this Punchh platform configuration.\n\
\n\nFor more information\
\ on redeemable settings, see the [Redeemables](https://support.punchh.com/s/article/Redeemables)\
\ article on the Support Portal. \n\nNote: To view the Punchh product documentation on the Punchh\
\ Support Portal, you must log in to a Punchh platform production environment. If you already\
\ have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal.\n"
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/redeemable_data_input'
examples:
Example:
value:
data:
- name: Redeemable offer 30
alternate_locale_name:
- language: fr
translation: FR MarlOffer 0.25
- language: en
translation: MarlOffer 0.25
- language: es
translation: ES MarlOffer 0.25
external_id: EXTERNAL_ID_GOES_HERE
description: description
alternate_locale_description:
- language: fr
translation: FR $0.25 Marl sContent Delivery Loyalty Offer
- language: en
translation: $0.25 Marl sContent Delivery Loyalty Offer
- language: es
translation: ES $0.25 Marl sContent Delivery Loyalty Offer
note: Notes here
allow_for_support_gifting: true
available_as_template: false
distributable: true
distributable_to_all_users: false
segment_definition_id: null
auto_applicable: true
receipt_rule:
qualifier_type: new
redeeming_criterion_id: null
discount_amount: 10
redeeming_criterion:
name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location: location:1234
stack_discounting: false
reuse_qualifying_items: false
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
activate_now: false
start_time: '2025-06-25T23:59:59'
indefinetely: false
expiry_days: null
end_time: '2025-06-28T23:59:59'
timezone: Australia/Darwin
remind_before: 3
discount_channel: all
points: 12
redemption_code_expiry_mins: 3
applicable_as_loyalty_redemption: true
expire_redemption_code_with_reward_end_date: false
template:
redemption_message: Countdown Message text
short_prompt: Short Prompt text
standard_prompt: Standard Prompt text
lag_duration:
value: 2
units: days
recurrence_schedule:
occurrences: 10
days_distance: 2
effective_location: location:12
meta_data: meta data
x-stoplight:
value:
id: 4764c9052bca9
patch:
summary: Update Redeemable
operationId: patch-api2-dashboard-offers-redeemable
responses:
'200':
description: OK - Success
content:
application/json:
schema:
$ref: '#/components/schemas/redeemable_results'
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings: {}
- external_id: EXTERNAL_ID_GOES_HERE
success: false
errors:
- ERROR MESSAGE
warnings: {}
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
warnings:
receipt_rule:
redeeming_criterion:
line_item_filters:
- message: 'Required parameters missing or invalid: line_item_selector_id'
item:
line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 1
item_qualifiers:
- message: 'Required parameters missing or invalid: net_value'
item:
expression_type: net_quantity_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: -1
receipt_qualifiers:
- message: 'Required parameters missing or invalid: attribute'
item:
attribute: total
operator: '>='
value: '10'
qualifying_expressions_operator:
- message: 'Required parameters missing or invalid: qualifying_expressions_operator'
item:
qualifying_expressions_operator: an
item_filter_expressions_operator:
- message: 'Required parameters missing or invalid: item_filter_expressions_operator'
item:
item_filter_expressions_operator: an
discount_evaluation_strategy:
- message: 'Required parameters missing or invalid: discount_evaluation_strategy'
item:
discount_evaluation_strategy: ma
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
description: 'Allows a business to update one or more redeemables. You can bulk update a maximum
of 20 redeemables per API call. If the request input contains more than 20 redeemables, only the
first 20 are created, and the remaining are ignored.
For more information, see [Offers Ingestion Management](/docs/dev-portal-platform-functions/ms8qid5tdtvc6-offers-ingestion-management)
### PATCH Requests: Partial Updates and Nested Object Replacements
PATCH requests allow you to update specific parameters of a Redeemable object without affecting
others. You only need to include the parameters you want to modify. For example, you can update
only the `allow_for_support_gifting` parameter in a Redeemable object.
When updating a nested object (e.g., `receipt_rule`, `template`, `lag_duration`, `recurrence_schedule`),
the entire nested object is replaced with the valid values provided in the request. Invalid values
are ignored.
Additional rules when updating nested objects:
* If all provided values are invalid, the existing values remain unchanged.
* If an empty nested object is provided, the existing values are deleted.
* If the nested object or any of its parameters is omitted, existing values remain unaffected.
To call this API, the offers ingestion option must be enabled for the business on the Punchh platform.
Contact your Punchh representative to update this Punchh platform configuration.
For more information on Redeemable settings, see the [Redeemables](https://support.punchh.com/s/article/Redeemables)
article on the Support Portal.
Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to
a Punchh platform production environment. If you already have access to a production environment,
follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)
to access the Punchh Support Portal.'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/redeemable_data_input'
examples:
Example:
value:
data:
- name: Redeemable offer 30
alternate_locale_name:
- language: fr
translation: FR MarlOffer 0.25
- language: en
translation: MarlOffer 0.25
- language: es
translation: ES MarlOffer 0.25
external_id: EXTERNAL_ID_GOES_HERE
description: description
alternate_locale_description:
- language: fr
translation: FR $0.25 Marl sContent Delivery Loyalty Offer
- language: en
translation: $0.25 Marl sContent Delivery Loyalty Offer
- language: es
translation: ES $0.25 Marl sContent Delivery Loyalty Offer
note: Notes here
allow_for_support_gifting: true
available_as_template: false
distributable: true
distributable_to_all_users: false
segment_definition_id: null
auto_applicable: true
receipt_rule:
qualifier_type: new
redeeming_criterion_id: REDEEMING_CRITERION_ID_GOES_HERE
discount_amount: 10
redeeming_criterion:
name: 10% Off on Sandwich
external_id: EXTERNAL_ID_GOES_HERE
amount_cap: 3
percentage_of_processed_amount: 10
qc_processing_function: sum_amounts
rounding_rule: ceil
max_discount_units: 2
unit_discount: 10
minimum_unit_rate: 0.01
target_price: 1
effective_location: location:1234
stack_discounting: false
reuse_qualifying_items: false
qualifying_expressions_operator: All
item_filter_expressions_operator: Any
discount_evaluation_strategy: Min
line_item_filters:
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: max_price
quantity: 5
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: min_price
quantity: 3
- line_item_selector_id: LIS_ID_GOES_HERE
processing_method: exclude
quantity: null
enable_menu_item_aggregator: false
aggregator_grouping_attributes:
item_name: false
item_id: false
item_major_group: false
item_family: false
line_item_type: false
item_qualifiers:
- expression_type: line_item_exists
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: line_item_does_not_exist
line_item_selector_id: LIS_ID_GOES_HERE
net_value: null
- expression_type: net_quantity_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 2
- expression_type: net_amount_greater_than_or_equal_to
line_item_selector_id: LIS_ID_GOES_HERE
net_value: 4
receipt_qualifiers:
- attribute: total_amount
operator: '>='
value: '10'
- attribute: receipt_hour
operator: in
value: '1'
activate_now: false
start_time: '2025-06-25T23:59:59'
indefinetely: false
expiry_days: null
end_time: '2025-06-28T23:59:59'
timezone: Australia/Darwin
remind_before: 3
discount_channel: all
points: 12
redemption_code_expiry_mins: 3
applicable_as_loyalty_redemption: true
expire_redemption_code_with_reward_end_date: false
template:
redemption_message: Countdown Message text
short_prompt: Short Prompt text
standard_prompt: Standard Prompt text
lag_duration:
value: 2
units: days
recurrence_schedule:
occurrences: 10
days_distance: 2
effective_location: location:12
meta_data: meta data
/api2/dashboard/offers/upload_redeemable_image:
post:
summary: Upload Redeemable Image
operationId: post-api2-dashboard-offers-upload_redeemable_image
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
x-stoplight:
id: putsbxqg4ptss
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: s45p69ln4448a
type: object
properties:
external_id:
type: string
x-stoplight:
id: yd92ld4889ugs
description: Unique ID (UUID) sent by the external system to track if a particular
entity is successfully updated in the Punchh system
success:
type: boolean
x-stoplight:
id: q4isrvdfagig3
description: 'Indicates whether the image was successfully uploaded to the system.
Possible values: true, false'
errors:
type: array
x-stoplight:
id: i9z5jyx51g3ts
description: A list of error messages providing details about why the image
upload failed
items:
x-stoplight:
id: ocpy2sxjh6and
type: string
examples:
Example:
value:
results:
- external_id: EXTERNAL_ID_GOES_HERE
success: true
errors: []
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
description: Allows a business to upload images for redeemables in bulk by first uploading them
to a server or network and then providing the image URL in the API request. The maximum allowed
image size is 500 KB.
x-stoplight:
id: 66bf308f1c51f
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: array
x-stoplight:
id: vnmoxq6vk906k
description: A list of image URLs that need to be uploaded
items:
x-stoplight:
id: 9l4ppyo3wv13g
type: object
properties:
external_id:
type: string
x-stoplight:
id: y8dvinmpkjaf8
description: A unique external identifier (UUID) of the redeemable. See [Create
Redeemable](/docs/dev-portal-platform-functions/4764c9052bca9-create-redeemable)
image_url:
type: string
x-stoplight:
id: 8sh8hxncdjat4
description: A valid URL pointing to the image hosted on a Content Delivery Network
(CDN) or server
required:
- external_id
- image_url
examples:
Example:
value:
data:
- external_id: EXTERNAL_ID_GOES_HERE
image_url: https://www.example.com/image.jpg
description: ''
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
schemas:
aggregator_grouping_attributes:
title: Aggregator Grouping Attributes (Object)
x-stoplight:
id: iq2opeipfwlcq
type: object
description: Attributes that have to be matched to aggregate menu items. All menu items with identical
attributes are treated as the same, and the total quantity is the sum of its occurrences on the
receipt. This parameter is a required parameter if `enable_menu_item_aggregator` is sent as true.
properties:
item_name:
type: boolean
x-stoplight:
id: 0c5b64frkhg7r
description: 'Indicates whether to group menu items with the same item name together and aggregate
their quantities. Possible values: true, false'
item_id:
type: boolean
x-stoplight:
id: cwkwcvwpy7dxw
description: 'Indicates whether to group menu items with the same item ID together and aggregate
their quantities. Possible values: true, false'
item_major_group:
type: boolean
x-stoplight:
id: 3mybqncem0pbp
description: 'Indicates whether to group menu items with the same ID of the major grouping of
items and aggregate their quantities. Possible values: true, false'
item_family:
type: boolean
x-stoplight:
id: aer4gxjg2oz82
description: 'Indicates whether to group menu items with the same ID of the item’s family together
and aggregate their quantities. Possible values: true, false'
line_item_type:
type: boolean
x-stoplight:
id: lemyxyuixrzyo
description: 'Indicates whether to group menu items with the same type of menu item together
and aggregate their quantities. Possible values: true, false'
redeemable_alternate_locale_description:
title: Alternate Locale Description (Array Object)
x-stoplight:
id: 3y2hqeml324qq
type: array
description: An object representing the redeemable description in multiple languages
items:
x-stoplight:
id: 8szg455tajjof
type: object
properties:
language:
type: string
x-stoplight:
id: qasnnev0s3mx0
description: 'The language code representing the locale. Possible values: en-CY for English
(Cyprus), en-GB for English (United Kingdom), es for Spanish, es-CR for Spanish (Costa Rica),
es-US for Spanish (United States), fr for French, fr-ca for French (Canada), and ro for
Romanian'
translation:
type: string
x-stoplight:
id: 562siougg25ip
description: The translated description of the redeemable in the specified language
redeemable_alternate_locale_name:
title: Alternate Locale Name (Array Object)
x-stoplight:
id: 0xsss0n88vh7u
type: array
description: An object representing the redeemable name in multiple languages
items:
x-stoplight:
id: fftabdlo3dnth
type: object
properties:
language:
type: string
x-stoplight:
id: fuql2d7va5dqn
description: 'The language code representing the locale. Possible values: en-CY for English
(Cyprus), en-GB for English (United Kingdom), es for Spanish, es-CR for Spanish (Costa Rica),
es-US for Spanish (United States), fr for French, fr-ca for French (Canada), and ro for
Romanian'
translation:
type: string
x-stoplight:
id: 480v64bn1qnn3
description: The translated name of the redeemable in the specified language
base_items:
title: Base Items (Object)
x-stoplight:
id: i2wkaqftnszca
type: object
description: When building a new line item selector (LIS), you will define a base item, a modifier,
or both. A base item is the 'main' item. For example, a hamburger.
properties:
clauses:
type: array
x-stoplight:
id: vcgu0lqswges4
description: List of clauses for filtering base items. The base item discount will be applied
only if `filter_item_set` is set to base_only or base_and_modifiers.
items:
x-stoplight:
id: drl3vx8knxlpp
type: object
properties:
attribute:
type: string
x-stoplight:
id: dls4vyq6g9bjs
description: 'The attribute(s) to filter items that should be included in the offer or
promotion. The filtering can be done based on specific characteristics of the items.
For base items, you will complete at least one of the following attributes. The possible
values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g., "Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in your POS
system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least 2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in your POS
system (e.g., "1001" or "2002"). This is the middle (second) level in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping of items
in your POS system (e.g., "1000" or "2000"). The major group ID is the top level in
the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D"). Possible
values: Menu Item (M), Discount (D), Service Charge (S), Extra (X), Tax (T), or Payment
(P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g., items
above a certain amount).
'
operator:
type: string
x-stoplight:
id: 1t6bv3000jz33
description: 'The value specifies how an attribute should be filtered or selected in the
Punchh system. Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive, in_case_insensitive,
not_in, not_in_case_insensitive, like, not_like, in_range, not_in_range, mod, and in_special'
value:
type: string
x-stoplight:
id: tcg7394y8q5nn
description: Value of the attribute that needs to be filtered
item_qualifiers:
title: Item Qualifiers (Array Object)
x-stoplight:
id: lq6pjd2djqiak
type: array
description: List of items qualifiers associated with the qualification criteria (QC). The object
lists the items that must be present on the check to meet the QC. The processing function is triggered
only if the receipt satisfies all of the conditions specified in the object’s attributes.
items:
x-stoplight:
id: kgfyi17oejibs
type: object
properties:
expression_type:
type: string
x-stoplight:
id: gltluqx6d4l5g
description: 'List of predefined functions that define various conditions under which a receipt
is eligible for further processing. These conditions evaluate whether the receipt meets
certain requirements before triggering the processing function. The system will skip the
item if the expression type is not a valid value. Possible values include:
* line_item_does_not_exist - The specified line item must NOT be present on the receipt.
* line_item_exists (default) - The specified line item must be present on the receipt.
* net_amount_excluding_min_priced_item_equal_to_or_more_than - The total net amount on the
receipt, excluding the lowest-priced item, must be equal to or greater than the specified
amount.
* net_amount_excluding_max_priced_item_equal_to_or_more_than - The total net amount on the
receipt, excluding the highest-priced item, must be equal to or greater than the specified
amount.
* net_quantity_greater_than_or_equal_to - The total quantity of the specified item(s) must
be equal to or greater than the specified value.
* net_amount_greater_than_or_equal_to - The total net amount on the receipt must be equal
to or greater than the specified amount.
* net_quantity_equal_to - The total quantity of the specified item(s) must be exactly equal
to the specified value.'
line_item_selector:
$ref: '#/components/schemas/qc_line_item_selector'
net_value:
type: number
x-stoplight:
id: ujngr39da676u
description: Specifies the required numeric threshold (such as quantity or amount) that the
receipt must meet for certain expression_type conditions. `net_value` is an additional parameter
that depends on the selected `expression_type`. It must be an integer and greater than zero.
However, if `expression_type` is set to either "line_item_exists" or "line_item_does_not_exist",
`net_value` will be ignored and treated as null, even if a value is provided.
redeemable_lag_duration:
title: Lag Duration (Object)
x-stoplight:
id: y8ihb0cxfl4py
type: object
description: This object specifies the duration before the redeemable is gifted to the guest.
properties:
value:
type: integer
x-stoplight:
id: f6juqmterzqcu
description: Numeric amount representing the duration
units:
type: string
x-stoplight:
id: jj5umrnpyj6so
description: 'Unit of measurement for the duration. Possible values: days, hours'
qc_line_item_selector:
title: Line Item Selector (Object)
x-stoplight:
id: ztq2iadcevh3g
type: object
description: Shows the details of the line item selector (LIS) associated with the qualification
criteria (QC)
properties:
name:
type: string
x-stoplight:
id: 4s05n4ycy6p3k
description: Name of the line item selector (LIS)
external_id:
type: string
x-stoplight:
id: ddvmls9vihm0a
description: External transaction identifier (UUID) sent by the external system to track if
a particular entity is successfully created in the Punchh system
exclude_non_payable:
type: boolean
x-stoplight:
id: 79pikqyqcajbf
description: "When one or more discounts are returned as a modifier to the base item, and if\
\ the net amount for the modifier after the discount(s) is zero, the items will be excluded\
\ from the LIS. As a result, the item will not be considered when evaluating a receipt using\
\ the qualification criteria (QC) to which the LIS is linked. However, the base of the same\
\ LIS can be evaluated for additional discounting. Possible values: true, false \n\nNote:\
\ Applicable when `filter_item_set` is set to base_and_modifiers"
filter_item_set:
type: string
x-stoplight:
id: 2v3tfpeni9ta6
description: 'The value determines which item(s) will be eligible for the discount. Possible
values:
* base_only: The line item selector (LIS) will be considered a base item, and the discount
will be applied to the base item value only.
* modifiers_only: The line item selector (LIS) will be considered a modifier, and a discount
will be applied to the modifier amount value only.
* base_and_modifiers: The discount will be applied to the base and modifier total value.'
base_items:
$ref: '#/components/schemas/base_items'
modifiers:
$ref: '#/components/schemas/modifiers'
lis_data_input:
title: LIS Input (Object)
x-stoplight:
id: mljp2rgnuzqv5
type: object
x-examples: []
properties:
data:
type: array
x-stoplight:
id: 8wuledtj3w1s6
description: A list of line item selectors (LIS) that needs to be created
items:
x-stoplight:
id: rrore3skab6df
type: object
properties:
name:
type: string
x-stoplight:
id: fmqz0xsxtrbqo
description: Name of the line item selector (LIS)
external_id:
type: string
x-stoplight:
id: b148rl44qy536
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id` either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
filter_item_set:
type: string
x-stoplight:
id: dfb9g9pji1pi5
description: 'The value determines what item(s) will be eligible for the discount. Possible
values:
* base_only: The line item selector (LIS) will be considered a base item, and the discount
will be applied to the base item value only.
* modifiers_only: The line item selector (LIS) will be considered a modifier, and a
discount will be applied to the modifier amount value only. If the LIS is created with
"modifiers_only", you must provide both base and modifier clauses.
* base_and_modifiers: The discount will be applied to the base and modifier total value.'
exclude_non_payable:
type: boolean
x-stoplight:
id: theonam023s1x
description: "When one or more discounts are returned as a modifier to the base item,\
\ and if the net amount for the modifier after the discount(s) is zero, the items will\
\ be excluded from the LIS. As a result, the item will not be considered when evaluating\
\ a receipt using the qualification criteria (QC) to which the LIS is linked. However,\
\ the base of the same LIS can be evaluated for additional discounting. Possible values:\
\ true, false \n\nNote: Applicable when `filter_item_set` is set to base_and_modifiers"
base_items:
type: object
x-stoplight:
id: ev1nei2uw50hb
description: When building a new line item selector (LIS), you will define a base item,
a modifier, or both. A base item is the 'main' item. For example, a hamburger.
properties:
clauses:
type: array
x-stoplight:
id: 67an42xgld731
description: List of clauses for filtering base items. The base item discount will
be applied only if `filter_item_set` is set to base_only or base_and_modifiers.
items:
x-stoplight:
id: v3i7w1tpe4juz
type: object
properties:
attribute:
type: string
x-stoplight:
id: z435jipsqwhzy
description: 'The attribute(s) to filter items that should be included in the
offer or promotion. The filtering can be done based on specific characteristics
of the items. For base items, you will complete at least one of the following
attributes. The possible values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g.,
"Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in
your POS system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least
2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in
your POS system (e.g., "1001" or "2002"). This is the middle (second) level
in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping
of items in your POS system (e.g., "1000" or "2000"). The major group ID is
the top level in the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your
POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D").
Possible values: Menu Item (M), Discount (D), Service Charge (S), Extra (X),
Tax (T), or Payment (P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g.,
items above a certain amount).
'
operator:
type: string
x-stoplight:
id: 9tq32t3k0jlis
description: 'The value specifies how an attribute should be filtered or selected
in the Punchh system. Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive,
in_case_insensitive, not_in, not_in_case_insensitive, like, not_like, in_range,
not_in_range, mod and in_special'
value:
type: string
x-stoplight:
id: czfxr7njb2igl
description: Value of the attribute that needs to be filtered. The value needs
to be sent based on the operator selected; e.g., for the "in" operator, the
values must be comma-separated.
required:
- attribute
- operator
- value
required:
- clauses
modifiers:
type: object
x-stoplight:
id: wcxvzzfrrjgci
description: 'A modifier is an item that may accompany a base item. For example, if the
base item is a hamburger, a modifier could be pepper jack cheese. '
properties:
max_discount_units:
type: integer
x-stoplight:
id: v99tx9su0p157
description: This value limits the number of units that can be discounted. A unit
may be an individual menu item or a menu item bundle, depending on the configured
Processing Function. Leave the field blank to allow all qualifying units to be discounted,
or set a cap to it by providing an integer value greater than or equal to 1.
processing_method:
type: string
x-stoplight:
id: ntlt12rj785fr
description: "States how the modifiers will be selected for further processing when\
\ `max_discount_units` are defined. Possible values: \n* max_price: Specify max_price\
\ to discount the most expensive modifiers first.\n* min_price: Select min_price\
\ to discount the least expensive modifier first.\nNote: If this field is left blank,\
\ the discount will be applied to the modifiers as they appear on the receipt. If\
\ you have specified a number in `max_discount_units`, it is recommended also to\
\ specify a value in `processing_method`."
clauses:
type: array
x-stoplight:
id: eklw238ran2gd
description: List of clauses for filtering modifier items. The modifiers discount
will be applied only if `filter_item_set` is set to modifiers_only or base_and_modifiers.
items:
x-stoplight:
id: c4czlo3jbspcm
type: object
properties:
attribute:
type: string
x-stoplight:
id: 1knwxvvibus43
description: 'The attribute(s) to filter items that should be included in the
offer or promotion. The filtering can be done based on specific characteristics
of the items. For modifier items, you will complete at least one of the following
attributes. The possible values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g.,
"Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in
your POS system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least
2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in
your POS system (e.g., "1001" or "2002"). This is the middle (second) level
in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping
of items in your POS system (e.g., "1000" or "2000"). The major group ID is
the top level in the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your
POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D").
Possible values: Menu Item (M), Discount (D), Service Charge (S), Extra (X),
Tax (T), or Payment (P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g.,
items above a certain amount).
This allows businesses to apply targeted rules to specific items or item groups
within a transaction for promotions, discounts, or rewards. For example, if
you want to create an LIS that applies only to items with a specific item
ID or name, you would use one of these values to define the filtering criteria.'
operator:
type: string
x-stoplight:
id: 1ww7zev8c9m88
description: 'The value specifies how an attribute should be filtered or selected
in the Punchh system. Required if the `modifiers` object is sent in the request.
Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive, in_case_insensitive,
not_in, not_in_case_insensitive, like, not_like, in_range, not_in_range, mod
and in_special'
value:
type: string
x-stoplight:
id: novmepuo0dmua
description: Value of the attribute that needs to be filtered. Required if the
`modifiers` object is sent in the request. The value needs to be sent based
on the operator selected; e.g., for the "in" operator, the values must be
comma-separated.
required:
- attribute
- operator
- value
required:
- clauses
required:
- name
- external_id
required:
- data
lis_data_output:
title: LIS Output (Object)
x-stoplight:
id: mljp2rgnuzqv6
type: object
x-examples: []
properties:
data:
type: array
x-stoplight:
id: 8wuledtj3w1s6
description: A list of line item selectors
items:
x-stoplight:
id: rrore3skab6df
type: object
properties:
name:
type: string
x-stoplight:
id: fmqz0xsxtrbqo
description: Name of the line item selector (LIS)
external_id:
type: string
x-stoplight:
id: b148rl44qy536
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id` either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
filter_item_set:
type: string
x-stoplight:
id: dfb9g9pji1pi5
description: 'The value determines which item(s) will be eligible for the discount. Possible
values:
* base_only: The line item selector (LIS) will be considered a base item, and the discount
will be applied to only the base item value.
* modifiers_only: The line item selector (LIS) will be considered a modifier, and a
discount will be applied to only the modifier amount value.
* base_and_modifiers: The discount will be applied to the base and modifier total value.'
exclude_non_payable:
type: boolean
x-stoplight:
id: theonam023s1x
description: "When one or more discounts are returned as a modifier to the base item,\
\ and if the net amount for the modifier after the discount(s) is zero, the items will\
\ be excluded from the LIS. As a result, the item will not be considered when evaluating\
\ a receipt using the qualification criteria (QC) to which the LIS is linked. However,\
\ the base of the same LIS can be evaluated for additional discounting. Possible values:\
\ true, false \n\nNote: Applicable when `filter_item_set` is set to base_and_modifiers"
base_items:
type: object
x-stoplight:
id: ev1nei2uw50hb
description: When building a new line item selector (LIS), you will define a base item,
a modifier, or both. A base item is the 'main' item. For example, a hamburger.
properties:
clauses:
type: array
x-stoplight:
id: 67an42xgld731
description: List of clauses for filtering base items. The base item discount will
be applied only if `filter_item_set` is set to base_only or base_and_modifiers.
items:
x-stoplight:
id: v3i7w1tpe4juz
type: object
properties:
attribute:
type: string
x-stoplight:
id: z435jipsqwhzy
description: 'The attribute(s) to filter items that should be included in the
offer or promotion. The filtering can be done based on specific characteristics
of the items. For base items, you will complete at least one of the following
attributes. Possible values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g.,
"Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in
your POS system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least
2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in
your POS system (e.g., "1001" or "2002"). This is the middle (second) level
in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping
of items in your POS system (e.g., "1000" or "2000"). The major group ID is
the top level in the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your
POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D").
Possible values: Menu Item (M), Discount (D), Service Charge (S), Extra (X),
Tax (T), or Payment (P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g.,
items above a certain amount).
'
operator:
type: string
x-stoplight:
id: 9tq32t3k0jlis
description: 'The value specifies how an attribute should be filtered or selected
in the Punchh system. Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive,
in_case_insensitive, not_in, not_in_case_insensitive, like, not_like, in_range,
not_in_range, mod, and in_special'
value:
type: string
x-stoplight:
id: czfxr7njb2igl
description: Value of the attribute that needs to be filtered
modifiers:
type: object
x-stoplight:
id: wcxvzzfrrjgci
description: A modifier is an item that may accompany a base item. For example, if the
base item is a hamburger, a modifier could be pepper jack cheese.
properties:
max_discount_units:
type: integer
x-stoplight:
id: v99tx9su0p157
description: This value limits the number of units that can be discounted. A unit
may be an individual menu item or a menu item bundle, depending on the configured
processing function.
processing_method:
type: string
x-stoplight:
id: ntlt12rj785fr
description: "States how the modifiers will be selected for further processing when\
\ `max_discount_units` are defined. Possible values: \n* max_price - Specifies that\
\ the most expensive modifiers are discounted first\n* min_price - Specifies that\
\ the least expensive modifiers are discounted first"
clauses:
type: array
x-stoplight:
id: eklw238ran2gd
description: List of clauses for filtering modifier items. The modifiers discount
will be applied only if `filter_item_set` is set to modifiers_only or base_and_modifiers.
items:
x-stoplight:
id: c4czlo3jbspcm
type: object
properties:
attribute:
type: string
x-stoplight:
id: 1knwxvvibus43
description: 'The attribute(s) to filter items that should be included in the
offer or promotion. The filtering can be done based on specific characteristics
of the items. For modifier items, you will complete at least one of the following
attributes. Possible values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g.,
"Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in
your POS system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least
2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in
your POS system (e.g., "1001" or "2002"). This is the middle (second) level
in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping
of items in your POS system (e.g., "1000" or "2000"). The major group ID is
the top level in the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your
POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D").
Possible values: Menu Item (M), Discount (D), Service Charge (S), Extra (X),
Tax (T), or Payment (P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g.,
items above a certain amount).'
operator:
type: string
x-stoplight:
id: 1ww7zev8c9m88
description: 'The value specifies how an attribute should be filtered or selected
in the Punchh system. Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive,
in_case_insensitive, not_in, not_in_case_insensitive, like, not_like, in_range,
not_in_range, mod, and in_special'
value:
type: string
x-stoplight:
id: novmepuo0dmua
description: Value of the attribute that needs to be filtered
meta:
type: object
x-stoplight:
id: scuvzjiwhsg2u
description: Contains pagination information
properties:
page:
type: integer
x-stoplight:
id: mvfno134ia5f7
description: Current page number
per_page:
type: integer
x-stoplight:
id: rdrzjufkuqyz2
description: Number of records per page
total_records:
type: integer
x-stoplight:
id: sb7jky4milbi4
description: Total number of records available
lis_results:
title: LIS Results (Object)
x-stoplight:
id: jpwwu4zsdviju
type: object
x-examples: {}
properties:
results:
type: array
x-stoplight:
id: gb8msmyvub03l
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: myq9wo2kds83u
type: object
properties:
external_id:
type: string
x-stoplight:
id: bjrapcsn7reme
description: External transaction identifier (UUID) sent by the external system to track
if a particular entity is successfully created in the Punchh system
success:
type: boolean
x-stoplight:
id: 7xsru2q46lplr
description: 'Status of a specific entity created in the system. Possible values: true,
false'
errors:
type: array
x-stoplight:
id: romm61qwl4n71
description: A list of error messages explaining why a specific entity was not created
in the system
items:
x-stoplight:
id: zhbm3xfh0bsdm
type: string
warnings:
type: object
x-stoplight:
id: 331ecg16j6qnq
description: A list of warning messages indicating potential issues found during the creation
of the LIS. These warnings do not prevent the LIS from being created but may require
attention. These warnings were ignored as they did not trigger any validation errors.
properties:
base_items:
type: object
x-stoplight:
id: 4zbrsmjc1tu6n
description: List of warnings related to base_items
properties:
clauses:
type: array
x-stoplight:
id: 1bw7t5rkh2301
description: List of warnings related to the base_items clauses
items:
x-stoplight:
id: m7xuict7un49e
type: object
properties:
message:
type: string
x-stoplight:
id: 3hxndnv4fbjf2
description: Warning message indicates which parameter contains an invalid
value in the clauses of base_items.
item:
type: object
x-stoplight:
id: md0kbh0bloy26
description: JSON object of base_items clauses that has an invalid value
properties:
attribute:
type: string
x-stoplight:
id: kgul9corj9ndg
description: Attribute name on which filtering needs to be done
operator:
type: string
x-stoplight:
id: 8jfim7zxxuv9e
description: The value specifies how an attribute should be filtered
or selected in the Punchh system.
value:
type: string
x-stoplight:
id: 96ge7i4ege5ig
description: Value of the attribute that needs to be filtered
modifiers:
type: object
x-stoplight:
id: 616cugklr7u3o
description: List of warnings related to modifiers
properties:
clauses:
type: array
x-stoplight:
id: 3tj7bg5rovbd1
description: List of warnings related to modifier clauses
items:
x-stoplight:
id: 7gyqoad7kibs5
type: object
properties:
message:
type: string
x-stoplight:
id: qe6tmqf9wzarm
description: Warning message indicates which parameter contains an invalid
value in the modifier clauses
item:
type: object
x-stoplight:
id: poi4en7kh2y7t
description: JSON object of modifiers clauses that has an invalid value
properties:
attribute:
type: string
x-stoplight:
id: x18spjuurwuhh
description: Attribute name on which filtering needs to be done
operator:
type: string
x-stoplight:
id: c4jy165mvo1iw
description: The value specifies how an attribute should be filtered
or selected in the Punchh system
value:
type: string
x-stoplight:
id: 6hnrlh6ts6wcs
description: Value of the attribute that needs to be filtered
meta:
title: Meta (Object)
x-stoplight:
id: f3gs3v1eqesb4
type: object
description: Shows pagination information
properties:
page:
type: integer
x-stoplight:
id: mupl2h3xge8l0
description: Current page number
per_page:
type: integer
x-stoplight:
id: 3qf8vl6x5afei
description: Number of records per page
total_records:
type: integer
x-stoplight:
id: v9lk6gcy9jzs9
description: Total number of records available
modifiers:
title: Modifiers (Object)
x-stoplight:
id: w4lf29swhlpt2
type: object
description: A modifier is an item that may accompany a base item. For example, if the base item
is a hamburger, a modifier could be pepper jack cheese.
properties:
clauses:
type: array
x-stoplight:
id: ddt1jq7sko9sh
description: List of clauses for filtering modifier items. The modifiers discount will be applied
only if `filter_item_set` is set to modifiers_only or base_and_modifiers.
items:
x-stoplight:
id: tuue0psh30q24
type: object
properties:
attribute:
type: string
x-stoplight:
id: m2yei58cpf9dm
description: 'The attribute(s) to filter items that should be included in the offer or
promotion. The filtering can be done based on specific characteristics of the items.
For modifier items, you will complete at least one of the following attributes. Possible
values for the attribute(s) are:
* item_name: Filter the item using the item name in your POS system (e.g., "Sandwich").
* item_id: Filter item(s) using their unique identifier or product code in your POS
system. This is the third and most specific level in the POS hierarchy.
* quantity: Filter based on the number of units purchased (e.g., "at least 2 sandwiches").
* item_family: Filter the item using the unique ID of the item’s family in your POS
system (e.g., "1001" or "2002"). This is the middle (second) level in the POS hierarchy.
* item_major_group: Filter the item using the unique ID of the major grouping of items
in your POS system (e.g., "1000" or "2000"). The major group ID is the top level in
the POS hierarchy, above the family group and item ID.
* item_serial_number: Filter the item using the item’s serial number in your POS system.
* line_item_type: Filter based on the type of the menu item (e.g., "M", "D"). Possible
values: Menu Item (M), Discount (D), Service Charge (S), Extra (X), Tax (T), or Payment
(P) such as a gift card
* item_total_amount: Filter based on the exact price or range of prices (e.g., items
above a certain amount).
This allows businesses to apply targeted rules to specific items or item groups within
a transaction for promotions, discounts, or rewards. For example, if you want to create
an LIS that only applies to items with a specific item ID or name, you would use one
of these values to define the filtering criteria.'
operator:
type: string
x-stoplight:
id: ahxvy2m1x3qnk
description: 'The value specifies how an attribute should be filtered or selected in the
Punchh system. Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive, in_case_insensitive,
not_in, not_in_case_insensitive, like, not_like, in_range, not_in_range, mod, and in_special'
value:
type: string
x-stoplight:
id: 7i9bciifthc2t
description: Value of the attribute that needs to be filtered
processing_method:
type: string
x-stoplight:
id: nj0gbkyn97wxi
description: "States how the modifiers will be selected for further processing when `max_discount_units`\
\ are defined. Possible values: \n* max_price - Specifies that the most expensive modifiers\
\ are discounted first\n* min_price - Specifies that the least expensive modifiers are discounted\
\ first"
max_discount_units:
type: integer
x-stoplight:
id: j9m1uwbxi2wi3
description: This value limits the number of units that can be discounted. A unit may be an
individual menu item or a menu item bundle, depending on the configured processing function.
qc_data_input:
title: QC Input (Object)
x-stoplight:
id: i0yltuftvwcf6
type: object
properties:
data:
type: array
x-stoplight:
id: l2eplxkth3jif
description: A list of qualification criteria (QC) that need to be created
items:
x-stoplight:
id: 289v9n9x325ut
type: object
properties:
name:
type: string
x-stoplight:
id: 2eejxuoc3a0j2
description: Name of qualification criteria (QC). The name can be up to 255 characters
long.
maxLength: 255
minLength: 1
external_id:
type: string
x-stoplight:
id: kfc6g16pwg8rh
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id`, either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
amount_cap:
type: number
x-stoplight:
id: 2jljgc0nhidbe
description: Maximum amount that can be earned/redeemed on any receipt. The value should
be greater than or equal to 0 and less than or equal to 99999 if provided.
minimum: 0
maximum: 99999
format: float
percentage_of_processed_amount:
type: number
x-stoplight:
id: jjdphn7hfc01q
description: Percentage of processed amount that can be earned/redeemed on any receipt.
The value should be greater than or equal to 0 and less than or equal to 99999 if provided.
minimum: 1
maximum: 99999
format: float
qc_processing_function:
type: string
x-stoplight:
id: i2extlgbomzij
description: 'Function applied on filtered menu items of the receipt. Processing functions
return a processed value that governs discounting and earning depending on where the
qualification criterion is attached. If it is applied in a discounting scenario, the
processed value controls the discount amount. If it is applied in an earning scenario
(e.g., a rewards program), the processed value controls how much is earned (such as
reward points). This parameter is optional when updating qualification criteria (QC).
Possible values: hit_target_price, rate_rollback, bundle_price_target, bundle_price_target_advanced,
hit_target_price_max_price_once, hit_target_price_min_price_once, sum_amounts_incremental,
static_amount, receipt_subtotal, bogof, bogof2, sum_amounts, receipt_total_amount, sum_qty
For more information on possible values, see the [Processing Functions]( https://support.punchh.com/s/article/Processing-Functions)
article on the Support Portal.
Note: To view the Punchh product documentation on the Punchh Support Portal, you must
log in to a Punchh platform production environment. If you already have access to a
production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)
to access the Punchh Support Portal.'
qualifying_expressions_operator:
type: string
x-stoplight:
id: 7in7ag4licd2z
description: 'Specifies how offer conditions in `item_qualifiers` are evaluated. Possible
values: All, Any. The default value is "All". Use "All" when every condition must be
met, or "Any" when satisfying at least one condition is sufficient.'
default: All
item_filter_expressions_operator:
type: string
x-stoplight:
id: h4v56u7aissz7
description: 'Specifies how offer conditions in `line_item_filters` are evaluated. Possible
values: All, Any. The default value is "All". Use "All" when every condition must be
met, or "Any" when satisfying at least one condition is sufficient.'
default: All
discount_evaluation_strategy:
type: string
x-stoplight:
id: pzgh5l2yr74vm
description: 'Specifies whether the maximum or minimum discount should be applied when
multiple conditions are met. Note: This parameter should be provided when `item_filter_expressions_operator`
is set to Any. Possible values: Min, Max. The default value is "Min".'
default: Min
rounding_rule:
type: string
x-stoplight:
id: 6nidyy7xcjlpn
description: "If the processing function returns a float value, it will be rounded according\
\ to the chosen rounding rule. If no rule is selected, the float value will be used\
\ as is. A value is required to be sent in the parameter depending on the processing\
\ function selected. Possible values: \n* round: This rule rounds the float value to\
\ the nearest integer. If the decimal part is 0.5 or higher, the value is rounded up.\
\ If the decimal part is less than 0.5, the value is rounded down. For example, 4.3\
\ becomes 4, and 4.7 becomes 5.\n* ceil: This rule rounds the float value up to the\
\ next highest integer, regardless of the decimal part. For example, 4.3 becomes 5.\n\
* floor: This rule rounds the float value down to the next lowest integer, regardless\
\ of the decimal part. For example, 4.3 becomes 4."
max_discount_units:
type: integer
x-stoplight:
id: 49gq1hglnuxez
description: This value limits the number of units that can be discounted. A value is
required to be sent in the parameter depending on the processing function (`qc_processing_function`)
types selected, such as rate_rollback, bundle_price_target, bundle_price_target_advanced,
and sum_amounts_incremental.
minimum: 0
maximum: 99999
minimum_unit_rate:
type: number
x-stoplight:
id: zfbtdc1ifud9v
description: Minimum unit price threshold. After applying the discount, the minimum unit
rate should not be below this amount. A value greater than or equal to 0.01 and less
than or equal to 99999 is required if the processing method (`qc_processing_function`)
is rate_rollback.
minimum: 0.01
maximum: 99999
unit_discount:
type: number
x-stoplight:
id: lxoccu80hjqgt
description: Discount to be applied to the rate of the selected items chosen for the offer
or promotion. The discount is based on a specific rate (e.g., per unit of item -- per
gallon, per liter, etc.). For example, for a fuel discount of 20 cents per gallon, you
need to specify the discount in a decimal format (like 0.2) to reflect a 20-cent reduction
for each gallon of fuel. If the qualification criteria are attached to a subscription
plan, the value of the unit discount will be picked up from the subscription plan; even
though you are required to enter a value for the discount (e.g., 0.2 for 20 cents),
this value will be ignored if the QC are part of a subscription plan, because
the discount will be controlled by the subscription plan's settings instead. The value
should be greater than or equal to 0.01 and less than or equal to 99999 if the processing
method (`qc_processing_function`) is rate_rollback. A value is required to be sent in
the parameter depending on the processing function selected.
format: float
target_price:
type:
- number
x-stoplight:
id: 1xqs99evdc90e
description: Discount selected menu items to achieve this target unit price. For example,
if locations sell a burger for variable pricing, a target unit price is achieved by
using the appropriate processing function. If a burger is sold at different prices at
different locations (e.g., one location sells it for $10, another for $12), you can
set a target price (e.g., $9) to standardize the price across locations. The system
applies discounts to bring the price down to $9, no matter what the original price was.
A value is required to be sent in the parameter depending on the processing function
(`qc_processing_function`) types selected, such as hit_target_price, hit_target_price_max_price_once,
hit_target_price_min_price_once, bundle_price_target, and bundle_price_target_advanced.
minimum: 0.01
effective_location:
type:
- array
x-stoplight:
id: xdwh79i6ie9ez
description: 'An array of valid existing location IDs and/or location group (tag) IDs.
The default is an empty array ([]). Restricts redemption to the specified locations
or groups. Use the format "location:" or "tag:".
Example: ["location:123", "tag:456"]. The maximum allowed combined total of locations
and location groups is 50.'
items:
x-stoplight:
id: rp8hc7d4ducg4
type: string
stack_discounting:
type: boolean
x-stoplight:
id: xfspaqyhy1rfi
description: When stacking is set to true, this discount can be redeemed with any other
discount that contains the same target item. If set to false, only one discount can
be applied to the target item, even if multiple discounts are available. "Y", "YES",
"1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other values are considered
false.
reuse_qualifying_items:
type: boolean
x-stoplight:
id: 50m3u684y74bx
description: When set to true, it allows qualifying item(s) to be reused when redeemed
with other discounts that apply to the same item(s). When set to false, it restricts
qualifying item(s) from being reused for multiple discounts. "Y", "YES", "1", "TRUE",
and "ON" (case-insensitive) are treated as true. Any other values are considered false.
line_item_filters:
$ref: '#/components/schemas/qc_line_item_filters_input'
enable_menu_item_aggregator:
type: boolean
x-stoplight:
id: h4ycxre7l7973
description: Whether the system will combine (aggregate) multiple instances of the same
menu item into one entry based on the attributes defined in `aggregator_grouping_attributes`.
"Y", "YES", "1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other
values are considered false.
aggregator_grouping_attributes:
type: object
x-stoplight:
id: lni6h7tgnwsss
description: Attributes that have to be matched to aggregate menu items. All menu items
with identical attributes are treated as the same, and the total quantity is the sum
of its occurrences on the receipt. This parameter is required if `enable_menu_item_aggregator`
is sent as true.
properties:
item_name:
x-stoplight:
id: 1jyct3ow75yf2
type: boolean
description: 'Indicates whether to group menu items with the same item name together
and aggregate their quantities. Possible values: true, false'
item_id:
type: boolean
x-stoplight:
id: 8d7po504bgshy
description: 'Indicates whether to group menu items with the same item ID together
and aggregate their quantities. Possible values: true, false'
item_major_group:
type: boolean
x-stoplight:
id: orcwljrl9wn46
description: 'Indicates whether to group menu items with the same ID of the major
grouping of items and aggregate their quantities. Possible values: true, false'
item_family:
type: boolean
x-stoplight:
id: 0xwndctk8bkq3
description: 'Indicates whether to group menu items with the same ID of the item’s
family together and aggregate their quantities. Possible values: true, false'
line_item_type:
type: boolean
x-stoplight:
id: 7ch5hbxcx3eza
description: 'Indicates whether to group menu items with the same type of menu item
together and aggregate their quantities. Possible values: true, false'
item_qualifiers:
$ref: '#/components/schemas/qc_item_qualifiers_input'
receipt_qualifiers:
$ref: '#/components/schemas/receipt_qualifiers'
required:
- external_id
- qc_processing_function
required:
- data
qc_item_qualifiers_input:
title: QC Input - Item Qualifiers (Array Object)
x-stoplight:
id: 0ndlcqae60ta6
type: array
description: 'Lists the items that must be present on the check to meet the qualification criteria.
The processing function is triggered only if the receipt satisfies all of the conditions specified
in the object’s attributes.
Note: When updating item qualifiers, do not pass this object in the request if you do not want
to update `item_qualifiers`. If an empty array object [] is provided, all previously created item
qualifiers will be deleted.
'
items:
x-stoplight:
id: 00actsh3la2si
type: object
properties:
line_item_selector_id:
type: string
x-stoplight:
id: 4mde2pc3va6oh
description: 'ID of the pre-existing LIS, which for now will be the external_id. Note: If
the line item selector ID is invalid, the system will skip that line item filter and create
the qualification criteria with valid LIS IDs.'
expression_type:
type: string
x-stoplight:
id: pjstvek2o5biq
description: 'List of predefined functions that define various conditions under which a receipt
is eligible for further processing. These conditions evaluate whether the receipt meets
certain requirements before triggering the processing function. The system will skip the
item if the expression type is not a valid value. Possible values include:
* line_item_does_not_exist: The specified line item must NOT be present on the receipt.
* line_item_exists (default): The specified line item must be present on the receipt.
* net_amount_excluding_min_priced_item_equal_to_or_more_than: The total net amount on the
receipt, excluding the lowest-priced item, must be equal to or greater than the specified
amount.
* net_amount_excluding_max_priced_item_equal_to_or_more_than: The total net amount on the
receipt, excluding the highest-priced item, must be equal to or greater than the specified
amount.
* net_quantity_greater_than_or_equal_to: The total quantity of the specified item(s) must
be equal to or greater than the specified value.
* net_amount_greater_than_or_equal_to: The total net amount on the receipt must be equal
to or greater than the specified amount.
* net_quantity_equal_to: The total quantity of the specified item(s) must be exactly equal
to the specified value.'
net_value:
type: number
x-stoplight:
id: d68bi9o1cvp14
description: Specifies the required numeric threshold (such as quantity or amount) that the
receipt must meet for certain `expression_type` conditions. `net_value` is an additional
parameter that depends on the selected `expression_type`. It must be an integer and greater
than zero. However, if the `expression_type` is set to either "line_item_exists" or "line_item_does_not_exist",
the `net_value` will be ignored and treated as null, even if a value is provided.
qc_line_item_filters_input:
title: QC Input - Line Item Filters
x-stoplight:
id: p2j01i99nn06q
type: array
description: 'Lists the items to be discounted by using filters to select applicable menu items.
Leave the filter empty to apply the discount to all menu items. If multiple items are selected,
the processing function will be applied to each, and the final result will be the sum of all values.
Note: When updating line item filters, do not pass this object if you do not want to update
`line_item_filters`. If an empty array object [] is provided, all previously created line item
filters will be deleted.
'
items:
x-stoplight:
id: dw7o6he1vftrf
type: object
properties:
line_item_selector_id:
type: string
x-stoplight:
id: edzdryggy3455
description: 'ID of the pre-existing LIS, which for now will be the external_id. Note: If
the line item selector ID is invalid, the system will skip that line item filter and create
the other line item filters with valid LIS IDs.'
processing_method:
type: string
x-stoplight:
id: o2c8wu4tw52oj
description: 'The processing method for a line item filter determines how the selected items
are handled when applying a discount. The system will skip the line item filter if the value
of `processing_method` is invalid. The available processing methods are:
* max_price: Applies the discount to the item with the highest price
* min_price: Applies the discount to the item with the lowest price
* exclude: Excludes the selected items from the discount
* sum_of_amount (default): Applies the discount based on the total sum of the selected items''
prices'
quantity:
type: integer
x-stoplight:
id: um20q1tdltn1e
description: 'Specifies how many units of a particular item will be selected or filtered for
processing. A value is required if the processing function is selected as `min_price` or
`max_price`. If you apply a filter on certain items and specify the quantity, the system
will process only the selected number of units for that item. For example, if the quantity
is set to 3, only 3 units of the item will be included in the filter or discount. The quantity
value must adhere to certain rules:
* The value of quantity must be a whole number.
* The quantity cannot be negative.
* You must have at least 1 unit of the item.
* You can select up to 5 units of an item.'
qc_data_output:
title: QC List Output (Object)
x-stoplight:
id: 2cpl8d7qmnsl7
type: object
properties:
data:
type: array
x-stoplight:
id: shl1s59zemvqd
description: A list of qualification criteria (QC)
items:
x-stoplight:
id: aswag4t2up7bn
type: object
properties:
name:
type: string
x-stoplight:
id: uzk3pa4p6054v
description: Name of the qualification criteria (QC). The name can be up to 255 characters
long.
external_id:
type: string
x-stoplight:
id: goy2kiaapafu1
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id` either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
amount_cap:
type: number
x-stoplight:
id: znddjw2cwxyqe
format: float
description: Maximum amount that can be earned/redeemed on any receipt
percentage_of_processed_amount:
type: number
x-stoplight:
id: xcq9f0bqah9kz
format: float
description: Percentage of processed amount that can be earned/redeemed on any receipt
qc_processing_function:
type: string
x-stoplight:
id: 861nyi4m1yjev
description: "Function applied on filtered menu items of the receipt. Processing functions\
\ return a processed value that governs discounting and earning depending on where the\
\ qualification criterion is attached. If it is applied in a discounting scenario, the\
\ processed value controls the discount amount. If it is applied in an earning scenario\
\ (e.g., a rewards program), the processed value controls how much is earned (such as\
\ reward points). \n\nPossible values: hit_target_price, rate_rollback, bundle_price_target,\
\ bundle_price_target_advanced, hit_target_price_max_price_once, hit_target_price_min_price_once,\
\ sum_amounts_incremental, static_amount, receipt_subtotal, bogof, bogof2, sum_amounts,\
\ receipt_total_amount, sum_qty\n\nFor more information on possible values, see the\
\ [Processing Functions]( https://support.punchh.com/s/article/Processing-Functions)\
\ article on the Support Portal.\nNote: To view the Punchh product documentation on\
\ the Punchh Support Portal, you must log in to a Punchh platform production environment.\
\ If you already have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
rounding_rule:
type: string
x-stoplight:
id: lk57gnvx6nqmj
description: "If the processing function returns a float value, it will be rounded according\
\ to the chosen rounding rule. If no rule is selected, the float value will be used\
\ as is. A value is required to be sent in the parameter depending on the processing\
\ function selected. Possible values: \n* round: This rule rounds the float value to\
\ the nearest integer. If the decimal part is 0.5 or higher, the value is rounded up.\
\ If the decimal part is less than 0.5, the value is rounded down. For example, 4.3\
\ becomes 4, and 4.7 becomes 5.\n* ceil: This rule rounds the float value up to the\
\ next highest integer, regardless of the decimal part. For example, 4.3 becomes 5.\n\
* floor: This rule rounds the float value down to the next lowest integer, regardless\
\ of the decimal part. For example, 4.3 becomes 4."
max_discount_units:
type: integer
x-stoplight:
id: kq0qin1gzaiuy
description: This value limits the number of units that can be discounted. It works only
with specific `qc_processing_function` types, such as rate_rollback, bundle_price_target,
bundle_price_target_advanced, and sum_amounts_incremental.
minimum: 1
minimum_unit_rate:
type: number
x-stoplight:
id: 7u3cakqb804a2
description: Minimum unit price threshold. After applying the discount, the minimum unit
rate should be at this amount.
unit_discount:
type: number
x-stoplight:
id: 094l13tl26egj
format: float
description: Discount to be applied to the rate of the selected items chosen for the offer
or promotion. The discount is based on a specific rate (e.g., per unit of item -- per
gallon, per liter, etc.). For example, for a fuel discount of 20 cents per gallon, you
need to specify the discount in a decimal format (like 0.2) to reflect a 20-cent reduction
for each gallon of fuel. If these QC are attached to a subscription plan, the value
of the unit discount will be picked up from the subscription plan; even though you are
required to enter a value for the discount (e.g., 0.2 for 20 cents), this value will
be ignored if the QC is part of a subscription plan, because the discount will be
controlled by the subscription plan's settings instead. The value should be greater
than or equal to 0.01 and less than or equal to 99999 if the processing method (`qc_processing_function`)
is rate_rollback. A value is required to be sent in the parameter depending on the processing
function selected.
target_price:
type:
- number
x-stoplight:
id: 5r4b3thjf5y15
description: Discount selected menu items to achieve this target unit price. For example,
if locations sell a burger for variable pricing, a target unit price is achieved by
using the appropriate processing function, and this target price only works with specific
`qc_processing_function`. If a burger is sold at different prices at different locations
(e.g., one location sells it for $10, another for $12), you can set a target price (e.g.,
$9) to standardize the price across locations. The system applies discounts to bring
the price down to $9, no matter what the original price was.
effective_location:
type: array
x-stoplight:
id: burcp8lmvqpbl
description: 'An array of location and/or location group (tag) identifiers where the qualification
criterion applies. The default is an empty array ([]). Each entry is in the format "location:"
or "tag:". Example: ["location:123", "tag:456"]. The maximum allowed
combined total of locations and tags is 50'
items:
x-stoplight:
id: 964nzcxm85ttc
type: string
stack_discounting:
type: boolean
x-stoplight:
id: r1hkkmmr9ziy0
description: When stacking is set to true, this discount can be redeemed with any other
discount that contains the same target item. If set to false, only one discount can
be applied to the target item, even if multiple discounts are available. "Y", "YES",
"1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other values are considered
false.
reuse_qualifying_items:
type: boolean
x-stoplight:
id: 8xwejpz1ybyhz
description: When set to true, it allows qualifying item(s) to be reused when redeemed
with other discounts that apply to the same item(s). When set to false, it restricts
qualifying item(s) from being reused for multiple discounts. "Y", "YES", "1", "TRUE",
and "ON" (case-insensitive) are treated as true. Any other values are considered false.
line_item_filters:
type: array
x-stoplight:
id: ibshkriaq76x4
description: List of line item selectors (LIS) associated with the qualification criteria
(QC)
items:
x-stoplight:
id: sr7swfpo1xtmp
type: object
properties:
processing_method:
type: string
x-stoplight:
id: r5qu75b4qa49c
description: 'The processing method for a line item filter determines how the selected
items are handled when applying a discount. The system will skip the line item
filter if the value of `processing_method` is invalid. The available processing
methods are:
* max_price: Applies the discount to the item with the highest price
* min_price: Applies the discount to the item with the lowest price
* exclude: Excludes the selected items from the discount
* sum_of_amount (default): Applies the discount based on the total sum of the
selected items'' prices'
quantity:
type: integer
x-stoplight:
id: 03rrwhmo0xuff
description: 'Specifies how many units of a particular item will be selected or
filtered for processing. A value is required if the processing function is selected
as `min_price` or `max_price`. If you apply a filter on certain items and specify
the quantity, the system will process only the selected number of units for that
item. For example, if the quantity is set to 3, only 3 units of the item will
be included in the filter or discount. The quantity value must adhere to certain
rules:
* The value of quantity must be a whole number.
* The quantity cannot be negative.
* You must have at least 1 unit of the item.
* You can select up to 5 units of an item.'
line_item_selector:
$ref: '#/components/schemas/qc_line_item_selector'
enable_menu_item_aggregator:
type: boolean
x-stoplight:
id: vzeopj8obw0fz
description: Whether the system will combine (aggregate) multiple instances of the same
menu item into one entry based on the attributes defined in aggregator_grouping_attributes.
"Y", "YES", "1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other
values are considered false.
aggregator_grouping_attributes:
$ref: '#/components/schemas/aggregator_grouping_attributes'
item_qualifiers:
$ref: '#/components/schemas/item_qualifiers'
receipt_qualifier:
$ref: '#/components/schemas/receipt_qualifiers'
meta:
$ref: '#/components/schemas/meta'
receipt_qualifiers:
title: Receipt Qualifiers (Array Object)
x-stoplight:
id: p6nqib79s2g8r
type: array
description: Lists the receipt rules that are used to check for information that must (or must not
be) present on a guest's receipt in order to satisfy conditions for the qualification criteria
items:
x-stoplight:
id: kgjrbgyv7mz22
type: object
properties:
attribute:
type: string
x-stoplight:
id: ajdryi5buq4al
description: "Type of receipt attribute based on which the qualification criteria will be\
\ applied. The value of the attribute must be from the predefined list. The system will\
\ ignore the attribute value if it is not from the list. If the same attribute is provided\
\ multiple times, only the first one will be accepted. Possible values: total_amount, receipt_hour,\
\ receipt_week_day, receipt_day, subtotal_amount, receipt_month, receipt_year, revenue_code,\
\ revenue_id, employee_id, employee_name, receipt_week, receipt_minute, channel, and transaction_no.\
\ For more information on possible values, see the [Receipt Rules/Qualifiers]( https://support.punchh.com/s/article/Receipt-RulesQualifiers)\
\ article on the Support Portal. \n\nNote: To view the Punchh product documentation on the\
\ Punchh Support Portal, you must log in to a Punchh platform production environment. If\
\ you already have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On) to\
\ access the Punchh Support Portal."
operator:
type: string
x-stoplight:
id: rhkpkekle3d65
description: 'Defines the comparison logic that will be applied to the receipt attribute.
Possible values: ==, !=, >, <, >=, <=, in, is_case_insensitive, in_case_insensitive, not_in,
not_in_case_insensitive, like, not_like, in_range, not_in_range, mod, and in_special'
value:
type: string
x-stoplight:
id: qx6654qjwgumt
description: A specific value or set of values with which the receipt attribute will be compared
redeemable_recurrence_schedule:
title: Recurrence Schedule (Object)
x-stoplight:
id: oydu0pldcbie3
type: object
description: Specifies how many times this redeemable should be awarded to the guest, along with
the frequency
properties:
occurrences:
type: integer
x-stoplight:
id: w5kr0ilaghndd
description: The number of times the redeemable should be awarded to the guest, based on the
recurrence interval defined. For example, if set to 2, the guest will receive the reward twice,
once for each occurrence as defined by the schedule (e.g., once every 2 days).
days_distance:
type: integer
x-stoplight:
id: a6o1rjybs8wgz
description: Defines the number of days after which the redeemable will be repeated. For example,
if set to 2, the redeemable will be awarded again every 2 days. The recurrence days must be
between 1 and 395. The total duration for recurrences cannot be greater than 13 months. For
example, if the recurrence is set to 3 times every 90 days, the recurrence will be at Day
1, Day 90, and Day 180. However, if the recurrence is set to 6 times every 90 days, then recurrence
would be at Day 1, Day 90, Day 180, Day 270, Day 360, and Day 450. This setup would result
in an error message appearing in the platform as the total recurrence days are greater than
395 days.
redeemable_data_input:
title: Redeemable Input (Object)
x-stoplight:
id: py6v9pco9txg3
type: object
properties:
data:
type: array
x-stoplight:
id: nttkj2ju991hq
description: 'A list of redeemables that needs to be created '
items:
x-stoplight:
id: eoav6ju4ony0e
type: object
properties:
name:
type: string
x-stoplight:
id: dhp1ab2v5jqc8
description: Name of the redeemable
external_id:
type: string
x-stoplight:
id: on1fi68g1fhnl
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id` either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
alternate_locale_name:
$ref: '#/components/schemas/redeemable_alternate_locale_name'
alternate_locale_description:
$ref: '#/components/schemas/redeemable_alternate_locale_description'
description:
type: string
x-stoplight:
id: 9g7xc3m4c5ct5
description: Description of the redeemable
note:
type: string
x-stoplight:
id: 4kyfgwknzl2iq
description: An internal note provided by the business. This text is not visible in the
app and is solely for the business to use internally to store information for future
reference.
allow_for_support_gifting:
type: boolean
x-stoplight:
id: wwwiin82pahcl
description: 'Indicates whether the redeemable is available for support gifting. Admins
who have gifting permission will be able to gift this redeemable to guests for support
purposes. Possible values: true, false'
available_as_template:
type: boolean
x-stoplight:
id: ukmib5x5s8x7p
description: 'Indicates whether the redeemable is available for use as a template. If
set to true, the redeemable can be reused and customized for creating new redeemables.
Possible values: true, false'
distributable:
type: boolean
x-stoplight:
id: 1ywcatnlys4ne
description: Indicates whether the redeemable will be available only for guests who validate
their segments. This parameter is applicable when the business has enabled deals.
distributable_to_all_users:
type: boolean
x-stoplight:
id: cr976gvfywelx
description: Indicates whether the redeemable will be available to all loyalty guests.
This parameter is applicable when the business has enabled deals.
segment_definition_id:
type: integer
x-stoplight:
id: jg9uh12b3tf04
description: ID of the segment as defined in the Punchh system. A value in the "punchh-segment-id"
format is required in this parameter if `distributable` is set to true and `distributable_to_all_users`
is set to false. This parameter is applicable when the business has enabled deals.
auto_applicable:
type: boolean
x-stoplight:
id: cwsnod7d1u9io
description: Indicates whether the offer (gifted and not tied to points) can be automatically
redeemed without guest interaction. This is applicable for businesses with auto redemption
enabled and for discount types defined in the Auto-Application strategy.
receipt_rule:
type: object
x-stoplight:
id: e4go768zliuup
description: Set of rules or conditions that determine how and when an offer can be redeemed
required:
- qualifier_type
- redeeming_criterion
properties:
qualifier_type:
type: string
x-stoplight:
id: 8iwze6rf494wr
description: "Defines the criteria that apply to the processing of receipts, determining\
\ how the discount will be applied based on the items purchased. Possible values:\n\
* new: Specify new if you want to create new qualification criteria to process the\
\ offer. If you choose this option, use the parameters in the `redeeming_criterion`\
\ object to create a new qualification criteria.\n* existing: Specify existing if\
\ you're going to use an existing qualification criteria to process the offer. The\
\ UUID of the existing qualification criteria should be specified in the `redeeming_criterion_id`\
\ parameter. \n* flat_discount: Specify flat_discount to set a fixed discount for\
\ the offer regardless of the items or total amount on the receipt. For example,\
\ $50 off or 10% off. The discount value should be specified in the `discount_amount`\
\ parameter."
redeeming_criterion_id:
type: string
x-stoplight:
id: 2oumywxdun122
description: UUID of the qualification criteria you want to attach to the offer. The
QC UUID is provided in the `external_id` response parameter when you create qualification
criteria using the [Create Qualification Criteria](/docs/dev-portal-platform-functions/009524a9d88ae-create-qualification-criteria-qc)
API. A value is required for this parameter when `qualifier_type` is "existing".
discount_amount:
type: number
x-stoplight:
id: hsax2zubl1mvv
description: Fixed discount set for the offer that will be applied to the receipt
regardless of the items or total amount on the receipt (e.g., $50 off or 10% off).
A positive value is required for this parameter when `qualifier_type` is "discount".
format: float
redeeming_criterion:
$ref: '#/components/schemas/redeemable_redeeming_criterion'
activate_now:
type: boolean
x-stoplight:
id: jafcdzcpiczlx
description: 'Indicates whether the offer will be activated immediately. This applies
when the `distributable` parameter for the offer is set to true, and the business has
enabled deals. Possible values: true, false'
start_time:
type: string
x-stoplight:
id: 8rwolvqehscj6
format: date-time
description: Local date and time at which the offer starts
end_time:
type: string
x-stoplight:
id: 40mlgs55b1679
description: Local date and time at which the offer ends
indefinetely:
type: boolean
x-stoplight:
id: 57whtvdh9nhvj
description: 'Indicates whether the redeemable will be available indefinitely. If set
to true, the offer will not expire. If set to false, you can specify the expiry period
in the `expiry_days` parameter. Possible values: true, false'
expiry_days:
type: integer
x-stoplight:
id: orp6tb0zslwq3
description: Number of days before the reward expires. If the value of this parameter
is set to 5 and the reward is credited to a guest’s account before the day ends (i.e.,
11:59 PM), that day will be counted as the first day of reward availability. The reward
will then expire at 11:59 PM on the fifth day.
timezone:
type: string
x-stoplight:
id: lcqztohmx2jsh
description: 'Valid time zone in which the offer is applicable or active. Possible values:
Etc/GMT+12, Pacific/Pago_Pago, Pacific/Midway, Pacific/Honolulu, America/Juneau, America/Los_Angeles,
America/Tijuana, America/Phoenix, America/Mazatlan, America/Denver, America/Guatemala,
America/Chicago, America/Chihuahua, America/Mexico_City, America/Monterrey, America/Regina,
America/Bogota, America/New_York, America/Indiana/Indianapolis, America/Lima, America/Halifax,
America/Caracas, America/Guyana, America/La_Paz, America/Puerto_Rico, America/Santiago,
America/St_Johns, America/Sao_Paulo, America/Argentina/Buenos_Aires, America/Montevideo,
America/Godthab, Atlantic/South_Georgia, Atlantic/Azores, Atlantic/Cape_Verde, Europe/London,
Europe/Lisbon, Africa/Monrovia, Etc/UTC, Europe/Amsterdam, Europe/Belgrade, Europe/Berlin,
Europe/Zurich, Europe/Bratislava, Europe/Brussels, Europe/Budapest, Africa/Casablanca,
Europe/Copenhagen, Europe/Dublin, Europe/Ljubljana, Europe/Madrid, Europe/Paris, Europe/Prague,
Europe/Rome, Europe/Sarajevo, Europe/Skopje, Europe/Stockholm, Europe/Vienna, Europe/Warsaw,
Africa/Algiers, Europe/Zagreb, Europe/Athens, Europe/Bucharest, Africa/Cairo, Africa/Harare,
Europe/Helsinki, Asia/Jerusalem, Europe/Kaliningrad, Europe/Kiev, Africa/Johannesburg,
Europe/Riga, Europe/Sofia, Europe/Tallinn, Europe/Vilnius, Asia/Baghdad, Europe/Istanbul,
Asia/Kuwait, Europe/Minsk, Europe/Moscow, Africa/Nairobi, Asia/Riyadh, Europe/Volgograd,
Asia/Tehran, Asia/Muscat, Asia/Baku, Asia/Tbilisi, Asia/Yerevan, Asia/Kabul, Asia/Almaty,
Asia/Yekaterinburg, Asia/Karachi, Asia/Tashkent, Asia/Kolkata, Asia/Colombo, Asia/Kathmandu,
Asia/Dhaka, Asia/Urumqi, Asia/Rangoon, Asia/Bangkok, Asia/Jakarta, Asia/Krasnoyarsk,
Asia/Novosibirsk, Asia/Shanghai, Asia/Chongqing, Asia/Hong_Kong, Asia/Irkutsk, Asia/Kuala_Lumpur,
Australia/Perth, Asia/Singapore, Asia/Taipei, Asia/Ulaanbaatar, Asia/Tokyo, Asia/Seoul,
Asia/Yakutsk, Australia/Adelaide, Australia/Darwin, Australia/Brisbane, Australia/Melbourne,
Pacific/Guam, Australia/Hobart, Pacific/Port_Moresby, Australia/Sydney, Asia/Vladivostok,
Asia/Magadan, Pacific/Noumea, Pacific/Guadalcanal, Asia/Srednekolymsk, Pacific/Auckland,
Pacific/Fiji, Asia/Kamchatka, Pacific/Majuro, Pacific/Chatham, Pacific/Tongatapu, Pacific/Apia,
Pacific/Fakaofo'
remind_before:
type: integer
x-stoplight:
id: hflasli2nhjiu
description: Day(s) before the offer expires, as specified in expiry_days, when the system
sends a reminder if the offer has not been used
discount_channel:
type: string
x-stoplight:
id: crt1xpyf0hjdm
description: 'Channels where this redeemable can be discounted. The value of this parameter
is for informational purposes only and is not validated by Punchh. Third-party vendors
can use this information to show/hide the redeemable on their platform. Possible values:
all, online_only, offline_only. The default value is "all".'
default: all
points:
type: integer
x-stoplight:
id: rfr7tjv089bwv
description: Number of points required to redeem the offer
redemption_code_expiry_mins:
type: integer
x-stoplight:
id: n8sh4g00qgwn3
description: Number of minutes before the redemption code attached to this redeemable
expires
applicable_as_loyalty_redemption:
type: boolean
x-stoplight:
id: qypwkih83qkqg
description: 'Indicates whether this redeemable is available for redemption using loyalty
points. Possible values: true, false'
expire_redemption_code_with_reward_end_date:
type: boolean
x-stoplight:
id: i4ixpihm4qe4n
description: 'Indicates whether the redemption code expires on the reward''s end date.
Possible values: true, false'
template:
$ref: '#/components/schemas/redeemable_template'
lag_duration:
$ref: '#/components/schemas/redeemable_lag_duration'
recurrence_schedule:
$ref: '#/components/schemas/redeemable_recurrence_schedule'
effective_location:
type: string
x-stoplight:
id: 7puasc43k08ca
description: A valid or existing location ID or location group ID. The default value is
null. Restricts redemption to the specified location(s). If a specific location needs
to be specified, use the format "location:”. If a location group
needs to be selected, use the format "tag:”.
meta_data:
type: string
x-stoplight:
id: x7g87ozg95mqi
description: Custom information for the offer that the mobile app can use to implement
specific filtering logic
required:
- name
- external_id
- receipt_rule
required:
- data
redeemable_data_output:
title: Redeemable List Output (Object)
x-stoplight:
id: t61lenmp5uqwz
type: object
x-examples: []
properties:
meta:
$ref: '#/components/schemas/meta'
data:
type: array
x-stoplight:
id: ec1ri9dncp84y
description: A list of redeemables
items:
x-stoplight:
id: 2zahz3ebmckpk
type: object
properties:
name:
type: string
x-stoplight:
id: k09rslq64kf32
description: Name of the redeemable
image:
type: string
x-stoplight:
id: chogs4zmji0j3
description: URL of the image
description:
type: string
x-stoplight:
id: vcrhxc8st2hgv
description: Description of the redeemable
note:
type: string
x-stoplight:
id: kqhsgagwc27ix
description: An internal note provided by the business. This text is not visible in the
app and is solely for the business to use internally to store information for future
reference.
allow_for_support_gifting:
type: boolean
x-stoplight:
id: nvou63g2j70ap
description: 'Indicates whether the redeemable is available for support gifting. Admins
who have gifting permission will be able to gift this redeemable to guests for support
purposes. Possible values: true, false'
available_as_template:
type: boolean
x-stoplight:
id: qx4jry2idts7f
description: 'Indicates whether the redeemable is available for use as a template. If
set to true, the redeemable can be reused and customized for creating new redeemables.
Possible values: true, false'
auto_applicable:
type: boolean
x-stoplight:
id: jr50w0absakmc
description: Indicates whether the offer (gifted and not tied to points) can be automatically
redeemed without guest interaction. This is applicable for businesses with auto redemption
enabled and for discount types defined in the Auto-Application strategy.
start_time:
type: string
x-stoplight:
id: 6nlkrgf3jzoty
format: date-time
description: Local date and time at which the offer starts
end_time:
type: string
x-stoplight:
id: 71qhw0kdu5huc
format: date-time
description: Local date and time at which the offer ends
segment_definition_id:
type: integer
x-stoplight:
id: g6ddjjvmpv9c5
description: ID of the segment as defined in the Punchh system. A value in the "punchh-segment-id"
format is required in this parameter if `distributable` is set to true and `distributable_to_all_users`
is set to false. This parameter is applicable when the business has enabled deals.
timezone:
type: string
x-stoplight:
id: mfk6z9x9dwj7f
description: 'Valid time zone in which the offer is applicable or active. Possible values:
Etc/GMT+12, Pacific/Pago_Pago, Pacific/Midway, Pacific/Honolulu, America/Juneau, America/Los_Angeles,
America/Tijuana, America/Phoenix, America/Mazatlan, America/Denver, America/Guatemala,
America/Chicago, America/Chihuahua, America/Mexico_City, America/Monterrey, America/Regina,
America/Bogota, America/New_York, America/Indiana/Indianapolis, America/Lima, America/Halifax,
America/Caracas, America/Guyana, America/La_Paz, America/Puerto_Rico, America/Santiago,
America/St_Johns, America/Sao_Paulo, America/Argentina/Buenos_Aires, America/Montevideo,
America/Godthab, Atlantic/South_Georgia, Atlantic/Azores, Atlantic/Cape_Verde, Europe/London,
Europe/Lisbon, Africa/Monrovia, Etc/UTC, Europe/Amsterdam, Europe/Belgrade, Europe/Berlin,
Europe/Zurich, Europe/Bratislava, Europe/Brussels, Europe/Budapest, Africa/Casablanca,
Europe/Copenhagen, Europe/Dublin, Europe/Ljubljana, Europe/Madrid, Europe/Paris, Europe/Prague,
Europe/Rome, Europe/Sarajevo, Europe/Skopje, Europe/Stockholm, Europe/Vienna, Europe/Warsaw,
Africa/Algiers, Europe/Zagreb, Europe/Athens, Europe/Bucharest, Africa/Cairo, Africa/Harare,
Europe/Helsinki, Asia/Jerusalem, Europe/Kaliningrad, Europe/Kiev, Africa/Johannesburg,
Europe/Riga, Europe/Sofia, Europe/Tallinn, Europe/Vilnius, Asia/Baghdad, Europe/Istanbul,
Asia/Kuwait, Europe/Minsk, Europe/Moscow, Africa/Nairobi, Asia/Riyadh, Europe/Volgograd,
Asia/Tehran, Asia/Muscat, Asia/Baku, Asia/Tbilisi, Asia/Yerevan, Asia/Kabul, Asia/Almaty,
Asia/Yekaterinburg, Asia/Karachi, Asia/Tashkent, Asia/Kolkata, Asia/Colombo, Asia/Kathmandu,
Asia/Dhaka, Asia/Urumqi, Asia/Rangoon, Asia/Bangkok, Asia/Jakarta, Asia/Krasnoyarsk,
Asia/Novosibirsk, Asia/Shanghai, Asia/Chongqing, Asia/Hong_Kong, Asia/Irkutsk, Asia/Kuala_Lumpur,
Australia/Perth, Asia/Singapore, Asia/Taipei, Asia/Ulaanbaatar, Asia/Tokyo, Asia/Seoul,
Asia/Yakutsk, Australia/Adelaide, Australia/Darwin, Australia/Brisbane, Australia/Melbourne,
Pacific/Guam, Australia/Hobart, Pacific/Port_Moresby, Australia/Sydney, Asia/Vladivostok,
Asia/Magadan, Pacific/Noumea, Pacific/Guadalcanal, Asia/Srednekolymsk, Pacific/Auckland,
Pacific/Fiji, Asia/Kamchatka, Pacific/Majuro, Pacific/Chatham, Pacific/Tongatapu, Pacific/Apia,
Pacific/Fakaofo'
discount_channel:
type: string
x-stoplight:
id: llo3t40qg98e0
description: 'Channels where this redeemable can be discounted. The value in this parameter
is for informational purposes only and is not validated by Punchh. Third-party vendors
can use this information to show/hide the redeemable on their platform. Possible values:
all, online_only, offline_only. The default value is "all".'
default: all
points:
type: integer
x-stoplight:
id: 5q23fkoa22jfj
description: Number of points required to redeem the offer
activate_now:
type: boolean
x-stoplight:
id: zhl8p63egt1x5
description: 'Indicates whether the offer will be activated immediately. This applies
when the `distributable` parameter for the offer is set to true, and the business has
enabled deals. Possible values: true, false'
applicable_as_loyalty_redemption:
type: boolean
x-stoplight:
id: zf9q6cr9uqyk0
description: 'Indicates whether this redeemable is available for redemption using loyalty
points. Possible values: true, false'
indefinetely:
type: boolean
x-stoplight:
id: n4n1ab3b6kzph
description: 'Indicates whether the redeemable will be available indefinitely. If set
to true, the offer will not expire. If set to false, you can specify the expiry period
in the `expiry_days` parameter. Possible values: true, false'
expiry_days:
type: integer
x-stoplight:
id: 6n0gb7ay6p15l
description: Number of days before the reward expires. If the value of this parameter
is set to 5 and the reward is credited to a guest’s account before the day ends (i.e.,
11:59 PM), that day will be counted as the first day of reward availability. The reward
will then expire at 11:59 PM on the fifth day.
remind_before:
type: integer
x-stoplight:
id: qdznbozl10nwj
description: Day(s) before the offer expires, as specified in expiry_days, when the system
sends a reminder if the offer has not been used.
expire_redemption_code_with_reward_end_date:
type: boolean
x-stoplight:
id: rovf02mt1zj5x
description: 'Indicates whether the redemption code expires on the reward''''s end date.
Possible values: true, false'
template:
$ref: '#/components/schemas/redeemable_template'
effective_location:
type: string
x-stoplight:
id: pmeah3140682c
description: A valid or existing location ID or location group ID. The default value is
null. Restricts redemption to the specified location(s). The format for a specific location
is "location:”, and the format for location group is “tag:”.
lag_duration:
$ref: '#/components/schemas/redeemable_lag_duration'
recurrence_schedule:
$ref: '#/components/schemas/redeemable_recurrence_schedule'
meta_data:
type: string
x-stoplight:
id: c2tpx51woub1p
description: Custom information for the offer that the mobile app can use to implement
specific filtering logic
distributable:
type: boolean
x-stoplight:
id: jth26495gqaar
description: Indicates whether the redeemable will be available only for guests who validate
their segments. This parameter is applicable when the business has enabled deals.
alternate_locale_name:
$ref: '#/components/schemas/redeemable_alternate_locale_name'
alternate_locale_description:
$ref: '#/components/schemas/redeemable_alternate_locale_description'
external_id:
type: string
x-stoplight:
id: zk4dmw9x196u9
description: 'A unique identifier (UUID) sent by the external system to track whether
a particular entity is successfully created in the Punchh system. It serves as a primary
key for the external system. If no `external_id` is provided, the Punchh system will
automatically generate a default `external_id` either as a 40-character hexadecimal
string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
redemption_code_expiry_mins:
type: integer
x-stoplight:
id: rkzhm73mydzlr
description: Number of minutes before the redemption code attached to this redeemable
expires
distributable_to_all_users:
type: boolean
x-stoplight:
id: lj520d2orzp9p
description: Indicates whether the redeemable will be available to all loyalty guests.
This parameter is applicable when the business has enabled deals.
receipt_rule:
x-stoplight:
id: p9577xjpz6ive
type: object
description: Set of rules or conditions that determine how and when an offer can be redeemed
properties:
qualifier_type:
type: string
x-stoplight:
id: jthruki0vsy3s
description: 'Defines the criteria that apply to the processing of receipts, determining
how the discount will be applied based on the items purchased. Possible values:
* new: Indicates new qualification criteria are created for the offer to process
the offer. If this option is chosen, the parameters in the `redeeming_criterion`
object define the details of the new qualification criteria.
* existing: Indicates existing qualification criteria are used to process the offer.
The UUID of the chosen existing qualification criteria is specified in `redeeming_criterion_id`.
* flat_discount: Indicates a fixed discount is set for the offer that will be applied
to the receipt regardless of the items or total amount on the receipt (e.g., $50
off or 10% off). The discount value is specified in the ''discount_amount'' parameter.'
redeeming_criterion_id:
type: string
x-stoplight:
id: rk6kqlpblc5hr
description: UUID of the qualification criteria you want to attach to the offer. The
QC UUID is provided in the `external_id` response parameter when you create qualification
criteria using [Create Qualification Criteria](/docs/dev-portal-platform-functions/009524a9d88ae-create-qualification-criteria-qc)
API. A value is required for this parameter, when `qualifier_type is set to "existing".
discount_amount:
type: number
x-stoplight:
id: opdtza7f8b6bw
format: float
description: Fixed discount set for the offer that will be applied to the receipt
regardless of the items or total amount on the receipt (e.g., $50 off or 10% off).
A value is required for this parameter when `qualifier_type is "discount".
redeeming_criterion:
type: object
x-stoplight:
id: 3k6d07x56igzg
description: This object contains information about the qualification criteria attached
to the redeemable.
properties:
name:
type: string
x-stoplight:
id: spjdlvk92siax
description: Name of the qualification criteria (QC)
minLength: 0
maxLength: 255
external_id:
type: string
x-stoplight:
id: fk8q4my62v8r9
description: 'A unique identifier (UUID) sent by the external system to track
whether a particular entity is successfully created in the Punchh system. It
serves as a primary key for the external system. If no `external_id` is provided,
the Punchh system will automatically generate a default `external_id` either
as a 40-character hexadecimal string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
amount_cap:
type: number
x-stoplight:
id: 15xm7hatk1rkl
description: Maximum amount that can be earned/redeemed on any receipt
format: float
percentage_of_processed_amount:
type: number
x-stoplight:
id: zqmx32ncsz8de
format: float
description: Percentage of processed amount that can be earned/redeemed on any
receipt
qc_processing_function:
type: string
x-stoplight:
id: kq1ob5yx3e0g3
description: "Function applied on filtered menu items of the receipt. Processing\
\ functions return a processed value that governs discounting and earning depending\
\ on where the qualification criterion is attached. If it is applied in a discounting\
\ scenario, the processed value controls the discount amount. If it is applied\
\ in an earning scenario (e.g., a rewards program), the processed value controls\
\ how much is earned (such as reward points). \n\nPossible values: hit_target_price,\
\ rate_rollback, bundle_price_target, bundle_price_target_advanced, hit_target_price_max_price_once,\
\ hit_target_price_min_price_once, sum_amounts_incremental, static_amount, receipt_subtotal,\
\ bogof, bogof2, sum_amounts, receipt_total_amount, sum_qty\n\nFor more information\
\ on possible values, see the [Processing Functions]( https://support.punchh.com/s/article/Processing-Functions)\
\ article on the Punchh Support Portal.\n\nNote: To view the Punchh product\
\ documentation on the Punchh Support Portal, you must log in to a Punchh platform\
\ production environment. If you already have access to a production environment,\
\ follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
rounding_rule:
type: string
x-stoplight:
id: 7i4vuebgksdok
description: "If the processing function returns a float value, it will be rounded\
\ according to the chosen rounding rule. If no rule is selected, the float value\
\ will be used as is. A value is required to be sent in the parameter depending\
\ on the processing function selected. Possible values: \n* round: This rule\
\ rounds the float value to the nearest integer. If the decimal part is 0.5\
\ or higher, the value is rounded up. If the decimal part is less than 0.5,\
\ the value is rounded down. For example, 4.3 becomes 4, and 4.7 becomes 5.\n\
* ceil: This rule rounds the float value up to the next highest integer, regardless\
\ of the decimal part. For example, 4.3 becomes 5.\n* floor: This rule rounds\
\ the float value down to the next lowest integer, regardless of the decimal\
\ part. For example, 4.3 becomes 4."
max_discount_units:
type: integer
x-stoplight:
id: p8uikbdbo6vze
description: This value limits the number of units that can be discounted. It
works only with specific `qc_processing_function` types, such as rate_rollback,
bundle_price_target, bundle_price_target_advanced, and sum_amounts_incremental.
unit_discount:
type: integer
x-stoplight:
id: lrq73jo6zoaop
description: Discount to be applied to the rate of the selected items chosen for
the offer or promotion. The discount is based on a specific rate (e.g., per
unit of item - per gallon, per liter, etc.). For example, for a fuel discount
of 20 cents per gallon, you need to specify the discount in a decimal format
(i.e, 0.2) to reflect a 20-cent reduction for each gallon of fuel. If the qualification
criteria are attached to a subscription plan, the value of the unit discount
will be picked up from the subscription plan, and even though you are required
to enter a value for the discount (e.g., 0.2 for 20 cents), this value will
be ignored if the qualification criteria are part of a subscription plan,
because the discount will be controlled by the subscription plan's settings
instead. The value should be greater than or equal to 0.01 and less than or
equal to 99999 if the processing method (`qc_processing_function`) is rate_rollback.
A value is required to be sent in the parameter depending on the processing
function selected.
minimum_unit_rate:
type: number
x-stoplight:
id: 4wimxxwag80dw
description: Minimum unit price threshold. After applying the discount, the minimum
unit rate should not be below this amount.
target_price:
type:
- number
x-stoplight:
id: 3rtevu2q3ylki
description: Discount selected menu items to achieve this target unit price. For
example, if locations sell a burger for variable pricing, a target unit price
is achieved by using the appropriate processing function, and this target price
works only with a specific `qc_processing_function`. If a burger is sold at
different prices at different locations (e.g., one location sells it for $10,
another for $12), you can set a target price (e.g., $9) to standardize the price
across locations. The system applies discounts to bring the price down to $9,
no matter what the original price was.
effective_location:
type: string
x-stoplight:
id: 7xsva58swiaut
description: A valid or existing location ID or location group ID. The default
value is null. Restricts redemption to the specified location(s). The format
for a specific location is "location:”, and the format for
location group is “tag:”.
stack_discounting:
type: boolean
x-stoplight:
id: 2c67ao7rf5gl3
description: When stacking is set to true, this discount can be redeemed with
any other discount that contains the same target item. If set to false, only
one discount can be applied to the target item, even if multiple discounts are
available. "Y", "YES", "1", "TRUE", and "ON" (case-insensitive) are treated
as true. Any other values are considered false.
reuse_qualifying_items:
type: boolean
x-stoplight:
id: gslykziz7j2ek
description: When set to true, it allows qualifying item(s) to be reused when
redeemed with other discounts that apply to the same item(s). When set to false,
it restricts qualifying item(s) from being reused for multiple discounts. "Y",
"YES", "1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other
values are considered false.
line_item_filters:
type: array
x-stoplight:
id: fjr4qdtlhkzif
items:
x-stoplight:
id: xeaqvfhrvdvwv
type: object
properties:
quantity:
type: string
x-stoplight:
id: f2wsbfyqwy87d
description: 'Specifies how many units of a particular item will be selected
or filtered for processing. A value is required if the processing function
is selected as `min_price` or `max_price`. If you apply a filter on certain
items and specify the quantity, the system will only process the selected
number of units for that item. For example, if the quantity is set to
3, only 3 units of the item will be included in the filter or discount.
The quantity value must adhere to certain rules:
* The value of quantity must be a whole number.
* The quantity cannot be negative.
* You must have at least 1 unit of the item.
* You can select up to 5 units of an item.'
processing_method:
type: string
x-stoplight:
id: eevuqhgpqy5uu
description: 'The processing method for a line item filter determines how
the selected items are handled when applying a discount. The system will
skip the line item filter if the value of processing_method is invalid.
The available processing methods are:
* max_price: Applies the discount to the item with the highest price.
* min_price: Applies the discount to the item with the lowest price.
* exclude: Excludes the selected items from the discount.
* sum_of_amount (default): Applies the discount based on the total sum
of the selected items'' prices.'
line_item_selector:
$ref: '#/components/schemas/qc_line_item_selector'
item_qualifiers:
$ref: '#/components/schemas/item_qualifiers'
receipt_qualifiers:
$ref: '#/components/schemas/receipt_qualifiers'
enable_menu_item_aggregator:
type: boolean
x-stoplight:
id: vqrfqgzg4ze4i
description: Whether the system will combine (aggregate) multiple instances of
the same menu item into one entry based on the attributes defined in `aggregator_grouping_attributes`.
"Y", "YES", "1", "TRUE", and "ON" (case-insensitive) are treated as true. Any
other values are considered false.
aggregator_grouping_attributes:
$ref: '#/components/schemas/aggregator_grouping_attributes'
required:
- timezone
redeemable_results:
title: Redeemable - Results (Array Object)
x-stoplight:
id: cqx3e81tlhtjw
type: object
properties:
results:
type: array
x-stoplight:
id: 58e86waoolby5
description: List of responses indicating if the entity is created or not
items:
x-stoplight:
id: 18861zl3h5rt8
type: object
properties:
external_id:
type: string
x-stoplight:
id: jit72m5gic8m4
description: Unique ID (UUID) sent by the external system to track if a particular entity
is successfully updated in the Punchh system
success:
type: boolean
x-stoplight:
id: ymigj11x9qy4s
description: 'Status of a specific entity created in the system. Possible values: true,
false'
errors:
type: array
x-stoplight:
id: qdlanb08obe11
description: A list of error messages explaining why a specific entity is not created
in the system
items:
x-stoplight:
id: 40tjnhdcesv8p
type: string
warnings:
type: object
x-stoplight:
id: 8o6vsbyxhopnh
description: A list of warning messages indicating potential issues found when the redeemable
is created or updated. These warnings do not prevent the redeemable from being created
or updated but may require attention. These warnings were ignored as they did not trigger
any validation errors.
properties:
receipt_rule:
type: object
x-stoplight:
id: wuedblap730vk
description: List of warnings generated due to validation errors for `receipt_rule`
properties:
redeeming_criterion:
type: object
x-stoplight:
id: 5k4bgay4a2tbc
description: List of warnings generated due to validation errors for `redeeming_criterion`
properties:
line_item_filters:
$ref: '#/components/schemas/warnings_line_item_filters'
item_qualifiers:
$ref: '#/components/schemas/warnings_item_qualifiers'
receipt_qualifiers:
$ref: '#/components/schemas/warnings_receipt_qualifiers'
qualifying_expressions_operator:
$ref: '#/components/schemas/warnings_qualifying_expressions_operator'
item_filter_expressions_operator:
$ref: '#/components/schemas/warnings_item_filter_expressions_operator'
discount_evaluation_strategy:
$ref: '#/components/schemas/warnings_discount_evaluation_strategy'
redeemable_redeeming_criterion:
title: Redeeming Criterion (Object)
x-stoplight:
id: jojsfkft1uil5
type: object
description: This object contains information about the qualification criteria that will be created
and attached to the redeemable. It is required when `qualifier_type` is set to "new".
properties:
name:
type: string
x-stoplight:
id: wkwstergomqnr
description: Name of qualification criteria (QC). The name can be up to 255 characters long.
minLength: 0
maxLength: 225
external_id:
type: string
x-stoplight:
id: 90qxonbnlop6s
description: 'A unique identifier (UUID) sent by the external system to track whether a particular
entity is successfully created in the Punchh system. It serves as a primary key for the external
system. If no `external_id` is provided, the Punchh system will automatically generate a default
`external_id` either as a 40-character hexadecimal string or as a 36-character UUID. For example:
* Alphanumeric hexadecimal with length 40: 875a6a33ed0f2410d8ac671c2d07c9351ca2f88e'
amount_cap:
type: number
x-stoplight:
id: oxwadpyrf764i
description: Maximum amount that can be earned/redeemed on any receipt. The value should be
greater than or equal to 0 and less than or equal to 99999 if provided.
format: float
minimum: 0
maximum: 99999
percentage_of_processed_amount:
type: number
x-stoplight:
id: xwie3xvrgdw2q
format: float
description: Percentage of processed amount that can be earned/redeemed on any receipt. The
value should be greater than or equal to 0 and less than or equal to 99999 if provided.
minimum: 0
maximum: 99999
qc_processing_function:
type: string
x-stoplight:
id: w7xhz6u0ksna8
description: "Function applied on filtered menu items of the receipt. Processing functions return\
\ a processed value that governs discounting and earning depending on where the qualification\
\ criterion are attached. If it is applied in a discounting scenario, the processed value\
\ controls the discount amount. If it is applied in an earning scenario (e.g., a rewards program),\
\ the processed value controls how much is earned (such as reward points). \n\nPossible values:\
\ hit_target_price, rate_rollback, bundle_price_target, bundle_price_target_advanced, hit_target_price_max_price_once,\
\ hit_target_price_min_price_once, sum_amounts_incremental, static_amount, receipt_subtotal,\
\ bogof, bogof2, sum_amounts, receipt_total_amount, sum_qty\n\nFor more information on possible\
\ values, see the [Processing Functions](https://support.punchh.com/s/article/Processing-Functions)\
\ article on the Punchh Support Portal.\n\nNote: To view the Punchh product documentation\
\ on the Punchh Support Portal, you must log in to a Punchh platform production environment.\
\ If you already have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On)\
\ to access the Punchh Support Portal."
rounding_rule:
type: string
x-stoplight:
id: zoqkuij01oaud
description: "If the processing function returns a float value, it will be rounded according\
\ to the chosen rounding rule. If no rule is selected, the float value will be used as is.\
\ A value is required to be sent in the parameter depending on the processing function selected.\
\ Possible values: \n* round: This rule rounds the float value to the nearest integer. If\
\ the decimal part is 0.5 or higher, the value is rounded up. If the decimal part is less\
\ than 0.5, the value is rounded down. For example, 4.3 becomes 4, and 4.7 becomes 5.\n* ceil:\
\ This rule rounds the float value up to the next highest integer, regardless of the decimal\
\ part. For example, 4.3 becomes 5.\n* floor: This rule rounds the float value down to the\
\ next lowest integer, regardless of the decimal part. For example, 4.3 becomes 4."
max_discount_units:
type: integer
x-stoplight:
id: kn49zs35liiog
description: This value limits the number of units that can be discounted. A value is required
to be sent in the parameter depending on the processing function (`qc_processing_function`)
types selected, such as rate_rollback, bundle_price_target, bundle_price_target_advanced,
and sum_amounts_incremental.
minimum: 1
unit_discount:
type: number
x-stoplight:
id: k2cfku19gv7ee
description: Discount to be applied to the rate of the selected items chosen for the offer or
promotion. The discount is based on a specific rate (e.g., per unit of item - per gallon,
per liter, etc.). For example, for a fuel discount of 20 cents per gallon, you need to specify
the discount in a decimal format (0.2) to reflect a 20-cent reduction for each gallon of fuel.
If the qualification criteria are attached to a subscription plan, the value of the unit discount
will be picked up from the subscription plan, and even though you are required to enter a
value for the discount (e.g., 0.2 for 20 cents), this value will be ignored if the
qualification criteria are part of a subscription plan, because the discount will be controlled
by the subscription plan's settings instead. The value should be greater than or equal to
0.01 and less than or equal to 99999 if the processing method (`qc_processing_function`) is
rate_rollback. A value is required to be sent in the parameter depending on the processing
function selected.
format: float
maximum: 99999
minimum: 0.01
minimum_unit_rate:
type: number
x-stoplight:
id: p5an5geaz0kka
description: Minimum unit price threshold. After applying the discount, the minimum unit rate
should not be below this amount. A value greater than or equal to 0.01 and less than or equal
to 99999 is required if the processing method (`qc_processing_function`) is rate_rollback.
minimum: 0.01
maximum: 99999
target_price:
type: integer
x-stoplight:
id: 96n35s1vh5b88
description: Discount selected menu items to achieve this target unit price. For example, if
locations sell a burger for variable pricing, a target unit price is achieved by using the
appropriate processing function. If a burger is sold at different prices at different locations
(e.g., one location sells it for $10, another for $12), you can set a target price (e.g.,
$9) to standardize the price across locations. The system applies discounts to bring the price
down to $9, no matter what the original price was. A value is required to be sent in the parameter
depending on the processing function (`qc_processing_function`) types selected, such as hit_target_price,
hit_target_price_max_price_once, hit_target_price_min_price_once, bundle_price_target, and
bundle_price_target_advanced.
effective_location:
type: string
x-stoplight:
id: 0shnef5xs778r
description: A valid or existing location ID or location group ID. The default value is null.
Restricts redemption to the specified location(s). If a specific location needs to be specified,
use the format "location:”. If a location group needs to be selected,
use the format "tag:”.
stack_discounting:
type: boolean
x-stoplight:
id: vgcyndom3xq2v
description: When stacking is set to true, this discount can be redeemed with any other discount
that contains the same target item. If set to false, only one discount can be applied to the
target item, even if multiple discounts are available. "Y", "YES", "1", "TRUE", and "ON" (case-insensitive)
are treated as true. Any other values are considered false.
reuse_qualifying_items:
type: boolean
x-stoplight:
id: nlw6bw79udofe
description: When set to true, it allows qualifying item(s) to be reused when redeemed with
other discounts that apply to the same item(s). When set to false, it restricts qualifying
item(s) from being reused for multiple discounts. "Y", "YES", "1", "TRUE", and "ON" (case-insensitive)
are treated as true. Any other values are considered false.
qualifying_expressions_operator:
type: string
x-stoplight:
id: zhl3mem3g88kn
description: 'Specifies how offer conditions in `item_qualifiers` are evaluated. Possible values:
All, Any. The default value is "All". Use "All" when every condition must be met, or "Any"
when satisfying at least one condition is sufficient.'
item_filter_expressions_operator:
type: string
x-stoplight:
id: 55psu44tsnb6d
description: 'Specifies how offer conditions in `line_item_filters` are evaluated. Possible
values: All, Any. The default value is "All". Use "All" when every condition must be met,
or "Any" when satisfying at least one condition is sufficient.'
discount_evaluation_strategy:
type: string
x-stoplight:
id: 4bp3rh2ao6mbu
description: 'Specifies whether the maximum or minimum discount should be applied when multiple
conditions are met. Note: This parameter should be provided when `item_filter_expressions_operator`
is set to Any. Possible values: Min, Max. The default value is "Min".'
line_item_filters:
$ref: '#/components/schemas/qc_line_item_filters_input'
enable_menu_item_aggregator:
type: boolean
x-stoplight:
id: a0i7wql9fvp37
description: Whether the system will combine (aggregate) multiple instances of the same menu
item into one entry based on the attributes defined in `aggregator_grouping_attributes`. "Y",
"YES", "1", "TRUE", and "ON" (case-insensitive) are treated as true. Any other values are
considered false.
aggregator_grouping_attributes:
$ref: '#/components/schemas/aggregator_grouping_attributes'
item_qualifiers:
$ref: '#/components/schemas/qc_item_qualifiers_input'
receipt_qualifiers:
$ref: '#/components/schemas/receipt_qualifiers'
required:
- external_id
redeemable_template:
title: Template (Object)
x-stoplight:
id: 2jo6kgp0r4h25
type: object
properties:
redemption_message:
type: string
x-stoplight:
id: wp8fepiom8yf8
description: Message displayed on the redemption screen of the mobile app during the redemption
process. You can use the variables {{points_requested}} and {{redeemed_points}} to customize
this message as appropriate.
short_prompt:
type: string
x-stoplight:
id: b5vw6z1pcxd5a
description: Prompt message displayed on the Point of Sale and Pin Pad
standard_prompt:
type: string
x-stoplight:
id: lkvmx53k4etc5
description: Prompt message displayed on the Point of Sale and Pin Pad
description: This object contains customizable messaging for the redemption process.
warnings_discount_evaluation_strategy:
title: Warnings - Discount Evaluation Strategy (Array Object)
x-stoplight:
id: cw9x4kb1t2rsw
type: array
description: List of warnings related to the discount evaluation strategy
items:
x-stoplight:
id: es09kivua8ffs
type: object
properties:
message:
type: string
x-stoplight:
id: shddtjgxfzk5d
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: 3vzzta7f0u3u9
description: JSON object of the discount evaluation strategy that has an invalid value
properties:
discount_evaluation_strategy:
type: string
x-stoplight:
id: gttlkb8m5sv2g
description: 'Specifies whether the maximum or minimum discount should be applied when
multiple conditions are met. Note: This parameter should be provided when `item_filter_expressions_operator`
is set to Any. Possible values: Min, Max. The default value is "Min".'
warnings_item_filter_expressions_operator:
title: Warnings - Item Filter Expressions Operator (Array Object)
x-stoplight:
id: yboa4dzz4zwwx
type: array
description: List of warnings related to the item filter expressions operator
items:
x-stoplight:
id: z7da52sc6day4
type: object
properties:
message:
type: string
x-stoplight:
id: fdbmai3wyg5a4
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: 1h1f7e0htqwef
description: JSON object of the item filter expressions operator that has an invalid value
properties:
item_filter_expressions_operator:
type: string
x-stoplight:
id: verq4j6bmlfce
description: 'Specifies how offer conditions in `line_item_filters` are evaluated. Possible
values: All, Any. The default value is "All". Use "All" when every condition must be
met, or "Any" when satisfying at least one condition is sufficient.'
warnings_item_qualifiers:
title: Warnings - Item Qualifiers (Array Object)
x-stoplight:
id: 1l036ixwc3kkb
type: array
description: List of warnings related to item qualifiers
items:
x-stoplight:
id: e350cl8t85hfc
type: object
properties:
message:
type: string
x-stoplight:
id: b4xk87lcpy0f6
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: xk16l9792qiqv
properties:
line_item_selector_id:
type: string
x-stoplight:
id: rfijp22soxu40
description: ID of the pre-existing LIS, which for now will be the external_id
expression_type:
type: string
x-stoplight:
id: zp2kexvlli7av
description: Defines the condition or rule for qualifying items that need to be met to
trigger the processing function
net_value:
type: number
x-stoplight:
id: aw8xizdh1j3kt
description: Net value required for a specific condition
warnings_line_item_filters:
title: Warnings - Line Item Filters (Array Object)
x-stoplight:
id: xtccj22akwl3d
type: array
description: List of warnings related to line item filters
items:
x-stoplight:
id: pvh3ahc3ffmsm
type: object
properties:
message:
type: string
x-stoplight:
id: 64x45466phzz9
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: 6u3ldwbcdrh1f
description: JSON object of the line item filter that has an invalid value
properties:
line_item_selector_id:
type: string
x-stoplight:
id: v4mqlb4fqiqb5
description: ID of the pre-existing LIS, which for now will be the external_id
' processing_method':
type: string
x-stoplight:
id: k9tdakd16b10j
description: Value specifies the processing method for a line item filter that determines
how the selected items are handled when applying a discount
quantity:
type: integer
x-stoplight:
id: vgavup5ggwk8a
description: Value specifies how many units of a particular item will be selected or filtered
for processing
warnings_qualifying_expressions_operator:
title: Warnings - Qualifying Expressions Operator (Array Object)
x-stoplight:
id: 3ljmwtshkqmk7
type: array
description: List of warnings related to the qualifying expressions operator
items:
x-stoplight:
id: 25o8ztibsnzfd
type: object
properties:
message:
type: string
x-stoplight:
id: 0lmd3fmqr0zzk
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: jxv6406yfbxoo
description: JSON object of the qualifying expressions operator that has an invalid value
properties:
qualifying_expressions_operator:
type: string
x-stoplight:
id: j199rtlrmgpd8
description: 'Specifies how offer conditions in `item_qualifiers` are evaluated. Possible
values: All, Any. The default value is "All". Use "All" when every condition must be
met, or "Any" when satisfying at least one condition is sufficient.'
warnings_receipt_qualifiers:
title: Warnings - Receipt Qualifiers (Array Object)
x-stoplight:
id: ey82eiewiquxo
type: array
description: List of warnings related to receipt qualifiers
items:
x-stoplight:
id: 52865xkd7ugsm
type: object
properties:
message:
type: string
x-stoplight:
id: gi83amfnudpd4
description: Warning message that describes the cause of the error and identifies the parameter
containing the invalid value
item:
type: object
x-stoplight:
id: kw214q2xp55rg
description: JSON object of the receipt qualifier that has an invalid value
properties:
attribute:
type: string
x-stoplight:
id: rwcwk5sy1f4mi
description: Type of receipt attribute based on which the qualification criteria will
be applied
operator:
type: string
x-stoplight:
id: vl0rjqzb221gl
description: Defines the comparison logic that will be applied to the receipt attribute
value:
type: string
x-stoplight:
id: hst0h0xzq62pd
description: A specific value or set of values with which the receipt attribute will be
compared
parameters:
Accept:
schema:
type: string
name: Accept
in: header
required: false
description: Set this header to application/json
Authorization:
schema:
type: string
default: Bearer BUSINESS_ADMIN_KEY_GOES_HERE
name: Authorization
in: header
required: true
description: 'Bearer token for admin authorization, who is making a call on behalf of the customer.
Send the API key in the following format: "Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE".'
Content-Type:
schema:
type: string
name: Content-Type
in: header
required: false
description: Set this header to application/json
responses:
'400':
description: Bad Request - Required parameter missing or empty
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: xtdcx8losb5tq
examples:
Required parameter missing or empty:
value:
error: 'Required parameter missing or the value is empty: data'
'401':
description: Unauthorized - User not authenticated or created
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: rnkpi6hfoveqy
examples:
User not authenticated or created:
value:
error: You need to sign in or sign up before continuing.
'403':
description: Forbidden - Functionality not available
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-stoplight:
id: un1ov0n2c1o1w
examples:
Functionality not available:
value:
error: Sorry, this functionality is not available. Please contact support@punchh.com to
enable this.
securitySchemes: {}
x-ext-urls: {}