Possible Redemptions (Redemptions 1.0)

Use this API to verify that a redemption can be applied on a given check.

Note: The API returns a 422 error message when a user attempts to redeem a loyalty/ non-loyalty discount at a location that is disabled for redemption by the business. This error message can be customized for the businesses in the Punchh platform to provide them greater flexibility and control over the user experience during redemption attempts at such locations. Contact your Punchh representative for more information about this Punchh platform configuration.

Rules To Select Discount Type

Following are the rules to decide what discount_type to use in the Possible Redemptions and Create Redemption API requests:

`reward`

In the User Lookup and Fetch Balance API request, if any item in the rewards array has either type as reward or does not have a type key, use its id to pass in the reward_id parameter and use discount_type = reward in the Possible Redemptions and Create Redemption API requests.

`redeemable`

In the User Lookup and Fetch Balance API request, if any item in the rewards array has type as redeemable, use its id to pass in the redeemable_id parameter and use discount_type = redeemable in the Possible Redemptions and Create Redemption API requests.

`discount_amount`

In the User Lookup and Fetch Balance API request, if the value of banked_rewards returned in the balance object is greater than 0, then pass a dollar amount in the redeemed_points parameter not exceeding the value of banked_rewards and use discount_type = discount_amount in the Possible Redemptions and Create Redemption API requests.

`card_completion`

In the User Lookup and Fetch Balance API request, if the value of unredeemed_cards returned in the balance object is greater than 0, then use discount_type = card_completion in the Possible Redemptions and Create Redemption API requests.

`redemption_code`

When Redemption Code or Punchh Coupon Code is entered on the POS either by scanning it using the QR code scanner or by manually entering it, pass that code in the redemption_code parameter and use discount_type = redemption_code in the Possible Redemptions and Create Redemption API requests.

`fuel_reward`

It allows a user to use the fuel discount balance, and it can be redeemed when the user is identified on the check. Use discount_type as fuel_reward in API requests.

`subscription`

It allows a user to redeem subscription related benefits. In the User Lookup and Fetch Balance API request, if the subscriptions object has subscription_id, use this ID to pass in the subscription_id parameter and use discount_type = subscription in the Possible Redemptions and Create Redemption API requests.

Headers

Authorization
Type: string
required

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

Short code for locale variant (e.g., fr-ca, es-ES, en-EN, etc.)

Body

application/json

discount_type
Type: string
required

The type of discount. Choose from the following: reward, redeemable, discount_amount, card_completion, redemption_code, fuel_reward, subscription. See the top of this page for more information about each type.
email
Type: string
required

The email address of the user. In the case of the single scan flow, email is not a required parameter.
menu_items
Type:
required

This object contains one or more menu items added to an order. See How To Send Menu Items to Punchh

Properties: 8
punchh_key
Type: string
required

Punchh key (barcode without parity bit) of the receipt as generated by the POS. Should be 11 or 12, 20 digits
receipt_amount
Type: numberFormat: double
required

Order amount before taxes, calculated as the sum of item_amount for M line items in menu_items minus the item_amount for D line items; S, T, and P line items are excluded. See the description of the D, S, T, and P items in the menu_items.menu_item_type request parameter. The value of this parameter should match subtotal_amount.

Note: We do not recommend sending either brand or Punchh discounts as line items in any Redemptions 1.0 requests. See the description of the D item in the menu_item_type request parameter. For multiple redemptions, include previously applied offers as D line items in subsequent requests. See Multiple Redemptions Example for processing multiple discounts.

⚠️ Important: During check-in, loyalty points and visits are calculated based on the individual item amounts in the menu_items array, not directly from receipt_amount.
receipt_datetime
Type: stringFormat: date-time
required

Timestamp of the receipt per ISO 8601 format including TZ offset from UTC (e.g., YYYY-MM-DDThh:mm:ss-±hh:mm)
redeemable_id
Type: string
required

Send this value when discount_type is redeemable. This is the ID of the redeemable the user wants to redeem.
redeemed_points
Type: string
required

Send this value when discount_type is discount_amount. This is the amount of the banked rewards the user wants to redeem.
redemption_code
Type: string
required

Send this value when discount_type is redemption_code. This is the Redemption Code or Punchh Coupon Code that is entered on the POS and is associated with redemption.
reward_id
Type: integerFormat: int64
required

Send this value when discount_type is reward. This is the ID of the reward the user wants to redeem.
single_scan_code
Type: string
required

Single scan code of the user is a required parameter when the user redeems a reward through the single scan flow. The code identifies the user requesting the redemption.
subscription_id
Type: string
required

Send this value when discount_type is subscription. This is a system-generated unique ID of the subscription that is issued to the guest.

Responses

application/json
application/json

post/api/pos/redemptions/possible

curl https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions/possible \
  --request POST \
  --header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "discount_type": "subscription",
  "subscription_id": "1111111",
  "cc_last4": 1111,
  "employee_id": 7,
  "employee_name": "EMPLOYEE_NAME_GOES_HERE",
  "menu_items": [
    {
      "item_name": "Whiterice",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": "12",
      "menu_family": "800",
      "menu_major_group": "152",
      "serial_number": "1.0"
    }
  ],
  "subtotal_amount": 10.72,
  "receipt_amount": 10.72,
  "receipt_datetime": "2023-02-18T18:05:01+05:30",
  "transaction_no": 5678,
  "external_uid": "EXTERNAL_UID_GOES_HERE",
  "punchh_key": "PUNCHH_KEY_GOES_HERE",
  "email": "test@example.com",
  "channel": "pos"
}'

Show Schema

{
  "status": "Redeemed at February 23, 2026 13:02 by <user> at Punchh Demo. It can be honored.",
  "redemption_amount": 8,
  "category": "redeemable",
  "qualified_menu_items": [
    {
      "item_name": "Sandwich",
      "item_qty": 1,
      "item_amount": 5,
      "menu_item_type": "M",
      "menu_item_id": "102000",
      "menu_family": "Sandwich",
      "menu_major_group": "Sandwich",
      "serial_number": "1.0"
    },
    {
      "item_name": "Coke",
      "item_qty": 1,
      "item_amount": 7,
      "menu_item_type": "M",
      "menu_item_id": "102000",
      "menu_family": "Coke",
      "menu_major_group": "Coke",
      "serial_number": "2.0"
    }
  ],
  "discount_distribution_items": [
    {
      "item_name": "Sandwich DISCOUNT",
      "item_qty": 1,
      "item_amount": -3,
      "menu_item_type": "R",
      "menu_item_id": "102000",
      "menu_family": "Sandwich",
      "menu_major_group": "Sandwich",
      "serial_number": 1
    },
    {
      "item_name": "Coke DISCOUNT",
      "item_qty": 1,
      "item_amount": -5,
      "menu_item_type": "R",
      "menu_item_id": "102000",
      "menu_family": "Coke",
      "menu_major_group": "Coke",
      "serial_number": 2
    }
  ],
  "max_applicable_quantity": 1,
  "campaign_name": "Mass Campaign Offer",
  "redemption_id": 21762,
  "redemption_code": "REDEMPTION_CODE_GOES_HERE"
}