Punchh Api2 API

openapi: 3.2.0
info:
  title: Punchh Api2 API
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  version: '1.0'
  description: 'Operations tagged Api2 across 6 of this provider''s published API definitions: punchh-mobile-redemptions-legacy-openapi.yml, punchh-mobile-redemptions-v2-openapi.yml, punchh-mobile-subscription-openapi.yml, punchh-platform-functions-headless-offers-openapi.yml, punchh-platform-functions-offers-ingestion-openapi.yml, punchh-platform-functions-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: Api2
paths:
  /api2/mobile/redemptions/{redemption_id}:
    parameters:
    - schema:
        type: integer
        format: int64
      name: redemption_id
      in: path
      required: true
      description: Redemption ID returned when the redemption is created
      x-stoplight:
        id: 90fd89b67ddc1
    delete:
      summary: Cancel Redemption (Redemptions 1.0)
      operationId: delete-api2-mobile-redemptions
      responses:
        '200':
          description: OK - Redemption successfully cancelled
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
                    x-stoplight:
                      id: m5t0iepx0dqg5
              examples:
                Sending an invalid redemption ID:
                  value:
                    errors: This Redemption is an invalid redemption or It is not for this guest
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
                    x-stoplight:
                      id: p3shfxdabejn2
              examples:
                ' Cancelling an expired redemption':
                  value:
                    errors: This Redemption cannot be cancelled because the Redemption code has been expired
                Cancelling a cancelled redemption:
                  value:
                    errors: Redemption cancellation failed. This redemption has already been cancelled.
                Cancelling an honored redemption:
                  value:
                    errors: This Redemption cannot be cancelled because the Redemption code has been honoured / redeemed
      description: "Allows users to cancel their redemption if it has not been processed, enabling them to select a new one without waiting for the redemption code to expire. Once the redemption is processed, the user cannot cancel it.\n\nThe `cancel_redemption` response parameter in the [Program Meta](/docs/dev-portal-mobile/2617bed9b0e8e-program-meta) API indicates whether the user can revoke (cancel) the generated redemption code from the brand's app. This is controlled by hiding or displaying the cancel redemption button on the brand's app. Contact your Punchh representative to update this Punchh platform configuration.\n<!--Whitelabel > Mobile Configuration > Loyalty > Cancel Redemption-->\n\n<b> Cancel Redemption Failure Scenarios</b>\n\nThe API returns an error if the discount associated with the redemption you want to cancel is invalid, already redeemed/honored, cancelled, or expired. \n\n<b>View Cancelled Redemption Status </b>\n\nThe Punchh platform displays the cancelled redemption on the user’s timeline and in the Account History tab. \n\nIf you have a redemption code for the cancelled redemption, you can use the [Search Redemption Code](/docs/dev-portal-platform-functions/ac8e06639a62c-search-redemption-code) API to verify the status of the cancelled redemption. "
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept-Language'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: htkodzobkpi6f
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              Example:
                value:
                  client: CLIENT_GOES_HERE
                  redemption_id: 490636366
        description: ''
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/redemptions/banked_currency:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/redemption_details'
              examples:
                default:
                  value:
                    redemption_status: redeemable
                    created_at: '2016-05-25T06:41:37-04:00'
                    redeemable_id: null
                    location_id: 304361
                    redemption_image_url: IMAGE_URL_GOES_HERE
                    redemption_message: Message associated with the redemption.
                    updated_at: '2016-05-25T06:41:37-04:00'
                    redeemable_description: ''
                    redemption_id: 1822896
                    redemption_tracking_code: '7246338'
                    expiring_at: '2016-05-25T08:41:37-04:00'
                    redeemable_name: null
                    campaign_name: Mass Campaign Offer
                    redeemed_value: '10'
        '400':
          description: ''
      summary: Create Redemption Using Banked Currency (Redemptions 1.0)
      description: Creates a redemption using a currency amount. The amount is deducted from a user's available banked currency.
      operationId: mobile_create_redemption_using_banked_currency
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: a7be5bbb2906d
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                banked_currency:
                  type: number
                  format: double
                  description: The amount of banked currency with which a redemption code has to be created
                location_id:
                  type: integer
                  description: Location ID at which the redemption code is generated. If no location ID is provided, then it returns the ID of the default location.
                latitude:
                  type: string
                  description: Latitude coordinate of the redemption location
                longitude:
                  type: string
                  description: Longitude coordinate of the redemption location
                gps_accuracy:
                  type: integer
                  description: Accuracy of a user's device GPS
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  banked_currency: 10
                  location_id: 304155
                  latitude: '26.9167509'
                  longitude: '75.8136926'
                  gps_accuracy: 27
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/redemptions/visits:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/redemption_details'
              examples:
                default:
                  value:
                    redemption_status: redeemable
                    created_at: '2016-05-25T06:41:37-04:00'
                    redeemable_id: null
                    location_id: 304361
                    redemption_image_url: IMAGE_URL_GOES_HERE
                    redemption_message: Message associated with the redemption.
                    updated_at: '2016-05-25T06:41:37-04:00'
                    redeemable_description: ''
                    redemption_id: 1822896
                    redemption_tracking_code: '7246338'
                    expiring_at: '2016-05-25T08:41:37-04:00'
                    redeemable_name: null
                    campaign_name: Mass Campaign Offer
                    redeemed_value: '10'
        '400':
          description: ''
      summary: Create Redemption Using Visits (Redemptions 1.0)
      description: Creates a redemption for an unredeemed card. This is for use with visit-based businesses.
      operationId: mobile_create_redemption_using_visits
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      x-stoplight:
        id: 1ae3d27ce6a88
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                location_id:
                  type: integer
                  description: Location ID at which a user wants to do the redemption. If a particular location ID is provided in the request, the redemption will be valid only at that location and will not be possible at any other.
                latitude:
                  type: string
                  description: Latitude coordinate of the redemption location. Must be provided if location_id is not passed as a parameter.
                longitude:
                  type: string
                  description: Longitude coordinate of the redemption location. Must be provided if location_id is not passed as a parameter.
                gps_accuracy:
                  type: integer
                  description: Accuracy of a user's device GPS
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  location_id: '304155'
                  latitude: 26.9167509
                  longitude: 75.8136926
                  gps_accuracy: 27
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/redemptions/redeemable:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/redemption_details'
              examples:
                default:
                  value:
                    redemption_status: redeemable
                    created_at: '2016-05-25T06:50:02-05:00'
                    redeemable_id: 41
                    location_id: 304361
                    redemption_image_url: IMAGE_URL_GOES_HERE
                    redemption_message: Redeem your free Sandwich, with purchase of chips and drink
                    updated_at: '2016-05-25T06:50:02-05:00'
                    redeemable_description: ''
                    redemption_id: 1818919
                    redemption_tracking_code: '8723640'
                    expiring_at: '2016-05-25T08:50:02-05:00'
                    redeemable_name: The Sandwich
                    campaign_name: Mass Campaign Offer
                    redeemed_value: '0'
        '400':
          description: ''
      summary: Create Redemption Using Redeemable (Redemptions 1.0)
      description: Creates a redemption for a redeemable based on a user's available loyalty points
      operationId: mobile_create_redemption_using_redeemable
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      x-stoplight:
        id: d491967b73fc7
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                reedemable_id:
                  type: number
                  format: double
                  description: ID of the redeemable used to create a redemption code
                location_id:
                  type: integer
                  description: Location ID at which a user wants to do the redemption. If a particular location ID is provided in the request, the redemption will be valid only at that location and will not be possible at any other.
                latitude:
                  type: string
                  description: Latitude coordinate of the redemption location. Must be provided if location_id is not passed as a parameter.
                longitude:
                  type: string
                  description: Longitude coordinate of the redemption location. Must be provided if location_id is not passed as a parameter.
                gps_accuracy:
                  type: integer
                  description: Accuracy of a user's device GPS
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  redeemable_id: 1102
                  location_id: '304155'
                  latitude: 26.9167509
                  longitude: 75.8136926
                  gps_accuracy: 27
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/redemptions/reward:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/redemption_details'
              examples:
                default:
                  value:
                    redemption_status: redeemable
                    created_at: '2016-05-25T06:55:04-05:00'
                    redeemable_id: 75
                    location_id: 304361
                    redemption_image_url: IMAGE_URL_GOES_HERE
                    redemption_message: Redeem your Free Bag of Chips
                    updated_at: '2016-05-25T06:55:04-05:00'
                    redeemable_description: ''
                    redemption_id: 1818920
                    redemption_tracking_code: '1809897'
                    expiring_at: '2016-05-25T08:55:04-05:00'
                    redeemable_name: Bag of Chips
                    campaign_name: Mass Campaign Offer
                    redeemed_value: null
        '400':
          description: ''
      summary: Create Redemption Using Reward ID (Redemptions 1.0)
      description: Creates a redemption for a reward that has been given to a user (e.g., through a campaign).
      operationId: mobile_create_redemption_using_reward_id
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      x-stoplight:
        id: 2969c78154a17
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                reward_id:
                  type: integer
                  description: 'The ID of the reward for which the redemption code has to be created

                    '
                  format: int64
                location_id:
                  type: integer
                  description: Location ID at which a user wants to do the redemption. If a particular location ID is provided in the request, the redemption will be valid only at that location and will not be possible at any other.
                latitude:
                  type: string
                  description: Latitude coordinate of the redemption location. Must be provided if a location_id is not passed as a parameter.
                longitude:
                  type: string
                  description: Longitude coordinate of the redemption location. Must be provided if a location_id is not passed as a parameter.
                gps_accuracy:
                  type: integer
                  description: Accuracy of a user's device GPS
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  reward_id: 5167827
                  location_id: '304155'
                  latitude: 26.9167509
                  longitude: 75.8136926
                  gps_accuracy: 27
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/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 associated with the 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 for a user in the system
                        end_date_tz:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward offer ends
                        start_date_tz:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward offer starts
                        updated_at:
                          type: string
                          enum:
                          - YYYY-MM-DDThh:mm:ssZ
                          format: date-time
                          description: Date/time when the reward offer was udpated
                        id:
                          type: integer
                          format: int64
                          description: Unique ID of the reward
                        image:
                          type: string
                          description: URL of the image depicting the reward
                        status:
                          type: string
                          description: Status of the reward (e.g., "unredeemed", "honoured", "expired")
                        points:
                          type: integer
                          description: Points needed for the reward
                        discount_amount:
                          type: integer
                          description: Discount amount associated with the reward
                        description:
                          type: string
                          description: Description of the reward
                        name:
                          type: string
                          description: Name of the reward
                        redeemable_properties:
                          type: string
                          description: Properties of the redeemable
                      required:
                      - name
              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: '1.1'
                    discount_amount: 2
                    reward:
                      created_at: '2019-04-02T22:46:32-07:00'
                      end_date_tz: null
                      start_date_tz: '2019-04-02T22:46:32-07:00'
                      updated_at: '2019-04-02T22:46:32-07:00'
                      id: 2
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 0
                      description: ''
                      name: 2% off Subtotal Amount
                      redeemable_properties: ''
                  - 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: '1.1'
                    discount_amount: 2
                    reward:
                      created_at: '2019-04-04T04:00:34-07:00'
                      end_date_tz: null
                      start_date_tz: '2019-04-04T04:00:34-07:00'
                      updated_at: '2019-04-04T04:00:34-07:00'
                      id: 3
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 2
                      description: $2 Off Your Order. Participating locations only.
                      name: $2 Off Your Order
                      redeemable_properties: ''
                  - 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: '1.1'
                    discount_amount: 2
                    reward:
                      created_at: '2019-04-04T04:01:03-07:00'
                      end_date_tz: null
                      start_date_tz: '2019-04-04T04:01:03-07:00'
                      updated_at: '2019-04-04T04:01:03-07:00'
                      id: 4
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 0
                      description: ''
                      name: 2% off Subtotal Amount
                      redeemable_properties: ''
                  - 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: '1.1'
                    discount_amount: 2
                    reward:
                      created_at: '2019-04-15T10:48:40-07:00'
                      end_date_tz: null
                      start_date_tz: '2019-04-15T10:48:40-07:00'
                      updated_at: '2019-04-15T10:48:40-07:00'
                      id: 14
                      image: IMAGE_URL_GOES_HERE
                      status: unredeemed
                      points: 0
                      discount_amount: 0
                      description: ''
                      name: 2% off Subtotal Amount
                      redeemable_properties: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      location_id:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      location_id: Required parameter missing or the value is empty.
      summary: List Applicable Offers (Redemptions 1.0)
      description: Returns applicable offers based on the check details.
      operationId: mobile_list_applicable_offers
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      x-stoplight:
        id: f09cf9b1e970a
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                menu_items:
                  $ref: '#/components/schemas/menu-items'
                client:
                  type: string
                  description: OAuth client ID provided by the business
                amount:
                  type: string
                  description: Order amount based on items added to the cart
                location_id:
                  type: string
                  description: Location ID of the store
                channel:
                  type: string
                  x-stoplight:
                    id: zazefztzioqd5
                  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: mobile, chatbot.'
                  enum:
                  - ' mobile'
                  - ' chatbot'
              required:
              - client
              - channel
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  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: '1.1'
                  amount: '100'
                  location_id: LOCATION_GOES_HERE
                  channel: mobile
        description: ''
      tags:
      - Api2
    servers:
    - url: https://SERVER_NAME_GOES_HERE.punchh.com
  /api2/mobile/discounts/select:
    parameters: []
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  redemption_ref:
                    type: string
                    description: Transaction level identifier for all discount selections
                  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
                    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 Co

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