# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Punchh Auth API
  version: 1.0.0
extends: openapi/punchh-auth-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: 16
- target: $.paths['/api/auth/redemptions/online_order'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem a reward against an online order receipt
      effect: write
      questions:
      - How does an online ordering site apply a guest's reward or redemption code to a checkout under the older Redemptions 1.0 flow?
      - Which discount types can be redeemed against an online order receipt?
      instructions:
      - text: Redeem reward {reward_id} on online order {transaction_no} at store {store_number} for {receipt_amount} at {receipt_datetime}.
        slots:
          reward_id: requestBody.reward_id
          transaction_no: requestBody.transaction_no
          store_number: requestBody.store_number
          receipt_amount: requestBody.receipt_amount
          receipt_datetime: requestBody.receipt_datetime
      - text: Apply coupon code {redemption_code} as discount type {discount_type} to online order {transaction_no} at store {store_number}.
        slots:
          redemption_code: requestBody.redemption_code
          discount_type: requestBody.discount_type
          transaction_no: requestBody.transaction_no
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/redemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a redemption code to use at the POS
      effect: write
      questions:
      - How do I get a tracking code a guest can show at the register to redeem a reward?
      - Can a redemption code be created from banked currency instead of a specific reward?
      instructions:
      - text: Fetch a POS redemption code for reward {reward_id}.
        slots:
          reward_id: requestBody.reward_id
      - text: Generate a redemption code worth {redeemed_points} of banked currency at store {store_number}.
        slots:
          redeemed_points: requestBody.redeemed_points
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/redemptions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void a processed Redemptions 1.0 redemption
      effect: destructive
      questions:
      - Can I reverse a redemption that has already been processed and give the offer back to the guest?
      - Are there time limits on voiding a coupon or promo redemption?
      instructions:
      - text: Void processed redemption {redemption_id} because {reason}.
        slots:
          redemption_id: requestBody.redemption_id
          reason: requestBody.reason
      - text: Void the redemption tied to code {redemption_code} and return the offer to the guest.
        slots:
          redemption_code: requestBody.redemption_code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/redemptions/applicable_offers'].get
  update:
    x-apievangelist-phrasing:
      intent: List rewards that apply to an online check
      effect: read
      questions:
      - Which of the guest's rewards can be used on the items in this online order?
      - Does the ordering channel affect which rewards qualify for a check?
      instructions:
      - text: List rewards applicable to a {receipt_amount} check on channel {channel} placed at {receipt_datetime}.
        slots:
          receipt_amount: requestBody.receipt_amount
          channel: requestBody.channel
          receipt_datetime: requestBody.receipt_datetime
      - text: Show which rewards apply to this check at store {store_number}.
        slots:
          store_number: requestBody.store_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/discounts/auto_select'].post
  update:
    x-apievangelist-phrasing:
      intent: Auto-fill the discount basket for an order
      effect: write
      questions:
      - Can the best discount be queued in the guest's basket automatically when auto-redemption is on?
      - How does auto redemption decide which discount to pick for a check?
      instructions:
      - text: Auto-select discounts for a {receipt_amount} order at {receipt_datetime}.
        slots:
          receipt_amount: requestBody.receipt_amount
          receipt_datetime: requestBody.receipt_datetime
      - text: Run auto redemption on order {transaction_no} and lock the basket with {external_uid}.
        slots:
          transaction_no: requestBody.transaction_no
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/discounts/select'].post
  update:
    x-apievangelist-phrasing:
      intent: Add chosen discounts to the guest's basket
      effect: write
      questions:
      - How does an online ordering site add a guest's chosen reward to their discount basket?
      - Is a new discount basket created if the guest doesn't have an active one?
      instructions:
      - text: Add discounts {discount_basket_items_attributes} to the guest's online discount basket.
        slots:
          discount_basket_items_attributes: requestBody.discount_basket_items_attributes
      - text: Select discounts {discount_basket_items_attributes} into the basket locked by {external_uid}.
        slots:
          discount_basket_items_attributes: requestBody.discount_basket_items_attributes
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/discounts/unselect'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove discounts from the online discount basket
      effect: destructive
      questions:
      - Can a guest drop a reward from their discount basket before checking out online?
      - Do I need the lock ID to remove items from a locked discount basket?
      instructions:
      - text: Remove items {discount_basket_item_ids} from the guest's discount basket.
        slots:
          discount_basket_item_ids: requestBody.discount_basket_item_ids
      - text: Unselect basket items {discount_basket_item_ids} using lock {external_uid}.
        slots:
          discount_basket_item_ids: requestBody.discount_basket_item_ids
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/discounts/active'].get
  update:
    x-apievangelist-phrasing:
      intent: View the guest's current discount basket
      effect: read
      questions:
      - What rewards has the guest already put in their discount basket?
      - Will an expired discount still show up in the active basket?
      instructions:
      - text: Show the guest's active discount basket.
      - text: Get the active discount basket locked with {external_uid}.
        slots:
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/batch_redemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit the discount basket against a receipt
      effect: write
      questions:
      - How do I finalize all the discounts in a guest's basket when the order is placed?
      - Can I preview possible redemptions before committing the batch?
      instructions:
      - text: 'Commit the batch redemption for order {transaction_no} at store {store_number}: {line_items}, {receipt_amount} at {receipt_datetime}.'
        slots:
          transaction_no: requestBody.transaction_no
          store_number: requestBody.store_number
          line_items: requestBody.line_items
          receipt_amount: requestBody.receipt_amount
          receipt_datetime: requestBody.receipt_datetime
      - text: Process the discount basket redemption at store {store_number} for line items {line_items}.
        slots:
          store_number: requestBody.store_number
          line_items: requestBody.line_items
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/batch_redemptions/{redemption_ref}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void an entire discount basket redemption
      effect: destructive
      questions:
      - How do I void every discount redeemed in a Redemptions 2.0 basket at once?
      - Where do I get the redemption reference needed to void a batch?
      instructions:
      - text: Void the whole discount basket with reference {redemption_ref}.
        slots:
          redemption_ref: path.redemption_ref
      - text: Reverse batch redemption {redemption_ref} for the guest.
        slots:
          redemption_ref: path.redemption_ref
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/discounts/unlock'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlock a locked discount basket
      effect: write
      questions:
      - How do I release a guest's discount basket that another channel locked?
      - What does it mean when a discount basket is locked by reward locking?
      instructions:
      - text: Unlock the discount basket held by {external_uid}.
        slots:
          external_uid: requestBody.external_uid
      - text: Release the basket lock {external_uid} so other channels can edit it.
        slots:
          external_uid: requestBody.external_uid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscription plans for sale online
      effect: read
      questions:
      - What subscription plans can my online ordering site offer for purchase?
      - Which plans are currently purchasable for this business?
      instructions:
      - text: List the subscription plans available to purchase online.
      - text: Show the purchasable plans for client {client}.
        slots:
          client: requestBody.client
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a subscription plan for a signed-in guest
      effect: write
      questions:
      - How does an online ordering vendor purchase a subscription for a guest?
      - Can a guest pay for a subscription with a saved card?
      instructions:
      - text: Purchase plan {plan_id} for {purchase_price} from {start_time} to {end_time}, auto renew {auto_renewal}, for guest token {authentication_token}.
        slots:
          plan_id: requestBody.plan_id
          purchase_price: requestBody.purchase_price
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          auto_renewal: requestBody.auto_renewal
          authentication_token: requestBody.authentication_token
      - text: Buy subscription plan {plan_id} with 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['/api/auth/subscriptions/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel a guest's subscription renewal online
      effect: destructive
      questions:
      - How can a guest turn off auto renewal for a subscription from the ordering site?
      - Can the guest choose between a soft and hard cancellation?
      instructions:
      - text: Cancel subscription {subscription_id} as {cancellation_type} with reason {cancellation_reason_id} and feedback {cancellation_feedback}.
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_type: requestBody.cancellation_type
          cancellation_reason_id: requestBody.cancellation_reason_id
          cancellation_feedback: requestBody.cancellation_feedback
      - text: 'Soft-cancel subscription {subscription_id} using reason {cancellation_reason_id}; feedback: {cancellation_feedback}; type {cancellation_type}.'
        slots:
          subscription_id: requestBody.subscription_id
          cancellation_reason_id: requestBody.cancellation_reason_id
          cancellation_feedback: requestBody.cancellation_feedback
          cancellation_type: requestBody.cancellation_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/user_subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a guest's subscriptions
      effect: read
      questions:
      - Which subscriptions are attached to this guest's profile?
      - Can I include past subscriptions when listing a guest's plans?
      instructions:
      - text: Show the subscriptions held by the guest.
      - text: List the guest's subscriptions with filter {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/auth/subscription_meta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get subscription cancellation reasons
      effect: read
      questions:
      - What cancellation reasons can a guest pick from when ending a subscription?
      - Why would subscription meta return no cancellation reasons?
      instructions:
      - text: Get the configured subscription cancellation reasons.
      - text: Fetch subscription meta for client {client}.
        slots:
          client: requestBody. client
      method: generated
      generated: '2026-10-01'