Punchh Redemptions API

openapi: 3.0.3
info:
  title: PAR Punchh Mobile Check-In Redemptions API
  version: '1.0'
  description: The PAR Punchh Mobile API powers business-branded mobile apps and websites, exposing guest-facing loyalty functions such as user registration and sign-in, profile management, check-ins/transactions, and offer management. Access requires partner certification and business-issued OAuth client credentials. All calls are signed with an HMAC-SHA256 `x-pch-digest` header. Base URLs (sandbox and production) are provided by a Punchh representative.
  x-generated-from: documentation
  x-last-validated: '2026-06-03'
  contact:
    name: PAR Developer Portal
    url: https://developers.partech.com/
servers:
- url: https://{server_name}.punchh.com
  description: Punchh environment host (provided by your Punchh representative)
  variables:
    server_name:
      default: SERVER_NAME_GOES_HERE
      description: Environment-specific host name
tags:
- name: Redemptions
  description: Apply rewards and discounts against online order receipts.
paths:
  /api/auth/redemptions/online_order:
    post:
      operationId: createOnlineOrderRedemption
      summary: Create Online Redemption
      description: Redeems a card, reward, redeemable, or discount against an online order receipt. Receipt details are revalidated during processing.
      tags:
      - Redemptions
      security:
      - PunchhBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnlineOrderRedemptionRequest'
            examples:
              CreateonlineorderredemptionRequestExample:
                summary: Default createOnlineOrderRedemption request
                x-microcks-default: true
                value:
                  client: business_client_key
                  discount_type: reward
                  receipt_amount: example
                  receipt_datetime: '2025-03-15T14:30:00Z'
                  store_number: STORE-001
                  subtotal_amount: example
                  transaction_no: TXN-784512
      responses:
        '200':
          description: Redemption applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnlineOrderRedemptionResponse'
              examples:
                Createonlineorderredemption200Example:
                  summary: Default createOnlineOrderRedemption 200 response
                  x-microcks-default: true
                  value:
                    status: active
                    redemption_amount: example
                    category: reward
                    qualified_menu_items:
                    - {}
                    discount_distribution_items:
                    - {}
                    redemption_id: '500123'
                    redemption_code: CODE-AB12CD
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-online-ordering/60069336e34d4-create-online-redemption-redemptions-1-0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/pos/redemptions/possible:
    post:
      operationId: getPosPossibleRedemptions
      summary: Possible Redemptions
      description: Returns the redemptions available to a guest for the supplied receipt.
      tags:
      - Redemptions
      security:
      - PunchhPosToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              GetpospossibleredemptionsRequestExample:
                summary: Default getPosPossibleRedemptions request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Possible redemptions.
        '401':
          description: Unauthorized.
      x-source-url: https://developers.partech.com/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/pos/redemptions:
    post:
      operationId: createPosRedemption
      summary: Create Redemption
      description: Applies a redemption against a POS receipt.
      tags:
      - Redemptions
      security:
      - PunchhPosToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              CreateposredemptionRequestExample:
                summary: Default createPosRedemption request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Redemption created.
        '401':
          description: Unauthorized.
      x-source-url: https://developers.partech.com/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: voidPosRedemption
      summary: Void Redemption
      description: Voids a previously created redemption.
      tags:
      - Redemptions
      security:
      - PunchhPosToken: []
      responses:
        '200':
          description: Redemption voided.
        '401':
          description: Unauthorized.
      x-source-url: https://developers.partech.com/docs/dev-portal-pos/1fbfdfdd05a86-make-your-first-pos-api-call
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    OnlineOrderRedemptionResponse:
      title: OnlineOrderRedemptionResponse
      type: object
      x-schema-source: documentation
      properties:
        status:
          type: string
          description: Redemption confirmation message.
          example: active
        redemption_amount:
          type: number
          description: Discount value applied.
          example: example
        category:
          type: string
          description: Redemption type.
          example: reward
        qualified_menu_items:
          type: array
          items:
            type: object
        discount_distribution_items:
          type: array
          items:
            type: object
        redemption_id:
          type: integer
          example: '500123'
        redemption_code:
          type: string
          example: CODE-AB12CD
    OnlineOrderRedemptionRequest:
      title: OnlineOrderRedemptionRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      - discount_type
      - receipt_amount
      - receipt_datetime
      - store_number
      - subtotal_amount
      - transaction_no
      properties:
        client:
          type: string
          description: Business client key.
          example: business_client_key
        discount_type:
          type: string
          enum:
          - reward
          - card_completion
          - redeemable
          - discount_amount
          - redemption_code
          - subscription
          example: reward
        receipt_amount:
          type: number
          description: Order total before taxes.
          example: example
        receipt_datetime:
          type: string
          description: ISO 8601 timestamp (YYYY-MM-DDThh:mm:ssZ).
          example: '2025-03-15T14:30:00Z'
        store_number:
          type: string
          description: Redemption location.
          example: STORE-001
        subtotal_amount:
          type: number
          description: Pre-tax order amount.
          example: example
        transaction_no:
          type: string
          description: Receipt/transaction identifier.
          example: TXN-784512
  securitySchemes:
    PunchhBearer:
      type: http
      scheme: bearer
      description: Bearer access token obtained via Sign In. Calls must also include an `x-pch-digest` HMAC-SHA256 signature header and a `punchh-app-device-id` header.
    PunchhDigest:
      type: apiKey
      in: header
      name: x-pch-digest
      description: HMAC-SHA256 request signature. Unauthenticated mobile calls also pass the business OAuth `client` id in the request body.