Create Redemption (Redemptions 1.0)

Redeems a card, reward, redeemable, or discount specified in the discount_type parameter against a receipt. Every request must have phone, email, card_number, or redemption_code as a parameter.

Punchh evaluates eligibility during the Possible Redemptions call using the receipt details provided (item name, price, quantity, identifiers, etc.). During the Create Redemption 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 Create Redemption call to fail or return a different result—even if the Possible Redemptions call was successful.

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: array object[] · Menu Items (Array Object)
required

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

Unique Punchh key
receipt_amount
Type: numberFormat: double
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 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

curl https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/redemptions \
  --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"
}