Batch Redemption Process (Redemptions 2.0)

​

Evaluates the validity of all inputs and commits the redemption.

Punchh evaluates eligibility during the Possible Redemptions call using the receipt details provided (item name, price, quantity, identifiers, etc.). During the Batch Redemption Process call, Punchh revalidates the same receipt to ensure the qualifying conditions are still met before honoring the redemption.

If any item attributes change between the two calls, Punchh may be unable to match the qualifying items, which can cause the Batch Redemption Process call to fail or return a different result—even if the Possible Redemptions call was successful.

NOTE: When processing a redemption, DO NOT include the query parameter in the API request. Use this parameter only to check for possible redemptions.

Additional behavior:

  • For orders placed for a future date, the guest’s loyalty account balance is evaluated on the order commit date (sysdate), not on the scheduled pickup or delivery date.
  • Locks the user's discount basket using a unique identifier external_uid generated by your application for the transaction when reward locking is enabled in the Punchh platform for the business. Locking the discount basket prevents other channels from creating simultaneous transactions or modifying the discount basket. See Discount Basket Locking Developer Guide. You must log in to the developer portal to access the developer guide.

When the Batch Redemption Process API commits the redemption, one of the following actions may occur based on the discount type:

  • Loyalty points are deducted from the guest account when discount_type = "redeemable" or "card_completion"
  • The reward is debited from the guest account when discount_type = "reward"
  • Banked rewards / currency are deducted from the guest’s loyalty account when discount_type = "discount_amount"
Headers
  • x-pch-digest
    Type: string
    required

    The signature for the API call

  • Content-Type
    Type: string
    required

    Set this header to application/json.

  • Accept
    Type: string
    required

    Advertises which content types the client is able to understand

  • User-Agent
    Type: string
    required

    For details, see User Agent.

  • Authorization
    Type: string
    required

    You may pass the access_token instead of the authentication_token in Online Ordering endpoints to authorize the request. It must be supplied as Bearer ACCESS_TOKEN_GOES_HERE.

  • Accept-Language
    Type: string

    Preferred language. Punchh supports multiple languages for the redeemable name, redeemable description, meta data for coupon, subscription plan name, and subscription description in the API response as per the locale specified in the Accept-Language request header. Possible values: es for Spanish, fr for French, fr-ca for French-Canada, en-CY for English-Cyprus, ro for Romania, es-US for Spanish United States, etc.
    The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address > Alternate Languages. In the Punchh platform, the admin of a business has to configure in the relevant language(s) 1) the redeemable name and redeemable description when creating/editing a redeemable under Offers > All Redeemables, 2) meta data for coupons when creating/editing a coupon campaign under Campaign Management, and 3) subscription plan name and subscription description when creating/editing a subscription plan under Wallet and Passes > Subscription Plans.

Body
application/json
  • client
    Type: string
    required

    Client key of the business

  • line_items
    Type: array object[] · Line Items (Array Object)
    required

    List of line items

  • receipt_amount
    Type: numberFormat: float
    required

    Order amount before taxes, calculated as the sum of all item amounts minus any discounts. This is the amount used to calculate loyalty points/visits. The value of this parameter should match subtotal_amount. For example, if the order amount is $10, both receipt_amount and subtotal_amount will be 10. If a $2 discount is applied, both will be 8.

  • receipt_datetime
    Type: stringFormat: date-time
    required

    Timestamp of receipt per ISO 8601 format, including TZ offset from UTC (YYYY-MM-DDThh:mm:ss-±hh:mm)

  • store_number
    Type: integer
    required

    Unique identifier for store location

  • subtotal_amount
    Type: numberFormat: float
    required

    Order amount before taxes (sum of all item amounts minus any discounts). Same as receipt_amount. For historical reasons, include this parameter along with receipt_amount in the API request.

  • external_uid
    Type: string

    Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is required when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.

  • query
    Type: boolean

    Include this parameter only if you want to make a possible redemptions call. The parameter value must be true. If you want to process a redemption, do not include this parameter in the request.

  • transaction_no
    Type: string

    Transaction number

Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/auth/batch_redemptions
curl https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/batch_redemptions \
  --request POST \
  --header 'x-pch-digest: SIGNATURE_GOES_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
  --header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
  --data '{
  "query": true,
  "store_number": 900,
  "client": "CLIENT_GOES_HERE",
  "line_items": [
    {
      "item_name": "coffee",
      "item_qty": 1,
      "amount": 10,
      "item_type": "M",
      "item_id": 330,
      "item_family": "10",
      "item_group": "gp",
      "serial_number": 1
    },
    {
      "item_name": "pizza",
      "item_qty": 1,
      "amount": 20,
      "item_type": "M",
      "item_id": 331,
      "item_family": "10",
      "item_group": "gp",
      "serial_number": 2
    }
  ],
  "receipt_datetime": "2019-04-11T14:14:07+05:30",
  "subtotal_amount": 100,
  "receipt_amount": 100,
  "transaction_no": "11111111111",
  "external_uid": "EXTERNAL_UID_GOES_HERE"
}'

{
  "redemption_ref": "REDEMPTION_REF_GOES_HERE",
  "success": [],
  "failures": [
    {
      "discount_basket_item_id": 1,
      "discount_amount": null,
      "redemption_id": null,
      "redemption_type": null,
      "discount_type": "reward",
      "discount_id": "367778",
      "discount_value": null,
      "message": [
        "Discount qualification on receipt failed for Shubham Gupta at Airway."
      ],
      "qualified": false,
      "remaining_balance": null,
      "meta_data": null,
      "qualifying_conditions": {
        "name": "LIS QC 21 july 2025",
        "external_id": "EXTERNAL_UID_GOES_HERE",
        "amount_cap": null,
        "rounding_rule": "",
        "max_discount_units": null,
        "target_price": null,
        "effective_location": [],
        "stack_discounting": null,
        "reuse_qualifying_items": null,
        "enable_menu_item_aggregator": false,
        "min_post_rollback_rate": null,
        "unit_discount": null,
        "receipt_qualifiers": [
          {
            "attribute": "amount",
            "operator": ">=",
            "value": "5"
          },
          {
            "attribute": "subtotal_amount",
            "operator": ">=",
            "value": "5"
          }
        ],
        "percentage_of_processed_amount": null,
        "qc_processing_function": "sum_amounts",
        "line_item_filters": [
          {
            "quantity": null,
            "processing_method": "",
            "line_item_selector": {
              "name": "LIS 17 july 2025",
              "external_id": "EXTERNAL_UID_GOES_HERE",
              "exclude_non_payable": false,
              "filter_item_set": "base_and_modifiers",
              "base_items": {
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "101,106,107"
                  },
                  {
                    "attribute": "item_name",
                    "operator": "like",
                    "value": "Cookie"
                  }
                ]
              },
              "modifiers": {
                "processing_method": "min_price",
                "max_discount_units": 2,
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "1010"
                  }
                ]
              }
            }
          }
        ],
        "item_qualifiers": [
          {
            "expression_type": "net_amount_greater_than_or_equal_to",
            "net_value": 6,
            "line_item_selector": {
              "name": "LIS 2 17 july 2025",
              "external_id": "EXTERNAL_UID_GOES_HERE",
              "exclude_non_payable": false,
              "filter_item_set": "base_only",
              "base_items": {
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "102"
                  }
                ]
              },
              "modifiers": {
                "processing_method": "",
                "max_discount_units": null,
                "clauses": []
              }
            }
          }
        ],
        "aggregator_grouping_attributes": {
          "item_name": true,
          "item_id": true,
          "item_major_group": true,
          "item_family": true,
          "item_type": true
        }
      },
      "discount_details": {
        "item_id": 92,
        "name": "LIS QC 21 july 2025 redeemable",
        "image": "IMAGE_URL_GOES_HERE",
        "points": null,
        "base_amount": null,
        "description": "LIS QC 21 july 2025 redeemable",
        "item_properties": null,
        "meta_detail": "",
        "start_date_tz": "2025-08-04T05:48:26Z",
        "end_date_tz": "2025-08-31T18:29:59Z",
        "created_at": "2025-07-21T12:34:09Z",
        "max_applicable_quantity": null,
        "prompt_text_short": null,
        "prompt_text_long": null
      },
      "qualified_items": []
    },
    {
      "discount_basket_item_id": 2,
      "discount_amount": null,
      "redemption_id": null,
      "redemption_type": null,
      "discount_type": "reward",
      "discount_id": "367779",
      "discount_value": null,
      "message": [
        "Discount qualification on receipt failed for Shubham Gupta at Airway."
      ],
      "qualified": false,
      "remaining_balance": null,
      "meta_data": null,
      "qualifying_conditions": {
        "name": "LIS QC 21 july 2025",
        "external_id": "EXTERNAL_UID_GOES_HERE",
        "amount_cap": null,
        "rounding_rule": "",
        "max_discount_units": null,
        "target_price": null,
        "effective_location": [],
        "stack_discounting": null,
        "reuse_qualifying_items": null,
        "enable_menu_item_aggregator": false,
        "min_post_rollback_rate": null,
        "unit_discount": null,
        "receipt_qualifiers": [
          {
            "attribute": "amount",
            "operator": ">=",
            "value": "5"
          },
          {
            "attribute": "subtotal_amount",
            "operator": ">=",
            "value": "5"
          }
        ],
        "percentage_of_processed_amount": null,
        "qc_processing_function": "sum_amounts",
        "line_item_filters": [
          {
            "quantity": null,
            "processing_method": "",
            "line_item_selector": {
              "name": "LIS 17 july 2025",
              "external_id": "EXTERNAL_UID_GOES_HERE",
              "exclude_non_payable": false,
              "filter_item_set": "base_and_modifiers",
              "base_items": {
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "101,106,107"
                  },
                  {
                    "attribute": "item_name",
                    "operator": "like",
                    "value": "Cookie"
                  }
                ]
              },
              "modifiers": {
                "processing_method": "min_price",
                "max_discount_units": 2,
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "1010"
                  }
                ]
              }
            }
          }
        ],
        "item_qualifiers": [
          {
            "expression_type": "net_amount_greater_than_or_equal_to",
            "net_value": 6,
            "line_item_selector": {
              "name": "LIS 2 17 july 2025",
              "external_id": "EXTERNAL_UID_GOES_HERE",
              "exclude_non_payable": false,
              "filter_item_set": "base_only",
              "base_items": {
                "clauses": [
                  {
                    "attribute": "item_id",
                    "operator": "in",
                    "value": "102"
                  }
                ]
              },
              "modifiers": {
                "processing_method": "",
                "max_discount_units": null,
                "clauses": []
              }
            }
          }
        ],
        "aggregator_grouping_attributes": {
          "item_name": true,
          "item_id": true,
          "item_major_group": true,
          "item_family": true,
          "item_type": true
        }
      },
      "discount_details": {
        "item_id": 92,
        "name": "LIS QC 21 july 2025 redeemable",
        "image": "IMAGE_URL_GOES_HERE",
        "points": null,
        "base_amount": null,
        "description": "LIS QC 21 july 2025 redeemable",
        "item_properties": null,
        "meta_detail": "",
        "start_date_tz": "2025-08-04T05:53:04Z",
        "end_date_tz": "2025-08-31T18:29:59Z",
        "created_at": "2025-07-21T12:34:09Z",
        "max_applicable_quantity": null,
        "prompt_text_short": null,
        "prompt_text_long": null
      },
      "qualified_items": []
    }
  ]
}
Copyright © 2026 PAR Technology Corporation. All rights reserved.
PAR Technology Corporation 8383 Seneca Turnpike, Suite 3 New Hartford, New York 13413 (315) 738-0600 legal@partech.com. PAR Tech is a leading global provider of software, systems, and service solutions to the restaurant and retail industries. You may learn about its product offerings here.
Before using this application, please read the Limited License Agreement and the PAR Tech Terms of Use. In addition, the sample applications of PAR Technology are licensed under the terms of the O'Saasy License.