Punchh Check-Ins API

openapi: 3.0.3
info:
  title: PAR Punchh Mobile Check-In Check-Ins 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: Check-Ins
  description: Loyalty check-in transaction details.
paths:
  /api2/mobile/checkins/transactions:
    get:
      operationId: getCheckinTransactionDetails
      summary: Transaction Details
      description: Returns details for a check-in transaction, including points earned, membership level, and associated redemptions. The transaction ID is delivered in the push notification payload key "t".
      tags:
      - Check-Ins
      security:
      - PunchhBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionDetailsRequest'
            examples:
              GetcheckintransactiondetailsRequestExample:
                summary: Default getCheckinTransactionDetails request
                x-microcks-default: true
                value:
                  client: business_client_key
                  transaction_id: '500123'
      responses:
        '200':
          description: Check-in transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetails'
              examples:
                Getcheckintransactiondetails200Example:
                  summary: Default getCheckinTransactionDetails 200 response
                  x-microcks-default: true
                  value:
                    checkin:
                      checkin_id: '500123'
                      created_at: '2025-03-15T14:30:00Z'
                      current_membership_level: example
                      location_id: '500123'
                      pending_refresh: example
                      points_earned: example
                      store_number: STORE-001
                      survey_url: https://portal.example.com/path/abc123
                      first_checkin: example
                      expiring_on: example
                    redemptions:
                    - redemption_id: '500123'
                      redemption_status: active
                      created_at: '2025-03-15T14:30:00Z'
                      updated_at: '2025-03-15T14:30:00Z'
                      redeemable_id: '500123'
                      redeemable_name: Free Appetizer
                      redeemed_value: example
                      redemption_image_url: https://portal.example.com/path/abc123
                      redemption_message: Reward successfully applied to the order.
                      redemption_tracking_code: CODE-AB12CD
                      expiring_at: example
        '401':
          description: Unauthorized.
      x-source-url: https://developers.partech.com/docs/dev-portal-mobile/2d7bc9f034998-transaction-details
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/pos/checkins:
    post:
      operationId: createPosCheckin
      summary: Create Check-In
      description: Creates a loyalty check-in at the point of sale.
      tags:
      - Check-Ins
      security:
      - PunchhPosToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PosCheckinRequest'
            examples:
              CreateposcheckinRequestExample:
                summary: Default createPosCheckin request
                x-microcks-default: true
                value:
                  store_number: STORE-001
                  transaction_no: TXN-784512
                  receipt_amount: example
                  subtotal_amount: example
      responses:
        '200':
          description: Check-in created.
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable Entity.
      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:
    TransactionDetails:
      title: TransactionDetails
      type: object
      x-schema-source: documentation
      properties:
        checkin:
          type: object
          properties:
            checkin_id:
              type: integer
              example: '500123'
            created_at:
              type: string
              format: date-time
              example: '2025-03-15T14:30:00Z'
            current_membership_level:
              type: string
              example: example
            location_id:
              type: integer
              example: '500123'
            pending_refresh:
              type: boolean
              example: example
            points_earned:
              type: number
              example: example
            store_number:
              type: string
              example: STORE-001
            survey_url:
              type: string
              example: https://portal.example.com/path/abc123
            first_checkin:
              type: boolean
              example: example
            expiring_on:
              type: string
              example: example
        redemptions:
          type: array
          items:
            type: object
            properties:
              redemption_id:
                type: integer
                example: '500123'
              redemption_status:
                type: string
                example: active
              created_at:
                type: string
                format: date-time
                example: '2025-03-15T14:30:00Z'
              updated_at:
                type: string
                format: date-time
                example: '2025-03-15T14:30:00Z'
              redeemable_id:
                type: integer
                example: '500123'
              redeemable_name:
                type: string
                example: Free Appetizer
              redeemed_value:
                type: number
                example: example
              redemption_image_url:
                type: string
                example: https://portal.example.com/path/abc123
              redemption_message:
                type: string
                example: Reward successfully applied to the order.
              redemption_tracking_code:
                type: string
                example: CODE-AB12CD
              expiring_at:
                type: string
                example: example
    PosCheckinRequest:
      title: PosCheckinRequest
      type: object
      x-schema-source: documentation
      properties:
        store_number:
          type: string
          example: STORE-001
        transaction_no:
          type: string
          example: TXN-784512
        receipt_amount:
          type: number
          example: example
        subtotal_amount:
          type: number
          example: example
    TransactionDetailsRequest:
      title: TransactionDetailsRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      - transaction_id
      properties:
        client:
          type: string
          description: OAuth client ID provided by the business.
          example: business_client_key
        transaction_id:
          type: string
          description: Receipt transaction ID from push notification payload key "t".
          example: '500123'
  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.