Punchh Redemptions API

openapi: 3.2.0
info:
  title: Platform Functions Redemptions API
  version: '1.0'
  description: This API documentation is intended to provide comprehensive information for admin users of the Punchh platform. Many of the settings and available actions depend on an appropriate level of access to Platform Functions APIs.
  contact:
    name: Punchh DevSupport
    url: https://developers.punchh.com
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Redemptions
paths:
  /api2/dashboard/redemptions:
    get:
      responses:
        '200':
          $ref: '#/components/responses/redemption-detail'
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Search Redemption Code
      operationId: dashboard_search_redemption_code
      tags:
      - Redemptions
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: string
        in: query
        name: location_id
        description: Unique ID of a particular location. This is generated by Punchh.
      - schema:
          type: string
        in: query
        name: redemption_code
        description: Redemption code of the user as generated on the app or web.
      x-stoplight:
        id: ac8e06639a62c
    patch:
      responses:
        '200':
          $ref: '#/components/responses/redemption-detail'
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Process Redemption
      description: Marks a redemption as processed
      operationId: dashboard_process_redemption
      tags:
      - Redemptions
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: d91b52fceaed2
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                redemption_code:
                  type: string
                  description: Redemption code of the user as generated on the app or web
                location_id:
                  type: integer
                  description: Unique ID of a particular business location. This is generated by Punchh.
                store_number:
                  type: string
                  description: Unique store number of a particular location, as provided by the business
            examples:
              default:
                value:
                  redemption_code: REDEMPTION_CODE_GOES_HERE
                  location_id: 304731
                  store_number: MNBVC
  /api2/dashboard/redemptions/force_redeem:
    post:
      operationId: dashboard_force_redeem
      tags:
      - Redemptions
      summary: Force Redeem
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '201':
          $ref: '#/components/responses/redemption-object'
        '401':
          $ref: '#/components/responses/401-unauthorized'
      x-stoplight:
        id: 6d3f5e310b96d
      description: 'The Force Redemption API allows administrators (e.g., restaurant managers, support staff, or corporate team members) to override normal redemption flows and manually or programmatically redeem an offer or promotion on behalf of a guest. This functionality is particularly useful in various customer support, operational, and exception-handling scenarios.


        <b>Note</b>: The Force Redemption API is intended primarily for support-related scenarios where offers need to be redeemed on a limited scale. It should not be used for bulk expirations or large-scale force redemptions. For example, if a brand has distributed offers through a campaign and later runs out of stock for the promotion, this API should not be used to bulk-expire the offers already available to guests in order to discontinue the campaign.


        <b>Usage Limit</b>: Permissible usage is capped at 500 requests per minute (RPM), with a daily limit of up to 100,000 requests. If you need to process more than 100,000 requests in a single day, contact your Punchh representative.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  description: ID that identifies the user
                redemption:
                  type: object
                  properties:
                    requested_punches:
                      type: integer
                    force_message:
                      type: string
                    reward_id:
                      type: integer
                      format: int64
                      description: Unique ID of the reward
                    fuel_redemption:
                      type: boolean
            examples:
              default:
                value:
                  user_id: 111111111
                  redemption:
                    requested_punches: 50
                    force_message: This is a test
components:
  responses:
    redemption-object:
      description: ''
      content:
        application/json:
          schema:
            type: object
            description: Returns the details of a redemption done by a user
            properties:
              redemption_status:
                type: string
                description: 'Status of the redemption. The values returned can be:

                  - redeemable: The redemption can be redeemed at the POS.

                  - expired: The redemption has expired and becomes unusable for the user.

                  - honored: The redemption has already been processed successfully and redeemed by the user at a POS.

                  - cancelled: The redemption can be voided by a user by approaching the POS if a redemption is done by mistake and the user wants to cancel it.'
              created_at:
                type: string
                description: Date/time when the redemption was created in the system, in ISO 8601 format
                format: date-time
              redeemable_id:
                type: integer
                description: Unique ID of the redeemable
              location_id:
                type: integer
                description: Location ID associated with redemption
              redeemable_name:
                description: Name of the redeemable
                type: string
              redeemed_value:
                type: number
                description: 'For a business with banked currency, a currency value will be returned (e.g., 10 would mean $10).


                  For a business without banked currency, a points value will be returned (e.g., 10 would mean 10 points).'
                format: float
              redemption_image_url:
                type: string
                description: URL of the image displayed in the app to depict the redeemable
              redemption_message:
                type: string
                description: A descriptive message that tells a user what the user has redeemed
              updated_at:
                type: string
                description: Date/time at which the redemption was updated in the system
                format: date-time
              redemption_id:
                type: integer
                description: Unique ID of the redemption that has been created
              redemption_tracking_code:
                type: string
                description: Code that a user must submit at the POS to receive the redeemed reward
              expiring_at:
                type: string
                description: Date/time when the redemption_tracking_code expires and the user cannot use it at the POS
                format: date-time
          examples:
            Force redeem:
              value:
                redemption_status: redeemable
                created_at: '2017-02-08T14:54:44Z'
                redeemable_id: null
                redemption_image_url: IMAGE_URL_GOES_HERE
                redemption_message: Message associated with the redemption.
                location_id: 304252
                updated_at: '2017-02-08T14:54:44Z'
                redemption_id: 6440712
                redemption_tracking_code: '7714880'
                expiring_at: '2017-02-08T16:54:44Z'
                redeemable_name: null
                redeemed_value: 50
    redemption-detail:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              redemption_status:
                type: string
                description: 'Status of the redemption. The values returned can be:

                  - redeemable: The redemption can be redeemed at the POS.

                  - expired: The redemption has expired and becomes unusable for the user.

                  - processed: The redemption has already been processed successfully and redeemed by the user at a POS.

                  - cancelled: The redemption can be voided by a user by approaching the POS if a redemption is done by mistake and the user wants to cancel it.'
              created_at:
                type: string
                description: Date/time when the redemption was created in the system, in ISO 8601 format
                format: date-time
              redeemable_id:
                type: integer
                description: Unique ID of the redeemable
              redemption_image_url:
                type: string
                description: URL of the image displayed in the app to depict the redeemable
              redemption_message:
                type: string
                description: A descriptive message that tells a user what the user has redeemed
              updated_at:
                type: string
                description: Date/time at which the redemption was updated in the system
                format: date-time
              redemption_id:
                type: integer
                description: Unique ID of the redemption that has been created
              redemption_tracking_code:
                type: string
                description: Code that a user must submit at the POS to receive the redeemed reward
              expiring_at:
                type: string
                description: Date/time when the redemption_tracking_code expires and the user cannot use it at the POS
                format: date-time
              redeemable_name:
                description: Name of the redeemable
                type: string
              redeemed_value:
                type: number
                description: 'For a business with banked currency, a currency value will be returned (e.g., 10 would mean $10).


                  For a business without banked currency, a points value will be returned (e.g., 10 would mean 10 points).'
                format: float
              user:
                type: object
                description: Returns information about the user who used the redemption code
                properties:
                  email:
                    type: string
                    description: Unique email address used to identify the user
                  first_name:
                    type: string
                    description: First name of the user
                  last_name:
                    type: string
                    description: Last name of the user
                  avatar_remote_url:
                    description: URL of the user's profile image uploaded to an online file storage system. This will be used for users who signed up using email.
                    type: string
          examples:
            Process redemption:
              value:
                redemption_status: processed
                created_at: '2016-10-07T01:36:10Z'
                redeemable_id: null
                redemption_image_url: IMAGE_URL_GOES_HERE
                redemption_message: ''
                updated_at: '2016-10-07T01:36:10Z'
                redemption_id: 3562961
                redemption_tracking_code: '6725261'
                expiring_at: '2016-10-07T03:36:10Z'
                redeemable_name: null
                redeemed_value: 8.05
                user:
                  first_name: FIRST_NAME_GOES_HERE
                  last_name: LAST_NAME_GOES_HERE
                  email: test@example.com
                  avatar_remote_url: null
            Search redemption code:
              value:
                redemption_status: redeemable
                created_at: '2016-10-07T01:36:10Z'
                redeemable_id: null
                redemption_image_url: IMAGE_URL_GOES_HERE
                redemption_message: ''
                updated_at: '2016-10-07T01:36:10Z'
                redemption_id: 3562961
                redemption_tracking_code: '6725261'
                expiring_at: '2016-10-07T03:36:10Z'
                redeemable_name: null
                redeemed_value: 8.05
                user:
                  first_name: FIRST_NAME_GOES_HERE
                  last_name: LAST_NAME_GOES_HERE
                  email: test@example.com
                  avatar_remote_url: null
    401-unauthorized:
      description: 'A business admin key is missing or invalid. A request header in the following format is needed to make the request:


        `Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE`'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            default:
              value:
                error: You need to sign in or sign up before continuing.
  parameters:
    authorization-header:
      schema:
        type: string
        default: Bearer BUSINESS_ADMIN_KEY_GOES_HERE
      name: Authorization
      in: header
      description: 'Bearer token for admin authorization, who is making a call on behalf of the customer. Send the API key in the following format: "Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE".'
      required: true
x-stoplight:
  id: 9820bbd2e8ee1
x-ext-urls: {}