API Evangelist conversational phrasing for Mobile Gift Cards API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mobile Gift Cards API
  version: 1.0.0
extends: openapi/punchh-gift-cards-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['/api2/mobile/gift_cards/purchase'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a new gift card in the app
      effect: write
      questions:
      - How does a guest buy a brand-new gift card for themselves in the app?
      - Is there a minimum amount for purchasing a gift card?
      instructions:
      - text: Buy a {amount} gift card with design {design_id}.
        slots:
          amount: requestBody.amount
          design_id: requestBody.design_id
      - text: Purchase a {amount} gift card using saved card {transaction_token}.
        slots:
          amount: requestBody.amount
          transaction_token: requestBody.transaction_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/reload'].post
  update:
    x-apievangelist-phrasing:
      intent: Add funds to an existing gift card
      effect: write
      questions:
      - Can a guest top up the balance on a gift card they already have?
      - Can I reload a gift card using a saved payment card?
      instructions:
      - text: Reload gift card {uuid} with {amount}.
        slots:
          uuid: path.uuid
          amount: requestBody.amount
      - text: Top up gift card {uuid} by {amount} using saved card {transaction_token}.
        slots:
          uuid: path.uuid
          amount: requestBody.amount
          transaction_token: requestBody.transaction_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a physical gift card to the app
      effect: write
      questions:
      - How can a guest load a plastic gift card into their app wallet?
      - Does importing a physical card need its security PIN?
      instructions:
      - text: Import physical gift card {card_number} with PIN {epin}.
        slots:
          card_number: requestBody.card_number
          epin: requestBody.epin
      - text: Add my plastic gift card {card_number} to the app and name it {name}.
        slots:
          card_number: requestBody.card_number
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a gift card or set auto-reload
      effect: write
      questions:
      - Can a guest turn on auto-reload when their gift card balance gets low?
      - How do I make one gift card the preferred card in the app?
      instructions:
      - text: Rename gift card {uuid} to {name}.
        slots:
          uuid: path.uuid
          name: requestBody.name
      - text: 'Turn on auto-reload for gift card {uuid}: add {default_amount} when the balance drops below {threshold_amount}.'
        slots:
          uuid: path.uuid
          default_amount: requestBody.default_amount
          threshold_amount: requestBody.threshold_amount
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a gift card from the guest's app
      effect: destructive
      questions:
      - Can a guest hide a gift card from their app without deleting it from the system?
      - What does the business see after a guest removes a gift card?
      instructions:
      - text: Remove gift card {uuid} from my app.
        slots:
          uuid: path.uuid
      - text: Delete gift card {uuid} from the guest's wallet.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/'].get
  update:
    x-apievangelist-phrasing:
      intent: List a guest's active gift cards
      effect: read
      questions:
      - Which gift cards does the guest currently have in their app?
      - Is a passcode needed to see a guest's gift cards?
      instructions:
      - text: List my active gift cards using passcode {passcode}.
        slots:
          passcode: requestBody.passcode
      - text: Show all gift cards in the guest's wallet; passcode is {passcode}.
        slots:
          passcode: requestBody.passcode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/balance'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a gift card's balance
      effect: read
      questions:
      - How much money is left on a particular gift card?
      - Can I look up the current balance and details of one gift card?
      instructions:
      - text: Check the balance of gift card {uuid}.
        slots:
          uuid: path.uuid
      - text: How much is left on gift card {uuid}? Show me.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: View a gift card's transaction history
      effect: read
      questions:
      - Where can a guest see past purchases and reloads on a gift card?
      - Can I pull the transaction history of a single gift card?
      instructions:
      - text: Show the transaction history for gift card {uuid}.
        slots:
          uuid: path.uuid
      - text: List every charge and reload on gift card {uuid}.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/transfer'].post
  update:
    x-apievangelist-phrasing:
      intent: Transfer a gift card or part of its balance
      effect: write
      questions:
      - Can a guest send part of a gift card balance to a friend?
      - How do I hand over an entire gift card to another user by email?
      instructions:
      - text: Transfer {amount} from gift card {uuid} to {recipient_email}.
        slots:
          amount: requestBody.amount
          uuid: path.uuid
          recipient_email: requestBody.recipient_email
      - text: Give the whole gift card {uuid} to the user with phone {recipient_phone}.
        slots:
          uuid: path.uuid
          recipient_phone: requestBody.recipient_phone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/share'].post
  update:
    x-apievangelist-phrasing:
      intent: Share a gift card with another user
      effect: write
      questions:
      - Can two people use the same gift card from their own apps?
      - How does a guest share their gift card with a family member?
      instructions:
      - text: Share gift card {uuid} with {recipient_email}.
        slots:
          uuid: path.uuid
          recipient_email: requestBody.recipient_email
      - text: Let the user with phone {recipient_phone} use gift card {uuid} too.
        slots:
          recipient_phone: requestBody.recipient_phone
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/revoke'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop sharing a gift card with someone
      effect: destructive
      questions:
      - How do I take back access to a gift card I shared with someone?
      - Can a guest revoke another user's sharing rights on a gift card?
      instructions:
      - text: Revoke {sharer_email}'s access to gift card {uuid}.
        slots:
          sharer_email: requestBody.sharer_email
          uuid: path.uuid
      - text: Stop sharing gift card {uuid} with {sharer_email}.
        slots:
          uuid: path.uuid
          sharer_email: requestBody.sharer_email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/gift'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a gift card as a gift for someone
      effect: write
      questions:
      - Can a guest buy a gift card and send it straight to a friend?
      - What do I need to send someone a gift card by phone number?
      instructions:
      - text: Send a {amount} gift card to {recipient_email}.
        slots:
          amount: requestBody.amount
          recipient_email: requestBody.recipient_email
      - text: Gift a {amount} card with design {design_id} to phone {recipient_phone}.
        slots:
          amount: requestBody.amount
          design_id: requestBody.design_id
          recipient_phone: requestBody.recipient_phone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/consolidate'].patch
  update:
    x-apievangelist-phrasing:
      intent: Merge one gift card's balance into another
      effect: destructive
      questions:
      - Can a guest combine two gift cards into one balance?
      - What happens to the source gift card after its balance is consolidated?
      instructions:
      - text: Move the full balance of gift card {source_card} into gift card {uuid}.
        slots:
          source_card: requestBody.source_card
          uuid: path.uuid
      - text: Consolidate {source_card} into {uuid} for the user with token {access_token}.
        slots:
          source_card: requestBody.source_card
          uuid: path.uuid
          access_token: requestBody.access_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/tip'].post
  update:
    x-apievangelist-phrasing:
      intent: Leave a tip using a gift card
      effect: write
      questions:
      - Can a guest pay a tip on their order with a gift card?
      - Is a gift card tip limited by the card's balance?
      instructions:
      - text: Tip {tip} on check-in {checkin_id} using gift card {uuid}.
        slots:
          tip: requestBody.tip
          checkin_id: requestBody.checkin_id
          uuid: path.uuid
      - text: Leave a {tip} gratuity from gift card {uuid} for order {checkin_id}.
        slots:
          tip: requestBody.tip
          uuid: path.uuid
          checkin_id: requestBody.checkin_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/gift_cards/{uuid}/epin'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a gift card's EPIN
      effect: read
      questions:
      - Where does a guest find the security PIN for their digital gift card?
      - Does retrieving a gift card EPIN require the app passcode?
      instructions:
      - text: Show the EPIN for gift card {uuid}.
        slots:
          uuid: path.uuid
      - text: Get the security PIN of gift card {uuid} with passcode {passcode}.
        slots:
          uuid: path.uuid
          passcode: requestBody.passcode
      method: generated
      generated: '2026-10-01'