# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Punchh Pos API
  version: 1.0.0
extends: openapi/punchh-pos-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: 15
- target: $.paths['/api/pos/redemptions/possible'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if a redemption can apply to a check
      effect: read
      questions:
      - Can the POS verify a reward will work on a check before redeeming it?
      - Why would a redemption check return a 422 at some locations?
      instructions:
      - text: Check whether redemption code {redemption_code} can apply to check {transaction_no}.
        slots:
          redemption_code: requestBody.redemption_code
          transaction_no: requestBody.transaction_no
      - text: Verify reward {reward_id} is redeemable on a {receipt_amount} receipt before committing.
        slots:
          reward_id: requestBody.reward_id
          receipt_amount: requestBody.receipt_amount
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/redemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem a reward or discount on a receipt
      effect: write
      questions:
      - How does the POS redeem a guest's reward against a receipt in Redemptions 1.0?
      - Which guest identifiers can a POS redemption use?
      instructions:
      - text: Redeem {discount_type} {reward_id} on transaction {transaction_no}.
        slots:
          discount_type: requestBody.discount_type
          reward_id: requestBody.reward_id
          transaction_no: requestBody.transaction_no
      - text: Apply redemption code {redemption_code} to the {receipt_amount} check for {email}.
        slots:
          redemption_code: requestBody.redemption_code
          receipt_amount: requestBody.receipt_amount
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/redemptions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void one processed redemption
      effect: destructive
      questions:
      - How do I undo a single redemption and give the offer back to the guest?
      - Are there time limits on voiding coupon redemptions?
      instructions:
      - text: Void redemption {redemption_id} on transaction {transaction_no}.
        slots:
          redemption_id: requestBody.redemption_id
          transaction_no: requestBody.transaction_no
      - text: Cancel redemption code {redemption_code} and return the reward to {email}.
        slots:
          redemption_code: requestBody.redemption_code
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/redemptions/multiple_destroy'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void several redemptions at once
      effect: destructive
      questions:
      - Can the POS void multiple redemptions in one request?
      - What happens to the rewards when a batch of Redemptions 1.0 redemptions is voided?
      instructions:
      - text: Void all the redemptions {redemption_id} on check {transaction_no} together.
        slots:
          redemption_id: requestBody.redemption_id
          transaction_no: requestBody.transaction_no
      - text: Bulk-cancel the redemptions for guest {email} on order {transaction_no}.
        slots:
          email: requestBody.email
          transaction_no: requestBody.transaction_no
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/redemptions/applicable_offers'].post
  update:
    x-apievangelist-phrasing:
      intent: List offers that apply to a check
      effect: read
      questions:
      - Which of a guest's offers apply to the items on their current check?
      - Can the POS ask what offers fit an order before choosing one to redeem?
      instructions:
      - text: List offers applicable to {email}'s {receipt_amount} check.
        slots:
          email: requestBody.email
          receipt_amount: requestBody.receipt_amount
      - text: 'Find offers for {email} that fit these menu items: {menu_items}.'
        slots:
          email: requestBody.email
          menu_items: requestBody.menu_items
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/users/active_redemptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a guest's active redemptions at the POS
      effect: read
      questions:
      - Which redemptions does a guest currently have open?
      - Can the POS look up active redemptions by phone number?
      instructions:
      - text: Show active redemptions for {email}.
        slots:
          email: query.email
      - text: Get the open redemptions for the guest with phone {phone}.
        slots:
          phone: query.phone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/users/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Identify a guest at the POS
      effect: read
      questions:
      - How does the POS find a loyalty guest before applying Redemptions 2.0 discounts?
      - Which fields can I use to look a guest up at the register?
      instructions:
      - text: Find the guest whose {lookup_field} is {lookup_value}.
        slots:
          lookup_field: requestBody.lookup_field
          lookup_value: requestBody.lookup_value
      - text: Look up the loyalty member by phone {lookup_value} at the POS.
        slots:
          lookup_value: requestBody.lookup_value
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/auto_select'].post
  update:
    x-apievangelist-phrasing:
      intent: Auto-fill a guest's discount basket
      effect: write
      questions:
      - Can discounts be queued into a guest's basket automatically at checkout?
      - Who decides which discounts auto-redemption picks?
      instructions:
      - text: Auto-select discounts for user {user_id} on a {receipt_amount} receipt.
        slots:
          user_id: requestBody.user_id
          receipt_amount: requestBody.receipt_amount
      - text: Run auto-redemption for guest {user_id} with subtotal {subtotal_amount}.
        slots:
          user_id: requestBody.user_id
          subtotal_amount: requestBody.subtotal_amount
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/lookup'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a guest's discounts and lock the basket
      effect: write
      questions:
      - What discounts does a guest have available against this receipt?
      - How do I lock a guest's discount basket so another channel can't change it?
      instructions:
      - text: Look up discounts for user {user_id} against a {receipt_amount} receipt.
        slots:
          user_id: requestBody.user_id
          receipt_amount: requestBody.receipt_amount
      - text: Check user {user_id}'s basket and lock it with external ID {external_uid}.
        slots:
          user_id: requestBody.user_id
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/select'].post
  update:
    x-apievangelist-phrasing:
      intent: Add discounts to a guest's basket
      effect: write
      questions:
      - How does a cashier add a chosen reward to the guest's discount basket?
      - Can a guest have more than one active discount basket?
      instructions:
      - text: Add {items} to user {user_id}'s discount basket.
        slots:
          items: requestBody.discount_basket_items_attributes
          user_id: requestBody.user_id
      - text: Select discounts {items} for guest {user_id} on locked basket {external_uid}.
        slots:
          items: requestBody.discount_basket_items_attributes
          user_id: requestBody.user_id
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/unselect'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove discounts from a guest's basket
      effect: destructive
      questions:
      - How do I take a discount back out of a guest's basket before checkout?
      - Can several discounts be removed from the basket in one call?
      instructions:
      - text: Remove basket items {item_ids} from user {user_id}'s basket.
        slots:
          item_ids: requestBody.discount_basket_item_ids
          user_id: requestBody.user_id
      - text: Unselect discount {item_ids} for guest {user_id}.
        slots:
          item_ids: requestBody.discount_basket_item_ids
          user_id: requestBody.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/batch_redemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit the discount basket as a redemption
      effect: write
      questions:
      - How do I finalize the discounts in a guest's basket when the order is paid?
      - Does the batch redemption revalidate the receipt before committing?
      instructions:
      - text: Commit user {user_id}'s discount basket on a {receipt_amount} receipt.
        slots:
          user_id: requestBody.user_id
          receipt_amount: requestBody.receipt_amount
      - text: Process batch redemption for guest {user_id} with line items {line_items}.
        slots:
          user_id: requestBody.user_id
          line_items: requestBody.line_items
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/batch_redemptions/{redemption_ref}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void a committed discount basket
      effect: destructive
      questions:
      - How do I reverse a whole Redemptions 2.0 batch redemption?
      - Where do I get the redemption reference needed to void a basket?
      instructions:
      - text: Void batch redemption {redemption_ref} for user {user_id}.
        slots:
          redemption_ref: path.redemption_ref
          user_id: requestBody.user_id
      - text: Reverse the committed basket {redemption_ref}.
        slots:
          redemption_ref: path.redemption_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/active'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a guest's active discount basket
      effect: read
      questions:
      - Which discounts has a guest already selected in their basket?
      - What happens to a basket discount that expires before checkout?
      instructions:
      - text: Show the active discount basket for user {user_id}.
        slots:
          user_id: requestBody.user_id
      - text: Get guest {user_id}'s basket locked under {external_uid}.
        slots:
          user_id: requestBody.user_id
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/discounts/unlock'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlock a guest's discount basket
      effect: write
      questions:
      - How do I release a locked discount basket so another channel can use it?
      - When does a discount basket need to be unlocked?
      instructions:
      - text: Unlock user {user_id}'s discount basket held by {external_uid}.
        slots:
          user_id: requestBody.user_id
          external_uid: requestBody.external_uid
      - text: Release the basket lock {external_uid} for guest {user_id}.
        slots:
          external_uid: requestBody.external_uid
          user_id: requestBody.user_id
      method: generated
      generated: '2026-10-01'