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\
<!--Cockpit > Dashboard > Miscellaneous Config > Enable Offers Ingestion-->\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<!--Cockpit > Dashboard > Miscellaneous Config\
\ > Enable Offers Ingestion-->\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\
<!--Cockpit > Dashboard > Miscellaneous Config > Enable Offers Ingestion-->\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\
<!--Cockpit > Dashboard > Miscellaneous Config > Enable Offers Ingestion-->\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'
- $re
# --- truncated at 32 KB (255 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-platform-functions-offers-ingestion-openapi.yml