sso_create_online_redemption

Batch Redemption Process (Redemptions 2.0)

​
  • Evaluates the validity of all inputs and commits the redemption.
  • Placed orders for future date. The guest's Punchh loyalty account balance is referenced and evaluated on the date of committing the order (Sys.date), not on the date scheduled for pick-up/delivery.
  • 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.

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

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. Note: When authentication is performed using Advanced Authentication, you must include the id_token in the id-token header and the access_token in the Authorization header. See Access Punchh APIs Using Access and ID tokens

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

  • id-token
    Type: string

    A token that contains identity information about the authenticated user. It is used to verify the user’s identity and is required only when authentication is performed using Advanced Authentication. This token alone does not grant access to Punchh APIs. To access the APIs, you must include the id_token in the id-token header and the access_token in the Authorization header. See Access Punchh APIs Using Access and ID tokens

Body
application/json
  • client
    Type: string
    required

    Client key of the business

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

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

    List of line items

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

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

  • transaction_no
    Type: string

    Transaction number

Responses
  • 200
    Type: object
    • discount_amount
      Type: integer

      Discount amount/points

    • discount_basket_item_id
      Type: integer

      Unique identifier of selection

    • discount_details
      Type: Discount Details (Object)

      List of a discount's defining attributes. In the case of the Auto Redemption and Get Active Discount Basket APIs, the object returns a null value for invalid discounts.

    • discount_id
      Type: integer

      Discount ID (e.g., reward_id, redeemable_id, redemption_code, coupon_code)

    • discount_type
      Type: string

      Discount type (e.g., reward, redeemable, etc.)

    • discount_value
      Type: numberFormat: float

      Value of the currency that a user wants to redeem. This value is set for users on the “Points Convert to Currency” loyalty program. The default value is 0 if the user has not selected any amount to redeem or has no currency in the loyalty account. The parameter returns a “null” value for a business that does not support banking of points into currency.

    • failures
      Type: array object[]

      The failures array in the response lists discounts that are not successfully redeemed, even if the HTTP request returns a 200 status. Note that not all HTTP request failures result in a 4xx HTTP status code.

    • message
      Type: string

      Error message

    • meta_data
      Type: string

      Metadata that can be added to a redeemable. This can be used to program mobile apps to have a certain behavior when specific data are received from the server. Or it can be used as the business wishes. This can be configured from the Punchh platform and has a maximum length of 255 characters.

      The meta_data value for the coupon redemption (i.e., when discount_type = redemption_code) is returned in the language specified in the Accept-Language request header, provided the meta_data has been translated into the relevant language in the Punchh platform. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the meta_data value for a coupon is returned in French only if a French translation is configured for the coupon meta data in the Punchh platform; otherwise the value is returned in the default English language.

    • qualified
      Type: boolean

      Indicates a discount's applicability to the receipt

    • qualified_items
      Type: array Qualified Items (Array Object)[]

      List of qualified items

    • qualifying_conditions
      Type: object

      The object lists all qualification criteria (both receipt-level and line-item) for submitted offers that failed while processing the redemption. This object is returned in the response only if the option to return the qualifying conditions for Redemption 2.0 flow is enabled for the business in the Punchh platform. See the data object under Get Qualification Criteria Response in Platform Functions for descriptions of the parameters in qualifying_conditions.

    • redemption_id
      Type: integer

      Unique ID of the redemption

    • redemption_ref
      Type: string

      Transaction level identifier for all discount selections

    • redemption_type
      Type: string

      Redemption status

    • remaining_balance
      Type: number

      Total amount remaining

    • success
      Type: array object[]

      List of discounts results that are successfully redeemed

  • 400
    Type: object
  • 404
    Type: object
  • 422
    Type: object
post/api/auth/batch_redemptions
{
  "redemption_ref": "string",
  "success": [
    {}
  ],
  "failures": [
    {}
  ],
  "discount_basket_item_id": 1,
  "discount_amount": 1,
  "redemption_id": 1,
  "redemption_type": "string",
  "discount_type": "string",
  "discount_id": 1,
  "discount_value": 1,
  "message": "string",
  "qualified": true,
  "remaining_balance": 1,
  "meta_data": "string",
  "discount_details": {
    "item_id": 1,
    "name": "string",
    "image": "string",
    "points": 1,
    "base_amount": 1,
    "description": "string",
    "item_properties": "string",
    "meta_detail": "string",
    "start_date_tz": "2025-12-19T16:30:10.408Z",
    "end_date_tz": "2025-12-19T16:30:10.408Z",
    "created_at": "2025-12-19T16:30:10.408Z",
    "auto_select": true,
    "campaign_name": "string",
    "max_applicable_quantity": 1
  },
  "qualified_items": [
    {
      "item_name": "string",
      "item_qty": 1,
      "amount": 1,
      "item_type": "string",
      "item_id": 1,
      "item_family": "string",
      "item_group": "string",
      "serial_number": "string"
    }
  ],
  "qualifying_conditions": {}
}