API Evangelist conversational phrasing for POS Point Of Sale API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for POS Point Of Sale API
  version: 1.0.0
extends: openapi/punchh-point-of-sale-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/api/pos/locations/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a store location's POS configuration
      effect: read
      questions:
      - How does a POS terminal pull the loyalty settings for its own store location?
      - What keys does the register need to send to read its location configuration?
      instructions:
      - text: Fetch the loyalty configuration for this store location.
      - text: Get the POS location settings in language {Accept-Language}.
        slots:
          Accept-Language: header.Accept-Language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/meta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get loyalty program details for the POS
      effect: read
      questions:
      - What program type and redeemables does the register need to know about this loyalty program?
      - How quickly do program configuration changes show up at the POS?
      instructions:
      - text: Show the loyalty program meta for the POS.
      - text: Get the program type and redeemable list for the register.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll a new loyalty member at the register
      effect: write
      questions:
      - Can a cashier sign a guest up for loyalty right at the POS with just a phone number?
      - Can the POS trigger an opt-in SMS when enrolling a new member?
      instructions:
      - text: Enroll a new loyalty member with phone {phone}.
        slots:
          phone: requestBody.phone
      - text: Sign up {first_name} {last_name} at the register with phone {phone} and email {email}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          phone: requestBody.phone
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a loyalty guest and their balance at the POS
      effect: read
      questions:
      - How does the register find a guest's loyalty account by phone, email or QR code?
      - Can a cashier look up a guest with a drive-thru short code?
      instructions:
      - text: Look up the loyalty guest with phone {phone} and show their balance.
        slots:
          phone: query.phone
      - text: Find the guest for drive-thru code {drive_thru_code}.
        slots:
          drive_thru_code: query.drive_thru_code
      - text: Identify the guest by redemption code {redemption_code}.
        slots:
          redemption_code: query.redemption_code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/checkins'].post
  update:
    x-apievangelist-phrasing:
      intent: Award loyalty for an in-store check
      effect: write
      questions:
      - How does the POS credit a guest with points for a purchase they just made in store?
      - Is email required for a POS check-in when using the single-scan flow?
      instructions:
      - text: 'Create a POS check-in for {email} on transaction {transaction_no}: {receipt_amount} at {receipt_datetime}.'
        slots:
          email: requestBody.email
          transaction_no: requestBody.transaction_no
          receipt_amount: requestBody.receipt_amount
          receipt_datetime: requestBody.receipt_datetime
      - text: Check in single-scan code {single_scan_code} for transaction {transaction_no} paying {payable}.
        slots:
          single_scan_code: requestBody.single_scan_code
          transaction_no: requestBody.transaction_no
          payable: requestBody.payable
      method: generated
      generated: '2026-10-01'
- target: $.paths['/receipt_details'].post
  update:
    x-apievangelist-phrasing:
      intent: Send receipt details from the POS
      effect: write
      questions:
      - How do I push every receipt from my POS so guests can scan it later for points?
      - Can I void a receipt I already sent or mark one as a test?
      instructions:
      - text: Store receipt {transaction_no} with Punchh key {punchh_key} for {amount}.
        slots:
          transaction_no: requestBody.transaction_no
          punchh_key: requestBody.punchh_key
          amount: requestBody.amount
      - text: Void stored receipt {transaction_no} by sending status {status}.
        slots:
          transaction_no: requestBody.transaction_no
          status: requestBody.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a visit without earning loyalty
      effect: write
      questions:
      - Can I log a guest's store visit without giving them any points?
      - Which identifiers can tie a non-earning transaction to a guest?
      instructions:
      - text: Record a non-earning transaction {transaction_no} for {email} totaling {receipt_amount}.
        slots:
          transaction_no: requestBody.transaction_no
          email: requestBody.email
          receipt_amount: requestBody.receipt_amount
      - text: Register a visit for phone {phone} on transaction {transaction_no} without awarding loyalty.
        slots:
          phone: requestBody.phone
          transaction_no: requestBody.transaction_no
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/users/balance'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch a guest's account balance and subscriptions
      effect: read
      questions:
      - What points, rewards and subscription benefits does a guest have available at the register?
      - Can I filter the balance response to a specific discount type?
      instructions:
      - text: Fetch the account balance for user {user_id}.
        slots:
          user_id: requestBody.user_id
      - text: Show user {user_id}'s balance with discounts of type {discount_type}.
        slots:
          user_id: requestBody.user_id
          discount_type: requestBody.discount_type
      method: generated
      generated: '2026-10-01'