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

Content-Type
Type: string
required

Set this header to application/json.
User-Agent
Type: string
required

For details, see User Agent.
Authorization
Type: string
required

This is a combination of unique API location key as well as business key (UUID) as the Authorization header.
Accept
Type: string
required

Advertises which content types the client is able to understand
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 Marketing Automation > Campaign Management, and 3) subscription plan name and subscription description when creating/editing a subscription plan under Wallets and Passes > Subscription Plans.

Body

application/json

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)
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.
user_id
Type: integer
required

Guest user ID
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 setting.
punchh_key
Type: string

Punchh key
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

post/api/pos/batch_redemptions

curl https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/batch_redemptions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: IntegratorName/IntegrationType/VersionNumber' \
  --header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
  --header 'Accept: application/json' \
  --data '{
  "query": true,
  "user_id": 11111111,
  "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,
  "punchh_key": "1111111111111",
  "transaction_no": "11111111111",
  "external_uid": "EXTERNAL_UID_GOES_HERE"
}'

Show Schema

{
  "redemption_ref": "REDEMPTION_REF_GOES_HERE",
  "success": [
    {
      "discount_basket_item_id": 266118,
      "discount_amount": 5,
      "redemption_id": 130097719,
      "redemption_type": "Redemption",
      "discount_type": "redeemable",
      "discount_id": 777658,
      "discount_value": null,
      "message": null,
      "qualified": true,
      "remaining_balance": null,
      "meta_data": null,
      "discount_details": {
        "item_id": 777658,
        "name": "Flat $5 Off (Unlocks at 100 points)",
        "image": "IMAGE_URL_GOES_HERE",
        "points": 100,
        "base_amount": 5,
        "description": "",
        "item_properties": null,
        "meta_detail": null,
        "start_date_tz": null,
        "end_date_tz": null,
        "created_at": "2022-09-08T18:41:16Z",
        "auto_select": true
      },
      "qualified_items": [
        {
          "item_name": "Pizza1 DISCOUNT",
          "item_qty": 1,
          "amount": 5,
          "item_type": "R",
          "item_id": 331,
          "item_family": "10",
          "item_group": "gp",
          "serial_number": "1.0"
        }
      ]
    }
  ],
  "failures": []
}