Punchh Check-In API

openapi: 3.0.3
info:
  title: PAR Punchh Mobile Check-In 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-In
  description: Loyalty check-ins for online orders.
paths:
  /api/auth/checkins/online_order:
    post:
      operationId: createOnlineOrderCheckin
      summary: Create Loyalty Check-In
      description: Creates a loyalty check-in for an online order, accruing points based on the receipt amount. Use `external_uid` to guarantee idempotency.
      tags:
      - Check-In
      security:
      - PunchhBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnlineOrderCheckinRequest'
            examples:
              CreateonlineordercheckinRequestExample:
                summary: Default createOnlineOrderCheckin request
                x-microcks-default: true
                value:
                  client: business_client_key
                  external_uid: '500123'
                  payable: example
                  receipt_amount: example
                  receipt_datetime: '2025-03-15T14:30:00Z'
                  store_number: STORE-001
                  subtotal_amount: example
                  transaction_no: TXN-784512
                  authentication_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
                  cc_last4: example
                  channel: pos
                  employee_id: '500123'
      responses:
        '200':
          description: Check-in created with loyalty totals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnlineOrderCheckinResponse'
              examples:
                Createonlineordercheckin200Example:
                  summary: Default createOnlineOrderCheckin 200 response
                  x-microcks-default: true
                  value:
                    first_name: Jane Smith
                    last_name: Jane Smith
                    total_checkins: example
                    points_balance: example
                    checkin:
                      checkin_id: '500123'
                      points_earned: example
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable Entity.
      x-source-url: https://developers.partech.com/docs/dev-portal-online-ordering/f1943957e38b4-create-loyalty-check-in
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    OnlineOrderCheckinRequest:
      title: OnlineOrderCheckinRequest
      type: object
      x-schema-source: documentation
      required:
      - client
      - external_uid
      - payable
      - receipt_amount
      - receipt_datetime
      - store_number
      - subtotal_amount
      - transaction_no
      properties:
        client:
          type: string
          description: Business client key.
          example: business_client_key
        external_uid:
          type: string
          description: Unique transaction identifier to prevent duplicates.
          example: '500123'
        payable:
          type: number
          description: Final amount after discounts, taxes, and fees.
          example: example
        receipt_amount:
          type: number
          description: Order subtotal used for loyalty calculations.
          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: Location identifier.
          example: STORE-001
        subtotal_amount:
          type: number
          description: Same as receipt_amount.
          example: example
        transaction_no:
          type: string
          description: Receipt/transaction number.
          example: TXN-784512
        authentication_token:
          type: string
          description: User auth token.
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        cc_last4:
          type: string
          description: Last 4 card digits.
          example: example
        channel:
          type: string
          enum:
          - pos
          - web
          - online_order
          - mobile
          - dashboard
          - chatbot
          - kiosk
          example: pos
        employee_id:
          type: string
          description: Employee or system ID.
          example: '500123'
    OnlineOrderCheckinResponse:
      title: OnlineOrderCheckinResponse
      type: object
      x-schema-source: documentation
      properties:
        first_name:
          type: string
          example: Jane Smith
        last_name:
          type: string
          example: Jane Smith
        total_checkins:
          type: integer
          example: example
        points_balance:
          type: number
          example: example
        checkin:
          type: object
          properties:
            checkin_id:
              type: integer
              example: '500123'
            points_earned:
              type: number
              example: example
  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.