Punchh Auth API

openapi: 3.2.0
info:
  title: Punchh Auth API
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  version: '1.0'
  description: 'Operations tagged Auth across 3 of this provider''s published API definitions: punchh-online-ordering-redemptions-legacy-openapi.yml, punchh-online-ordering-redemptions-v2-openapi.yml, punchh-online-ordering-subscription-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Auth
paths:
  /api/auth/redemptions/online_order:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Message that explains if the customer's redemption was successfully completed or not
                  redemption_amount:
                    type: integer
                    description: Total redemption amount that can be applied on the order
                  category:
                    type: string
                    description: 'Category returned for redemption requested where values can be: `redeemable`, `processed`, `expired`, `invalid`, `unassigned`. Consider redemption valid only when the category is returned as `redeemable`.'
                  qualified_menu_items:
                    $ref: '#/components/schemas/Menu-items'
                  discount_distribution_items:
                    $ref: '#/components/schemas/discount_distribution_items'
                  redemption_id:
                    type: integer
                    format: int64
                    description: Unique ID associated with the redemption. Save this in your system for future reference.
                  redemption_code:
                    type: string
                    description: Redemption code associated with redemption
                  max_applicable_quantity:
                    type: number
                    description: 'Maximum quantity that can be discounted. Note: This parameter will be returned for offers related to Price Rollback.'
                  campaign_name:
                    type: string
                    x-stoplight:
                      id: 7s3sui5p01net
                    description: Name of the campaign through which the guest received the offer
                  qualifying_conditions:
                    type: object
                    x-stoplight:
                      id: ox2f9fs82bs54
                    description: 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 1.0 APIs is enabled for the business in the Punchh platform. See the `data` object under [Get Qualification Criteria Response](https://developers.partech.com/docs/dev-portal-platform-functions/97ec083d6cf57-get-qualification-criteria-qc-list#response-body) in Platform Functions for descriptions of the parameters in `qualifying_conditions`.
              examples:
                default:
                  value:
                    status: Redeemed at Feb 26, 2026 10:49 by FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE at Naperville. Please HONOR it.
                    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
        '401':
          description: Sending invalid credentials
        '412':
          description: Sending invalid Signature
        '422':
          description: ''
          content:
            application/json:
              examples:
                default:
                  value:
                  - Given reward is not accessible for this guest
      description: "Redeems a card, reward, redeemable, or discount specified in the `discount_type` parameter against a receipt.\n\nPunchh evaluates eligibility during the Possible Redemptions call using the receipt details provided (item name, price, quantity, identifiers, etc.). During the Create Online Redemption API call, Punchh revalidates the same receipt to ensure the qualifying conditions are still met before honoring the redemption. \n\nIf any item attributes change between the two calls, Punchh may be unable to match the qualifying items, which can cause the Create Online Redemption API call to fail or return a different result—even if the Possible Redemptions call was successful.\n\n**NOTE**: **When processing a redemption, DO NOT include the `query` parameter in the API request.** Use this parameter only to check for possible redemptions. "
      summary: Create Online Redemption (Redemptions 1.0)
      operationId: sso_create_online_redemption
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: 60069336e34d4
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authentication_token:
                  type: string
                  description: The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
                query:
                  type: boolean
                  description: 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.
                cc_last4:
                  type: string
                  description: Last 4 digits of credit card number
                employee_id:
                  type: string
                  description: Employee ID
                employee_name:
                  type: string
                  description: Employee name
                store_number:
                  type: string
                  description: The location where the redemption must be redeemed
                menu_items:
                  $ref: '#/components/schemas/menu_items'
                receipt_amount:
                  type: number
                  format: double
                  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.
                subtotal_amount:
                  type: number
                  format: double
                  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_datetime:
                  type: string
                  description: Timestamp of receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format
                transaction_no:
                  type: string
                  description: Receipt number or transaction number on the receipt
                external_uid:
                  type: string
                  description: 'Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice.

                    '
                client:
                  type: string
                  description: Client key of the business
                channel:
                  type: string
                  enum:
                  - pos
                  - web
                  - online_order
                  - mobile
                  - dashboard
                  - chatbot
                  - kiosk
                  description: 'Channel through which the redemption was requested. Possible values are: online_order, pos, web, mobile, dashboard, chatbot, and kiosk.

                    '
                state:
                  type: string
                  description: 'The current state of the check-in. Possible values are: committed, pending, or void'
                discount_type:
                  type: string
                  enum:
                  - reward
                  - card_completion
                  - redeemable
                  - discount_amount
                  - redemption_code
                  - subscription
                  description: 'Any one of these values: card_completion || reward || redeemable || discount_amount || redemption_code || subscription. For details, see [Getting Started With Online Ordering APIs](/docs/dev-portal-online-ordering/0130fe9413a97-getting-started-with-online-ordering-ap-is).'
                reward_id:
                  type: integer
                  description: Send this value when discount_type is reward. This is the ID of the reward the user wants to redeem.
                  format: int64
                redeemable_id:
                  type: string
                  description: Send this value when discount_type is redeemable. This is the ID of the redeemable the user wants to redeem.
                redeemed_points:
                  type: string
                  description: 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
                  description: Send this value when discount_type is redemption_code. This is the redemption code or Punchh coupon code that is associated with redemption.
                subscription_id:
                  type: string
                  description: Send this value when discount_type is subscription. This is a system-generated unique ID of the subscription that is issued to the guest.
                email:
                  type: string
                  description: Email address of the user (required to be sent only in case of coupons and promos)
              required:
              - store_number
              - receipt_amount
              - subtotal_amount
              - receipt_datetime
              - transaction_no
              - client
              - discount_type
      tags:
      - Auth
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api/auth/redemptions:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  internal_tracking_code:
                    type: integer
                    description: Internal tracking code generated on the redemption
                  expiry_hours:
                    type: integer
                    description: Total number of hours after which the redemption code will expire
              examples:
                default:
                  value:
                    internal_tracking_code: '2142353'
                    expiry_hours: '24'
        '401':
          description: Sending invalid credentials
        '412':
          description: Sending invalid Signature
        '422':
          description: Sending invalid Entity
      summary: Fetch Redemption Code (Redemptions 1.0)
      description: 'This endpoint generates an internal tracking code, which can be used to [look up a user on the POS system](/docs/dev-portal-pos/b3A6NTAyODM5MTc-user-lookup-and-fetch-balance) and [redeem the selected reward or banked currency at the POS](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0). To generate an internal tracking code via this endpoint, you must supply either a reward ID in the **reward_id** parameter or a value for the banked currency to redeem in the **redeemed_points** parameter. While the internal tracking code is active, the selected reward or banked currency value is eligible for redemption at the POS using the value of the internal tracking code as the **redemption_code** in the [POS Redemption API endpoint](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0).


        >User authentication required

        >

        >This API requires authentication_token to be supplied as `HTTP_AUTHORIZATION` header or in the `authentication_token` parameter.'
      operationId: sso_fetch_redemption_code
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      x-stoplight:
        id: 85f9cf163d423
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authentication_token:
                  type: string
                  default: AUTHENTICATION_TOKEN_GOES_HERE
                  description: The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
                client:
                  type: string
                  description: Client key of the business
                location_id:
                  type: integer
                  format: int32
                  description: Location ID of the redemption
                locale:
                  type: string
                  description: Locale used for language
                longitude:
                  type: string
                  description: Longitude of the redemption location
                latitude:
                  type: string
                  description: Latitude of the redemption location
                redeemed_points:
                  type: number
                  format: double
                  description: Value of banked currency to redeem. Use this field only if you have a Points Convert to Currency program type and you are trying to redeem banked currency. Otherwise, use the **reward_id** field only.
                reward_id:
                  type: integer
                  format: int64
                  description: Reward ID (required if redeemed_points is not provided)
                gps_accuracy:
                  type: integer
                  description: 'GPS accuracy

                    '
                store_number:
                  type: string
                  description: 'Store number of the location. This can be used as an alternative to specify the location if location_id/latitute/longitude are not provided.

                    '
              required:
              - client
              - redeemed_points
              - reward_id
            examples:
              default:
                value:
                  authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
                  client: CLIENT_GOES_HERE
                  location_id: 304155
                  locale: ''
                  longitude: '75.8136926'
                  latitude: '26.9167509'
                  redeemed_points: null
                  reward_id: 12345
                  gps_accuracy: 27
                  store_number: '12'
        description: ''
      tags:
      - Auth
    delete:
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Void Processed Redemption (Redemptions 1.0)
      description: 'Voids a processed redemption. After a redemption is voided successfully, the offer tied to the redemption is returned to the guest''s account.


        <b>Note</b>: The Void Redemption API allows you to cancel a redemption without any time restrictions for most types of redemptions. However, for coupons and promos, redemptions can only be voided within 24 hours of the redemption process.'
      operationId: sso_void_processed_redemption
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      x-stoplight:
        id: b7e6468ce7ed7
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                redemption_id:
                  type: integer
                  format: int64
                  description: ID of the redemption that you want to delete
                authentication_token:
                  type: string
                  description: The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
                client:
                  type: string
                  description: Client key of the business
                reason:
                  type: string
                  description: Why the redemption is being deleted
                redemption_code:
                  type: string
                  description: To be entered if the redemption ID is not provided. If both redemption_id and redemption_code are provided, then only redemption_id will be processed.
              required:
              - redemption_id
              - client
            examples:
              default:
                value:
                  redemption_id: 323242
                  authentication_token: AUTHENTICATION_TOKEN_GOES_HERE
                  client: CLIENT_GOES_HERE
      tags:
      - Auth
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api/auth/redemptions/applicable_offers:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    menu_items:
                      $ref: '#/components/schemas/Menu-items'
                    discount_amount:
                      type: integer
                      description: Discount amount applied to the order for an applicable offer or reward
                    reward:
                      type: object
                      properties:
                        created_at:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward was created, in YYYY-MM-DD format
                        end_date_tz:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward will expire, in YYYY-MM-DD format
                        start_date_tz:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward becomes available, in YYYY-MM-DD format
                        updated_at:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward was updated, in YYYY-MM-DD format
                        id:
                          type: integer
                          format: int64
                          description: ID of the reward
                        image:
                          type: string
                          description: Image of the reward
                        status:
                          type: string
                          description: 'Status of the reward (e.g., "unreedemmed", "expired") '
                        points:
                          type: integer
                          description: Points needed to redeem the reward
                        discount_amount:
                          type: integer
                          description: Discount amount of the reward
                        description:
                          type: string
                          description: Description of the reward
                        name:
                          type: string
                          description: Name of the reward
                        redeemable_properties:
                          type: string
                          description: Reedemable properties of the reward. Properties such as "Merchandise", "Food Item", etc. added to a particular redeemable.
              examples:
                default:
                  value:
                  - menu_items:
                    - item_name: Adult
                      item_qty: 1
                      item_amount: 100
                      menu_item_type: M
                      menu_item_id: '1'
                      menu_family: '1'
                      menu_major_group: '1'
                      serial_number: '3.0'
                    discount_amount: 2
                    reward:
                      created_at: '2023-04-03T05:42:02Z'
                      end_date_tz: null
                      start_date_tz: '2023-04-03T05:42:02Z'
                      updated_at: '2023-04-03T05:42:02Z'
                      id: 1
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 2
                      description: $2 Off Your Order. Participating locations only.
                      name: Redeemable - $2 Off Your Order
                      redeemable_properties: null
                  - menu_items:
                    - item_name: Adult
                      item_qty: 1
                      item_amount: 100
                      menu_item_type: M
                      menu_item_id: '1'
                      menu_family: '1'
                      menu_major_group: '1'
                      serial_number: '3.0'
                    discount_amount: 2
                    reward:
                      created_at: '2023-04-03T05:46:32Z'
                      end_date_tz: null
                      start_date_tz: '2023-04-03T05:46:32Z'
                      updated_at: '2023-04-03T05:46:32Z'
                      id: 2
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 2
                      description: ''
                      name: 2% off Subtotal Amount
                      redeemable_properties: null
        '401':
          description: Sending invalid credentials
        '412':
          description: Sending invalid Signature
        '422':
          description: The given reward can't be applied to the given receipt details
      summary: Applicable Offers (Redemptions 1.0)
      description: Returns all applicable rewards available to the user per the items added to the check
      operationId: sso_applicable_offers
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/content_type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/Authorization'
      x-stoplight:
        id: ae5f635ab632f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                authentication_token:
                  type: string
                  description: The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile).
                client:
                  type: string
                  description: Client key of the business
                receipt_amount:
                  type: number
                  format: double
                  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.
                subtotal_amount:
                  type: number
                  format: double
                  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_datetime:
                  type: string
                  format: date-time
                  description: Timestamp of the receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format
                store_number:
                  type: string
                  description: Location where the redemption must be redeemed
                menu_items:
                  $ref: '#/components/schemas/menu_items'
                channel:
                  type: string
                  x-stoplight:
                    id: tfd4xyagg7i9x
                  description: 'Channel through which the order was placed. If a channel is defined in the Receipt Qualifier condition under Offers > Qualification Criteria in the Punchh platform, the API returns the list of offers applicable to the transaction after evaluating the value set for the channel. Possible values: online_order, web.'
                  enum:
                  - online_order
                  - web
              required:
              - client
              - receipt_amount
              - subtotal_amount
              - receipt_datetime
              - channel
      tags:
      - Auth
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /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
              

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