Punchh Redemptions 2.0 (New) API - POS

info:
  title: Redemptions 2.0 (New) API - POS
  version: '2.0'
  description: "The Redemptions 2.0 protocol has been designed to replace the legacy Redemptions 1.0 endpoints.\
    \ The new protocol allows for the following features:\n\n- Single-scan flow support\n- Batching of\
    \ redemptions to occur in a single API call\n- Stacked discounting\n- Proportional breakdown of discounted\
    \ items\n- Item qualifier recycling\n- Enhance flexibility to redemption rules and processing orders\n\
    \nThe Redemptions 2.0 protocol is not backward compatible with the [legacy Redemptions 1.0 endpoints](/docs/dev-portal-pos/apis/redemptions-1-0-legacy-api).\
    \ Configurations within the Punchh platform are required, so please contact your Punchh representative\
    \ for help before starting development.\n\nRedemptions 2.0 API endpoints\n- Based on the client-side\
    \ interface on the POS side, add/remove discount and selection APIs in the `api/pos` namespace are\
    \ available for the discount basket.    \n- The `api/pos/batch_redemptions` API endpoint allows multiple\
    \ redemptions in a single API request based on Multiple Redemption configuration rules set for a particular\
    \ business.\n\nFor more information, see [POS Module 6: Redemptions](/docs/dev-portal-pos/tutorials/modules/6-redemptions/overview)."
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
paths:
  /api/pos/users/find:
    get:
      summary: Find User (Redemptions 2.0)
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: Guest user ID
                  business_id:
                    type: integer
                    description: This attribute will be replaced by business_uid.
                  phone:
                    type: string
                    description: User’s phone number
                  email:
                    type: string
                    description: User's email address
                  first_name:
                    type: string
                    description: User's first name
                  last_name:
                    type: string
                    description: User's last name
                  payment_mode:
                    type: string
                    description: User's payment mode selected in mobile app
                  selected_card_number:
                    type: string
                    description: User's card selected from mobile app
                  loyalty_cards:
                    type: array
                    description: User's cards selected from mobile app
                    items: {}
                  selected_tip_amount:
                    type: integer
                    description: User's selected tip amount for upcoming transaction in mobile app
                  external_uid:
                    type: string
                    description: Unique identifier generated by the system to lock the discount basket
                      to prevent duplicate transactions
                  locked:
                    type: boolean
                    description: Whether the discount basket is locked or not
              examples:
                Example:
                  value:
                    user_id: 11111111
                    business_id: 27
                    phone: '1111111111'
                    email: test@example.com
                    first_name: FIRST_NAME_GOES_HERE
                    last_name: LAST_NAME_GOES_HERE
                    payment_mode: GiftCard
                    selected_card_number: CARD_NUMBER_GOES_HERE
                    loyalty_cards:
                    - null
                    selected_tip_amount: 1
                    external_uid: EXTERNAL_UID_GOES_HERE
                    locked: false
        '400':
          description: "Bad Request - Example error responses:\n- Required parameter missing or the value\
            \ is empty: lookup_field \n- Required parameter missing or the value is empty: lookup_value "
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: "Not Found - Example error responses:\n\n- Invalid or Expired Single Scan Code\
            \ \n- User not found "
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: Unprocessable Entity - Guest is not allowed to earn/redeem as he/she is banned
            or deactivated from the Loyalty program
          content:
            application/json:
              schema:
                type: object
                properties: {}
      operationId: get-api-pos-users-find
      description: This API endpoint is used for guest user identification. Both `lookup_field` and `lookup_value`
        are passed as request parameters to look up the user account. The response includes user profile
        information in addition to the user ID.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Accept'
      x-stoplight:
        id: ce2bc2798ed8f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                lookup_field:
                  type: string
                  description: 'Field (e.g., phone, email, etc.) used to look up the user account. Accepted
                    values are:

                    - phone - User’s phone number

                    - email - User''s email address

                    - otp - Single-scan code generated by mobile API for user identification

                    - none - Anonymous guest flow handling. If you pass the "none" value in the `lookup_field`
                    request parameter and the "anonymous" value in the `lookup_value` request parameter,
                    a new guest user will be created with a user ID and a dummy email ID in Punchh (returned
                    in the API response).

                    - reward_id - Not recommended

                    - redemption_code - Not recommended

                    - user_as_qrcode - User''s QR code identification in loyalty account

                    - user_token - User''s authentication

                    - apple_nfc_data - User identifier that enables look-up of user information generated
                    from the Apple Pass. See [Implement Apple Pass Integration With POS](/docs/dev-portal-pos/additional-topics/applepassintegrationwithpos)

                    - nfc_token - User identifier that enables the look-up of user information generated
                    from the Google Pass. See [Implement Google Pass Integration With POS](/docs/dev-portal-pos/additional-topics/implement-google-pass-integration-with-pos)'
                lookup_value:
                  type: string
                  description: 'Value of the look-up field (phone number, email address, etc.). Example
                    values:

                    - phone - 1111111111

                    - email - test@example.com

                    - otp - 111111

                    - none - anonymous

                    - reward_id - <REWARD_ID_GOES_HERE>

                    - redemption_code - <REDEMPTION_CODE_GOES_HERE>

                    - user_as_qrcode - <QR_CODE_GOES_HERE>

                    - user_token - <TOKEN_GOES_HERE>

                    - apple_nfc_data - <TOKEN_GOES_HERE>

                    - nfc_token - <TOKEN_GOES_HERE>'
              required:
              - lookup_field
              - lookup_value
            examples:
              Example:
                value:
                  lookup_field: phone/otp/none/
                  lookup_value: <phone_number>/<single_scan_code>/anonymous/
  /api/pos/discounts/auto_select:
    post:
      summary: Auto Redemption (Redemptions 2.0)
      operationId: post-api-auth-discounts-auto_select
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  redemption_ref:
                    type: string
                    description: Transaction level identifier for all discount selections
                  locked:
                    type: boolean
                    x-stoplight:
                      id: rzkkqfaaw025t
                    description: Indicates whether the discount basket is locked. A value of true means
                      the basket is locked.
                  created_at:
                    type: string
                    description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss
                      format
                    format: date-time
                  discount_basket_items:
                    $ref: '#/components/schemas/discount_basket_items'
              examples:
                Example:
                  value:
                    redemption_ref: REDEMPTION_REF_GOES_HERE
                    locked: true
                    created_at: null
                    discount_basket_items:
                    - discount_basket_item_id: 4699
                      discount_type: reward
                      discount_id: '33703164'
                      discount_value: null
                      created_at: '2022-08-25T10:03:48Z'
                      discount_details:
                        item_id: 777658
                        name: Flat $5 Off (Unlocks at 100 points)
                        campaign_name: Mass Campaign Offer
                        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
                Listing expired discount with error message:
                  value:
                    redemption_ref: REDEMPTION_REF_GOES_HERE
                    locked: true
                    created_at: null
                    discount_basket_items:
                    - discount_basket_item_id: 4699
                      discount_type: reward
                      discount_id: '33703164'
                      discount_value: null
                      created_at: '2022-08-25T10:03:48Z'
                      discount_details:
                        item_id: 777658
                        name: Flat $5 Off (Unlocks at 100 points)
                        campaign_name: Mass Campaign Offer
                        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
                    - discount_basket_item_id: 4890
                      discount_type: reward
                      discount_id: '33703165'
                      discount_value: null
                      created_at: '2022-08-25T10:03:48Z'
                      message:
                      - Invalid Reward ID.
                      discount_details: null
        '400':
          description: 'Bad Request - Example error responses:

            - Required parameter missing or the value is empty: receipt_amount

            - Required parameter missing or the value is empty: line_items '
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: Not Found - User not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: 'Unprocessable Entity - Example error responses:

            - Guest is not allowed to select/unselect from basket as he/she is banned or deactivated from
            the Loyalty program

            - Invalid Receipt Amount

            - Your current loyalty program configuration does not support this feature. Please connect
            with your Customer Success representative for resolution of the issue.

            - Unable to access the user’s Discount Basket, the Basket is currently locked'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: "- A discount should be automatically queued up in the discount basket if the auto-redemption\
        \ feature is enabled for the business.\n- The business can configure the auto-redemption strategy.\n\
        - If a discount expires after being added to the discount basket, it is removed from the discount\
        \ basket. When you make a call to the API, it validates the offers added to the discount basket.\
        \ If one or more discounts are found to be honored, expired, perished, or archived, the API returns\
        \ an error message indicating that these discounts cannot be honored. The API lists the invalid\
        \ discounts in the `discount_basket_items` object with a message stating that the discount is\
        \ invalid and returns a null value in the `discount_details` object.\n\n **Note**: Auto-redemption\
        \ currently supports only subscriptions and non-points-based rewards."
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/accept language'
      x-stoplight:
        id: d3e1d4293ad65
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                line_items:
                  $ref: '#/components/schemas/line_items'
                receipt_datetime:
                  type: string
                  description: Timestamp of receipt per ISO 8601 format, including TZ offset from UTC
                    (YYYY-MM-DDThh:mm:ss-±hh:mm)
                  format: date-time
                subtotal_amount:
                  type: number
                  format: float
                  description: 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.
                receipt_amount:
                  type: number
                  format: float
                  description: 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.
                business_date:
                  type: string
                  description: Business date
                punchh_key:
                  type: string
                  description: Punchh key
                transaction_no:
                  type: string
                  description: Transaction number
                user_id:
                  type: integer
                  description: Guest user ID
                external_uid:
                  type: string
                  x-stoplight:
                    id: 5o7sexzfm6by7
                  description: 'Unique identifier generated by the system to lock the discount basket
                    and prevent duplicate transactions. This parameter is optional when reward locking
                    is enabled for the business in the Punchh platform. <b>Note</b>: Contact your Punchh
                    representative to update this configuration setting.'
              required:
              - receipt_datetime
              - subtotal_amount
              - receipt_amount
              - user_id
            examples:
              Example:
                value:
                  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
                  business_date: <store this information>
                  punchh_key: '1111111111111'
                  transaction_no: '11111111111'
                  user_id: 11111111
                  external_uid: EXTERNAL_UID_GOES_HERE
    parameters: []
  /api/pos/discounts/lookup:
    post:
      summary: Discount Look-up (Redemptions 2.0)
      operationId: post-api-pos-discounts-lookup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  selected_discounts:
                    type: array
                    description: List of discounts results that are selected or added to the basket. See
                      the JSON response example for a list of parameters that are included in this array
                      object.
                    items:
                      type: object
                  unselected_discounts:
                    type: array
                    description: List of discounts results that are not added to the basket. See the JSON
                      response example for a list of parameters that are included in this array object.
                    items:
                      type: object
                  discount_basket_item_id:
                    type: integer
                    description: Unique identifier of selection
                  discount_amount:
                    type: integer
                    description: Discount amount/points
                  redemption_id:
                    type: integer
                    format: int64
                    description: Unique ID of the redemption
                  redemption_type:
                    type: string
                    description: Redemption status
                  discount_type:
                    type: string
                    description: 'The discount type can be any one of these values: card_completion ||
                      reward || redeemable || discount_amount || redemption_code || subscription || fuel_reward.
                      For details, see [Make Your First POS API Call](/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call#redemption-types).'
                  discount_id:
                    type: integer
                    description: Unique ID that identifies the discount (e.g., reward_id, redeemable_id,
                      redemption_code, coupon_code)
                  discount_value:
                    type: number
                    format: float
                    description: 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.
                  message:
                    type: string
                    description: Error message
                  qualified:
                    type: boolean
                    description: Indicates a discount's applicability to the receipt
                  remaining_balance:
                    type: number
                    description: Available currency balance / banked rewards in the user’s account. This
                      value is set only when the program type of the business is banked rewards.
                  meta_data:
                    type: string
                    description: 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 in the
                      Punchh platform and has a maximum length of 255 characters.
                  discount_details:
                    $ref: '#/components/schemas/discount_details'
                  qualified_items:
                    $ref: '#/components/schemas/qualified_items'
              examples:
                Example:
                  value:
                    selected_discounts:
                    - discount_basket_item_id: 2710
                      discount_amount: 1
                      redemption_id: 78244965
                      redemption_type: Redemption
                      discount_type: reward
                      discount_id: 773861859
                      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)
                        campaign_name: Mass Campaign Offer
                        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: []
                    unselected_discounts:
                    - discount_type: reward
                      discount_id: 63
                      discount_amount: 2
                      qualified_items: []
                      discount_details: []
                      qualified: true
                    - discount_type: redemption_code
                      discount_id: <coupon_code>
                      discount_amount: 3
                      qualified_items: []
                      qualified: false
        '400':
          description: 'Bad Request - Example error responses:

            - Required parameter missing or the value is empty: receipt_amount

            - Required parameter missing or the value is empty: external_uid '
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: 'Unprocessable Entity - Example error responses:

            - Unable to access the user’s Discount Basket, the Basket is currently locked

            - Your current loyalty program configuration does not support this feature. Please connect
            with your Customer Success representative for resolution of the issue

            - Invalid Receipt Amount

            - Invalid Business Configuration. Please connect with your Customer Success representative
            for resolution of the issue'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: 'You can use this API endpoint to:

        - Look up a guest''s available discount in the loyalty account, per the guest’s user ID.

        - Evaluate the guest’s discount basket against the receipt to verify the applicability of discounts
        if needed.

        - 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](/docs/dev-portal-developer-resources/d7b83074c9f23-redemptions-2-0-discount-basket-locking).
        You must log in to the developer portal to access the developer guide.


        The API returns the following:

        - Selected discounts in the `selected_discounts` array object, which contains any pre-selected
        discount items selected using the mobile app and [Add Selection to Discount Basket](/docs/dev-portal-pos/apis/redemptions-2-0-new-api/paths/~1api~1pos~1discounts~1select/post)
        API. If the business is configured for auto-redemption, the `selected_discounts` object will contain
        all available discounts for the user. If no discount items are pre-selected, the API returns an
        empty `selected_discounts` object.

        - Unselected discounts in the `unselected_discounts` array object, which contains any discount
        items that are available in the user account but not yet added to the discount basket

        - Discount basket in the API response indicating which discounts in the basket are applicable
        and which do not apply to the check items'
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/accept language'
      x-stoplight:
        id: 7bc37320c4f5f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                line_items:
                  $ref: '#/components/schemas/line_items'
                receipt_datetime:
                  type: string
                  description: Timestamp of receipt per ISO 8601 format, including TZ offset from UTC
                    (YYYY-MM-DDThh:mm:ss-±hh:mm)
                  format: date-time
                subtotal_amount:
                  type: number
                  format: float
                  description: 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.
                receipt_amount:
                  type: number
                  format: float
                  description: 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.
                business_date:
                  type: string
                  description: Business date
                punchh_key:
                  type: string
                  description: Punchh key
                transaction_no:
                  type: string
                  description: Transaction number
                user_id:
                  type: integer
                  description: Guest user ID
                external_uid:
                  type: string
                  x-stoplight:
                    id: kyrb3s0uey4lp
                  description: '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. <b>Note</b>: Contact your Punchh
                    representative to update this configuration setting.'
              required:
              - receipt_datetime
              - subtotal_amount
              - receipt_amount
              - user_id
            examples:
              Example:
                value:
                  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
                  business_date: <store this information>
                  punchh_key: '1111111111111'
                  transaction_no: '11111111111'
                  user_id: 11111111
                  external_uid: EXTERNAL_UID_GOES_HERE
  /api/pos/discounts/select:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  redemption_ref:
                    type: string
                    description: Transaction level identifier for all discount selections
                  locked:
                    type: boolean
                    x-stoplight:
                      id: apr3pqg2alycg
                    description: Indicates whether the discount basket is locked. A value of true means
                      the basket is locked.
                  location_id:
                    type: integer
                    description: Unique identifier of location
                    x-stoplight:
                      id: v0o8s1tv2y85p
                  created_at:
                    type: string
                    format: date-time
                    description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss
                      format
                  discount_basket_items:
                    $ref: '#/components/schemas/discount_basket_items'
              examples:
                Example:
                  value:
                    redemption_ref: REDEMPTION_REF_GOES_HERE
                    locked: false
                    location_id: 20
                    created_at: '2024-05-21T15:14:02Z'
                    discount_basket_items:
                    - discount_basket_item_id: 469363
                      discount_type: reward
                      discount_id: '41049646877'
                      discount_value: null
                      created_at: '2024-05-24T08:36:52Z'
                      discount_details:
                        item_id: 41049646877
                        name: Sandwich Test | AK
                        campaign_name: Mass Campaign Offer
                        image: IMAGE_URL_GOES_HERE
                        points: null
                        base_amount: null
                        description: ''
                        item_properties: ''
                        meta_detail: null
                     

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-pos-redemptions-v2-openapi.yml