Punchh Redemptions 2.0 (New) API - Online Ordering

info:
  title: Redemptions 2.0 (New) API - Online Ordering
  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:


    - Single-scan flow support

    - Batching of redemptions to occur in a single API call

    - Stacked discounting

    - Proportional breakdown of discounted items

    - Item qualifier recycling

    - Enhance flexibility to redemption rules and processing orders


    The Redemptions 2.0 protocol is not backward compatible with the [legacy Redemptions 1.0 endpoints](/docs/dev-portal-online-ordering/apis/oo-redemptions-1-0-legacy-api).
    Configurations within the Punchh platform are required, so please contact your Punchh representative
    for help before starting development.


    Redemptions 2.0 API endpoints - general workflow

    1. Guest adds discount if not already selected.

    2. Fetch active basket details.

    3. Update discount basket if required. Add/remove discount selection.

    4. After successful submission of order, the Batch Redemption API will be called to process the redemption
    of all selected discounts.


    For more information, see [Online Ordering Module 5: Redemptions](/docs/dev-portal-online-ordering/tutorials/modules/5-redemptions/overview).'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
paths:
  /api/auth/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: bza0ruu9nwh31
                    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.

        - The business can configure the auto-redemption strategy.

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


        **Note**: Auto-redemption currently supports only subscriptions and non-points-based rewards.'
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/accept language'
      x-stoplight:
        id: d3e1d4293ad65
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client key of the business
                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
                transaction_no:
                  type: string
                  description: Transaction number
                external_uid:
                  type: string
                  x-stoplight:
                    id: l8errxvcbef2m
                  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.'
              required:
              - client
              - receipt_datetime
              - subtotal_amount
              - receipt_amount
            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>
                  transaction_no: '11111111111'
                  client: CLIENT_GOES_HERE
                  external_uid: EXTERNAL_UID_GOES_HERE
  /api/auth/discounts/select:
    post:
      responses:
        '200':
          description: ''
          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: eada20qcylhhh
                    description: Indicates whether the discount basket is locked. A value of true means
                      the basket is locked.
                  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
                    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: 48188
                        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
                        start_date_tz: '2024-05-24T08:34:24Z'
                        end_date_tz: '2024-06-30T03:15:00Z'
                        created_at: '2023-08-18T08:29:36Z'
                        auto_select: false
                    - discount_basket_item_id: 541689
                      discount_type: reward
                      discount_id: '41378920421'
                      discount_value: null
                      created_at: '2024-06-11T12:56:33Z'
                      discount_details:
                        item_id: 48188
                        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
                        start_date_tz: '2024-05-31T13:25:08Z'
                        end_date_tz: '2024-06-30T03:15:00Z'
                        created_at: '2023-08-18T08:29:36Z'
                        auto_select: false
        '400':
          description: 'Bad Request - Example error responses:

            - Required parameter missing or the value is empty: user_id

            - Required parameter missing or the value is empty: discount_basket_items_attributes

            - Required parameter missing or the value is empty: discount_type

            - Required parameter missing or the value is empty: external_uid'
          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:

            - Discount basket items have already been taken for the user

            - Same parameters provided multiple times

            - Not enough cards

            - Processing limit for discounts of loyalty type has been reached

            - Invalid Code

            - Coupon/Promo code is not active

            - The code can not be added, as the campaign has exceeded its usage limit

            - This coupon can only be used 1 time(s) per day

            - Invalid Business Configuration. Please connect with your Customer Success representative
            for resolution of the issue.

            - Mobile Coupon/Promo cannot be added into basket

            - Balance is insufficient to process request

            - Max Redemption Amount has been reached

            - Invalid Discount Value

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

            - Interoperability validation failed

            - Invalid Subscription ID

            - Invalid Redeemable ID

            - Invalid Reward ID

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

            - Redemption limit reached

            - Discount type should be card_completion, discount_amount, redemption_code, reward, fuel_reward,
            redeemable, subscription

            - Another transaction is currently accessing the same code. Please try after some time.

            - Cannot add more than one subscription into basket'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: '- A single discount basket will be active at a time. If there is no active discount
        basket, the system will create a new active discount basket along with selected discounts passed
        in the request parameters.

        - The Punchh system will not have any validation based on points adjustments as discounts are
        added.

        - When a guest adds multiple discounts, and one is invalid for some reason, the entire request
        will fail with an error message. The guest will then be required to remove the invalid discount
        and resubmit. '
      summary: Add Selection to Discount Basket (Redemptions 2.0)
      operationId: sso_create_online_redemption
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/accept language'
      x-stoplight:
        id: 49c4867d18844
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client key of the business
                discount_basket_items_attributes:
                  type: array
                  description: List of discounts to add to basket
                  items:
                    type: object
                    properties:
                      discount_type:
                        type: string
                        enum:
                        - reward
                        - card_completion
                        - redeemable
                        - discount_amount
                        - redemption_code
                        - subscription
                        - fuel_reward
                        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 [Getting Started With Online Ordering APIs](/docs/dev-portal-online-ordering/0130fe9413a97-getting-started-with-online-ordering-ap-is).'
                      discount_id:
                        type: integer
                        description: Discount ID
                      discount_value:
                        type: number
                        description: Value of discount. Send this value when discount_type is discount_amount.
                          This is the amount of the banked rewards the user wants to redeem.
                        format: float
                    required:
                    - discount_type
                external_uid:
                  type: string
                  x-stoplight:
                    id: 3y6agmfqv4r4w
                  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.'
              required:
              - client
              - discount_basket_items_attributes
            examples:
              Example:
                value:
                  discount_basket_items_attributes:
                  - discount_id: 131
                    discount_type: reward
                  - discount_value: 2
                    discount_type: discount_amount
                  client: CLIENT_GOES_HERE
                  external_uid: EXTERNAL_UID_GOES_HERE
        description: ''
  /api/auth/discounts/unselect:
    parameters: []
    delete:
      summary: Remove Item From Discount Basket (Redemptions 2.0)
      operationId: delete-api-auth-discounts-unselect
      responses:
        '200':
          description: OK
          headers: {}
          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: rl8ecf3bw8dll
                    description: Indicates whether the discount basket is locked. A value of true means
                      the basket is locked.
                  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
                    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: 48188
                        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
                        start_date_tz: '2024-05-24T08:34:24Z'
                        end_date_tz: '2024-06-30T03:15:00Z'
                        created_at: '2023-08-18T08:29:36Z'
                        auto_select: false
                    - discount_basket_item_id: 541689
                      discount_type: reward
                      discount_id: '41378920421'
                      discount_value: null
                      created_at: '2024-06-11T12:56:33Z'
                      discount_details:
                        item_id: 48188
                        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
                        start_date_tz: '2024-05-31T13:25:08Z'
                        end_date_tz: '2024-06-30T03:15:00Z'
                        created_at: '2023-08-18T08:29:36Z'
                        auto_select: false
        '400':
          description: 'Bad Request - Required parameter missing or the value is empty: discount_basket_item_ids'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: 'Not Found - Example error responses:

            - User does not have an active basket

            - User not found'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: 'Unprocessable Entity - Example error responses:

            - Discount Items not found with any given ids

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

            - Unable to access the user’s Discount Basket, the Basket is currently locked'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: Delete one or more discounts from a discount basket.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/accept language'
      x-stoplight:
        id: 8a087a5033151
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client key of the business
                discount_basket_item_ids:
                  type: array
                  description: IDs of items that need to be removed from the discount basket
                  items:
                    type: integer
                external_uid:
                  type: string
                  x-stoplight:
                    id: wy2ef1w8pibgg
                  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.'
              required:
              - client
              - discount_basket_item_ids
            examples:
              Example:
                value:
                  discount_basket_item_ids:
                  - 4690
                  - 4691
                  client: CLIENT_GOES_HERE
                  external_uid: EXTERNAL_UID_GOES_HERE
  /api/auth/discounts/active:
    get:
      summary: Get Active Discount Basket (Redemptions 2.0)
      tags: []
      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: rq8knfiuv9tfn
                    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
        '404':
          description: 'Not Found - Example error responses:

            - User does not have an active basket

            - User not found'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: 'Unprocessable Entity - Example error responses:

            - 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: {}
      operationId: get-api-auth-discounts-active
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/content type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/accept language'
      description: '- Get a list of discount details that have been selected by a guest. Only one active
        basket can exist in the system for a particular guest.

        - 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 discounts 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.'
      x-stoplight:
        id: 1d4f01cf7aa32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client key of the business
                external_uid:
                  type: string
                  x-stoplight:
          

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