Redeeming Criterion (Object)

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

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.

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.

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".

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:<punchh_location_id>”. If a location group needs to be selected, use the format "tag:<location_group_id>”.

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.

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.

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.

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.

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 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.

Name of qualification criteria (QC). The name can be up to 255 characters long.

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.

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).

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 article on the Punchh 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 to access the Punchh Support Portal.

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.

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

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.

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:

• 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.
• ceil: This rule rounds the float value up to the next highest integer, regardless of the decimal part. For example, 4.3 becomes 5.
• floor: This rule rounds the float value down to the next lowest integer, regardless of the decimal part. For example, 4.3 becomes 4.

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.

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.

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.