# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Punchh Api2 API
  version: 1.0.0
extends: openapi/punchh-api2-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: 33
- target: $.paths['/api2/mobile/redemptions/{redemption_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel an unprocessed redemption from the app
      effect: destructive
      questions:
      - Can a guest cancel a redemption code in the mobile app before it has been used at the store?
      - What happens if I try to cancel a redemption that was already processed?
      instructions:
      - text: Cancel mobile redemption {redemption_id} so the guest can pick a different reward.
        slots:
          redemption_id: path.redemption_id
      - text: Withdraw the unprocessed redemption {redemption_id} for app client {client}.
        slots:
          redemption_id: path.redemption_id
          client: requestBody.client
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/banked_currency'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem banked currency for a redemption code
      effect: write
      questions:
      - How can a guest turn part of their banked currency balance into a redemption code?
      - Does a banked-currency redemption need a store location, or will it work without one?
      instructions:
      - text: Create a redemption code worth {banked_currency} of banked currency for the signed-in guest.
        slots:
          banked_currency: requestBody.banked_currency
      - text: Generate a banked currency redemption of {banked_currency} at location {location_id}.
        slots:
          banked_currency: requestBody.banked_currency
          location_id: requestBody.location_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/visits'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem a completed visit card
      effect: write
      questions:
      - In a visit-based loyalty program, how does a guest redeem a completed punch card from the app?
      - Can I create a visits redemption using GPS coordinates instead of a location ID?
      instructions:
      - text: Redeem the guest's unredeemed visit card at location {location_id}.
        slots:
          location_id: requestBody.location_id
      - text: Create a visits-based redemption near latitude {latitude} and longitude {longitude}.
        slots:
          latitude: requestBody.latitude
          longitude: requestBody.longitude
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/redeemable'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem loyalty points for a redeemable
      effect: write
      questions:
      - How does a guest spend loyalty points on a specific redeemable item from the catalog?
      - Which redeemable will a points redemption code be tied to?
      instructions:
      - text: Spend the guest's points on redeemable {reedemable_id} and give me the redemption code.
        slots:
          reedemable_id: requestBody.reedemable_id
      - text: Create a points redemption for redeemable {reedemable_id} at store {location_id}.
        slots:
          reedemable_id: requestBody.reedemable_id
          location_id: requestBody.location_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/reward'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem a reward a guest was given
      effect: write
      questions:
      - How do I generate a redemption code for a reward the guest received from a campaign?
      - Can a gifted reward be redeemed at a particular store location from the app?
      instructions:
      - text: Create a redemption code for reward {reward_id} in the guest's account.
        slots:
          reward_id: requestBody.reward_id
      - text: Redeem gifted reward {reward_id} at location {location_id}.
        slots:
          reward_id: requestBody.reward_id
          location_id: requestBody.location_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/applicable_offers'].get
  update:
    x-apievangelist-phrasing:
      intent: List offers that apply to a cart in the app
      effect: read
      questions:
      - Which offers can a guest apply to the items currently in their mobile order?
      - Do the applicable offers depend on the ordering channel and order amount?
      instructions:
      - text: Show the offers that apply to a {amount} order placed through {channel}.
        slots:
          amount: requestBody.amount
          channel: requestBody.channel
      - text: List applicable offers for this cart at store {location_id} on channel {channel}.
        slots:
          location_id: requestBody.location_id
          channel: requestBody.channel
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/discounts/select'].post
  update:
    x-apievangelist-phrasing:
      intent: Add discounts to the guest's discount basket
      effect: write
      questions:
      - How does the mobile app add a reward to the guest's discount basket?
      - What happens if the guest has no active discount basket when selecting a discount?
      instructions:
      - text: Add these discounts {discount_basket_items_attributes} to the guest's discount basket in the app.
        slots:
          discount_basket_items_attributes: requestBody.discount_basket_items_attributes
      - text: Put the selected rewards into the mobile discount basket.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/discounts/unselect'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove discounts from the discount basket
      effect: destructive
      questions:
      - Can a guest take a discount back out of their basket in the app?
      - Is it possible to remove several discount basket items at once?
      instructions:
      - text: Remove basket items {discount_basket_item_ids} from the guest's discount basket.
        slots:
          discount_basket_item_ids: requestBody.discount_basket_item_ids
      - text: Unselect discount basket item {discount_basket_item_ids} in the mobile app.
        slots:
          discount_basket_item_ids: requestBody.discount_basket_item_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/discounts/active'].get
  update:
    x-apievangelist-phrasing:
      intent: Show the guest's active discount basket
      effect: read
      questions:
      - What discounts has the guest currently selected in their basket?
      - Are expired discounts dropped from the active discount basket automatically?
      instructions:
      - text: Show me what's in the guest's active discount basket.
      - text: Fetch the current discount basket for app client {client}.
        slots:
          client: requestBody.client
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/single_scan_tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a single-scan code to pay and redeem
      effect: write
      questions:
      - How can a guest pay, earn and redeem with one scan at the register?
      - Can the single-scan code include a tip or use a gift card as the payment method?
      instructions:
      - text: Generate a single-scan access code paid by {payment_type}.
        slots:
          payment_type: requestBody.payment_type
      - text: Create a single-scan code using gift card {gift_card_uuid} with a tip of {tip}.
        slots:
          gift_card_uuid: requestBody.gift_card_uuid
          tip: requestBody.tip
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscription plans available to buy
      effect: read
      questions:
      - What subscription plans can guests buy in the mobile app right now?
      - Are expired subscription plans hidden from the purchasable list?
      instructions:
      - text: List the active subscription plans guests can purchase in the app.
      - text: Show purchasable subscription plans for client {client}.
        slots:
          client: requestBody.client
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a subscription plan for the signed-in guest
      effect: write
      questions:
      - How does a guest purchase a subscription plan from the mobile app?
      - Why would buying a single-use plan with auto renewal turned on fail?
      instructions:
      - text: Purchase plan {plan_id} for {purchase_price} at location {location_id}, starting {start_time} and ending {end_time}, auto renew {auto_renewal}.
        slots:
          plan_id: requestBody.plan_id
          purchase_price: requestBody.purchase_price
          location_id: requestBody.location_id
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          auto_renewal: requestBody.auto_renewal
      - text: Subscribe the guest to plan {plan_id} using saved card {payment_card_uuid}.
        slots:
          plan_id: requestBody.plan_id
          payment_card_uuid: requestBody.payment_card_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/user_subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the subscriptions a guest holds
      effect: read
      questions:
      - Which subscriptions does this guest currently have on their profile?
      - Can I see a guest's past or cancelled subscriptions, not just the active ones?
      instructions:
      - text: Show the guest's current subscriptions.
      - text: List the guest's subscriptions filtered by {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/redemptions/subscription'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a code to use a subscription benefit
      effect: write
      questions:
      - How does a guest get a code to redeem their subscription perk at the POS or online?
      - Can a subscription benefit be redeemed with a code generated in the app?
      instructions:
      - text: Generate a redemption code for subscription {subscription_id}.
        slots:
          subscription_id: requestBody.subscription_id
      - text: Give the guest a code to use the benefits of subscription {subscription_id}.
        slots:
          subscription_id: requestBody.subscription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/subscriptions/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn off a guest's subscription auto renewal
      effect: destructive
      questions:
      - How can a guest stop their subscription from renewing in the app?
      - Do benefits stay active until the end date after a guest cancels from the app?
      instructions:
      - text: Cancel auto renewal on subscription {subscription_id} with reason {cancellation_reason_id} and feedback {cancellation_feedback}.
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_reason_id: requestBody.cancellation_reason_id
          cancellation_feedback: requestBody.cancellation_feedback
      - text: Stop subscription {subscription_id} from renewing because of reason {cancellation_reason_id}; the guest said {cancellation_feedback}.
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_reason_id: requestBody.cancellation_reason_id
          cancellation_feedback: requestBody.cancellation_feedback
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse audience segments for an external platform
      effect: read
      questions:
      - Which guest segments are defined in Punchh that my marketing tool can target?
      - Can I search segments by name and page through them?
      instructions:
      - text: List the segments whose name matches {query}.
        slots:
          query: requestBody.query
      - text: Show page {page} of segments with {per_page} per page.
        slots:
          page: requestBody.page
          per_page: requestBody.per_page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/redeemables'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse offers to send from an external platform
      effect: read
      questions:
      - What offers can my external campaign tool pick from to send to guests?
      - Does the offer search look at descriptions as well as names?
      instructions:
      - text: Find offers whose name or description mentions {query} for my campaign tool.
        slots:
          query: requestBody.query
      - text: Browse page {page} of campaign-ready offers, {per_page} at a time.
        slots:
          page: requestBody.page
          per_page: requestBody.per_page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/campaigns'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule a mass offer campaign to a segment
      effect: write
      questions:
      - How can an external platform have Punchh deliver an offer to everyone in a segment?
      - Which campaign types are supported for mass gifting right now?
      instructions:
      - text: Schedule campaign {name} gifting redeemable {redeemable_uuid} to segment {segment_id} as {category} via {campaign_type}, starting {start_time}.
        slots:
          name: requestBody.name
          redeemable_uuid: requestBody.redeemable_uuid
          segment_id: requestBody.segment_id
          category: requestBody.category
          campaign_type: requestBody.campaign_type
          start_time: requestBody.start_time
      - text: Mass-gift offer {redeemable_uuid} to segment {segment_id} and tag it with external campaign {external_campaign_id}.
        slots:
          redeemable_uuid: requestBody.redeemable_uuid
          segment_id: requestBody.segment_id
          external_campaign_id: requestBody.external_campaign_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/users/support_gifting'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue a background support gift to a guest
      effect: write
      questions:
      - What's the best way to send high volumes of support gifts without waiting on each one?
      - Is there an asynchronous way to gift points or rewards to many guests one by one?
      instructions:
      - text: Queue an asynchronous gift of {gift_count} points to user {user_id}.
        slots:
          gift_count: requestBody.gift_count
          user_id: requestBody.user_id
      - text: In the background, gift redeemable {redeemable_id} to user {user_id} because {gift_reason}.
        slots:
          redeemable_id: requestBody.redeemable_id
          user_id: requestBody.user_id
          gift_reason: requestBody.gift_reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/users/support'].post
  update:
    x-apievangelist-phrasing:
      intent: Gift a guest points, rewards or challenge progress
      effect: write
      questions:
      - How can a support agent immediately make things right with a guest by gifting points or a reward?
      - Can I gift fuel or progress toward a challenge to a single guest?
      instructions:
      - text: Right now, gift {reward_amount} in currency to user {user_id} with the message {message}.
        slots:
          reward_amount: requestBody.reward_amount
          user_id: requestBody.user_id
          message: requestBody.message
      - text: Give user {user_id} {progress_count} steps on challenge {challenge_campaign_id}.
        slots:
          user_id: requestBody.user_id
          progress_count: requestBody.progress_count
          challenge_campaign_id: requestBody.challenge_campaign_id
      - text: Gift {fuel_amount} of fuel to user {user_id}.
        slots:
          fuel_amount: requestBody.fuel_amount
          user_id: requestBody.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/lis'].get
  update:
    x-apievangelist-phrasing:
      intent: List line item selectors
      effect: read
      questions:
      - Which line item selectors are defined for my business's offers?
      - Does listing line item selectors require offers ingestion to be enabled?
      instructions:
      - text: List line item selectors named like {query}.
        slots:
          query: requestBody.query
      - text: Show page {page} of line item selectors.
        slots:
          page: requestBody.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/lis'].post
  update:
    x-apievangelist-phrasing:
      intent: Create line item selectors in bulk
      effect: write
      questions:
      - How many line item selectors can I create in a single request?
      - How do I define which menu items an offer applies to?
      instructions:
      - text: 'Create these new line item selectors: {data}.'
        slots:
          data: requestBody.data
      - text: Add up to 20 new line item selectors from {data}.
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/lis'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update existing line item selectors
      effect: write
      questions:
      - Can I edit line item selectors that already exist in bulk?
      - What's the limit on line item selectors per update call?
      instructions:
      - text: Update the existing line item selectors with {data}.
        slots:
          data: requestBody.data
      - text: 'Apply these changes to my current line item selectors: {data}.'
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/qc'].get
  update:
    x-apievangelist-phrasing:
      intent: List qualification criteria
      effect: read
      questions:
      - What qualification criteria rules are set up for my offers?
      - Can I search qualification criteria by name?
      instructions:
      - text: List qualification criteria whose name contains {query}.
        slots:
          query: requestBody.query
      - text: Show page {page} of qualification criteria, {per_page} per page.
        slots:
          page: requestBody.page
          per_page: requestBody.per_page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/qc'].post
  update:
    x-apievangelist-phrasing:
      intent: Create qualification criteria in bulk
      effect: write
      questions:
      - How do I define the conditions a check must meet for an offer to apply?
      - What happens if I send more than 20 qualification criteria at once?
      instructions:
      - text: Create new qualification criteria from {data}.
        slots:
          data: requestBody.data
      - text: 'Define these offer qualification rules: {data}.'
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/qc'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update existing qualification criteria
      effect: write
      questions:
      - Can I change qualification criteria that were already created?
      - Do updates to qualification criteria go through the same validations as creating them?
      instructions:
      - text: Update existing qualification criteria with {data}.
        slots:
          data: requestBody.data
      - text: Edit my current offer qualification rules using {data}.
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/redeemable'].get
  update:
    x-apievangelist-phrasing:
      intent: List redeemables for offers ingestion
      effect: read
      questions:
      - Which redeemables are defined at the business level for offers ingestion?
      - Can I search offers-ingestion redeemables by name only?
      instructions:
      - text: List offers-ingestion redeemables named like {query}.
        slots:
          query: requestBody.query
      - text: Show offers-ingestion redeemables page {page} with {per_page} per page.
        slots:
          page: requestBody.page
          per_page: requestBody.per_page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/redeemable'].post
  update:
    x-apievangelist-phrasing:
      intent: Create redeemables in bulk
      effect: write
      questions:
      - How do I define new redeemables for my loyalty program through the API?
      - Is there a cap on how many redeemables I can create per call?
      instructions:
      - text: 'Create these new redeemables: {data}.'
        slots:
          data: requestBody.data
      - text: Bulk-define up to 20 redeemables from {data}.
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/redeemable'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update existing redeemables
      effect: write
      questions:
      - Can I modify redeemables that already exist in bulk?
      - How many existing redeemables can a single update touch?
      instructions:
      - text: Update the existing redeemables with {data}.
        slots:
          data: requestBody.data
      - text: 'Change the details of my current redeemables: {data}.'
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/offers/upload_redeemable_image'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload images for redeemables from URLs
      effect: write
      questions:
      - How do I add pictures to my redeemables in bulk?
      - What's the maximum image size for a redeemable image?
      instructions:
      - text: 'Upload redeemable images from these URLs: {data}.'
        slots:
          data: requestBody.data
      - text: Attach the hosted images {data} to their redeemables.
        slots:
          data: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/subscriptions/purchase'].post
  update:
    x-apievangelist-phrasing:
      intent: Purchase or migrate a subscription for a guest
      effect: write
      questions:
      - Can a back-end system buy a subscription for a guest who isn't logged in?
      - How do I migrate a guest's active subscription from a previous loyalty system?
      instructions:
      - text: Purchase plan {plan_id} for user {user_id} at {purchase_price} at location {location_id}, from {start_time} to {end_time}, auto renew {auto_renewal}.
        slots:
          plan_id: requestBody.plan_id
          user_id: requestBody.user_id
          purchase_price: requestBody.purchase_price
          location_id: requestBody.location_id
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          auto_renewal: requestBody.auto_renewal
      - text: Migrate user {user_id}'s existing subscription to plan {plan_id} with {initial_savings} in prior savings.
        slots:
          user_id: requestBody.user_id
          plan_id: requestBody.plan_id
          initial_savings: requestBody.initial_savings
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/subscriptions/renew'].post
  update:
    x-apievangelist-phrasing:
      intent: Renew a guest's subscription
      effect: write
      questions:
      - How does the business renew a guest's subscription on its renewal date?
      - Can a guest switch to a different plan when their subscription renews?
      instructions:
      - text: Renew subscription {subscription_id} for {purchase_price} from {start_time} to {end_time}.
        slots:
          subscription_id: requestBody.subscription_id
          purchase_price: requestBody.purchase_price
          start_time: requestBody.start_time
          end_time: requestBody.end_time
      - text: Renew subscription {subscription_id} onto new plan {new_plan_id}.
        slots:
          subscription_id: requestBody.subscription_id
          new_plan_id: requestBody.new_plan_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/subscriptions/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel a guest subscription as an admin
      effect: destructive
      questions:
      - How can an admin hard-cancel a guest's subscription immediately?
      - What's the difference between a soft and hard cancellation from the dashboard?
      instructions:
      - text: Admin-cancel subscription {subscription_id} as {cancellation_type} because {cancellation_reason}.
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_type: requestBody.cancellation_type
          cancellation_reason: requestBody.cancellation_reason
      - text: From the dashboard, hard-cancel subscription {subscription_id} with reason {cancellation_reason} and type {cancellation_type}.
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_reason: requestBody.cancellation_reason
          cancellation_type: requestBody.cancellation_type
      method: generated
      generated: '2026-10-01'