# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Talon One Loyalty API
  version: 1.0.0
extends: openapi/talon-one-loyalty-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 24
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's loyalty balances in real time
      effect: read
      questions:
      - How many active and pending points does this shopper have right now, from my storefront integration?
      - Can the real-time balance lookup also tell me the customer's current and projected tier?
      - What would a customer's points balance have been as of a past end date in a given subledger?
      instructions:
      - text: Show the real-time loyalty balance for customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Get customer {integrationId}'s Integration API balance in program {loyaltyProgramId} as of {endDate}, including tier details.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's loyalty transactions in real time
      effect: read
      questions:
      - Where can my app show a shopper their recent points earned and spent, straight from the Integration API?
      - Which loyalty transactions did a customer make between two dates in a specific subledger?
      - Can I see only the points transactions still waiting for activation for one customer profile?
      instructions:
      - text: List the latest Integration API loyalty transactions for customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show customer {integrationId}'s real-time points transactions in program {loyaltyProgramId} from {startDate} to {endDate}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/delete_transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a customer's loyalty transactions
      effect: destructive
      questions:
      - How do I wipe a customer's loyalty transaction history across every ledger in a program?
      - Can I erase a shopper's points transactions from just one subledger instead of all of them?
      instructions:
      - text: Delete all loyalty transactions for customer {integrationId} in program {loyaltyProgramId} with scope {scope}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          scope: requestBody.scope
      - text: Remove customer {integrationId}'s transactions from subledgers {subledgerIds} of loyalty program {loyaltyProgramId}, scope {scope}.
        slots:
          integrationId: path.integrationId
          subledgerIds: requestBody.subledgerIds
          loyaltyProgramId: path.loyaltyProgramId
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/join'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll a customer in a loyalty program
      effect: write
      questions:
      - How do I sign a customer up for my profile-based loyalty program?
      - Will enrolling a shopper in a loyalty program create their customer profile if it doesn't exist yet?
      instructions:
      - text: Enroll customer {integrationId} in loyalty program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Join profile {integrationId} to loyalty program {loyaltyProgramId}, creating the profile if needed.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/points'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's unused loyalty points
      effect: read
      questions:
      - Which of a customer's unused points are active, pending or expiring soon?
      - Can I list the individual unspent point batches on a customer profile rather than just a total?
      instructions:
      - text: List the unused points batches for customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show customer {integrationId}'s unspent points with status {status} in loyalty program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          status: query.status
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/activate_points'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate pending loyalty points
      effect: write
      questions:
      - How do I turn pending points into spendable points once an order ships?
      - Can I activate all the points a customer earned in one session at once?
      instructions:
      - text: Activate the pending points earned in session {sessionId} in loyalty program {loyaltyProgramId}.
        slots:
          sessionId: requestBody.sessionId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Activate pending points from transactions {transactionUUIDs} in program {loyaltyProgramId}.
        slots:
          transactionUUIDs: requestBody.transactionUUIDs
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's loyalty balances for back-office use
      effect: read
      questions:
      - Is there a Management API version of the customer points balance lookup for back-office tools?
      - Can an admin dashboard pull a customer's ledger balances and tier info outside the real-time integration?
      instructions:
      - text: Using the Management API, get the ledger balances of customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Pull back-office balances for customer {integrationId} in loyalty program {loyaltyProgramId} for subledger {subledgerId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          subledgerId: query.subledgerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's loyalty transactions for back-office use
      effect: read
      questions:
      - Can an admin tool list a customer's points transactions through the Management API instead of the Integration API?
      - For a support agent, is there a back-office way to filter a customer's transactions by main ledger or subledger?
      instructions:
      - text: Via the Management API, list ledger transactions for customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show back-office transaction logs for customer {integrationId} in program {loyaltyProgramId} of type {loyaltyTransactionType}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          loyaltyTransactionType: query.loyaltyTransactionType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs'].get
  update:
    x-apievangelist-phrasing:
      intent: List loyalty programs
      effect: read
      questions:
      - What loyalty programs exist in my Talon.One account?
      - Where can I find the IDs of all my loyalty programs?
      instructions:
      - text: List all loyalty programs in my account.
      - text: Show me every loyalty program and its ID.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty program's details
      effect: read
      questions:
      - How is a particular loyalty program configured?
      - Can I look up one loyalty program's settings by its ID?
      instructions:
      - text: Get the configuration of loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show details for loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/dashboard'].get
  update:
    x-apievangelist-phrasing:
      intent: Get loyalty dashboard statistics for a date range
      effect: read
      questions:
      - How many points were active, pending, spent and expired in my loyalty program last month?
      - Does the loyalty dashboard data include today's activity?
      - Can I break loyalty dashboard numbers down by subledger?
      instructions:
      - text: Get dashboard statistics for loyalty program {loyaltyProgramId} from {rangeStart} to {rangeEnd}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
      - text: Show points activity for subledger {subledgerId} of program {loyaltyProgramId} between {rangeStart} and {rangeEnd}.
        slots:
          subledgerId: query.subledgerId
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/import_points'].post
  update:
    x-apievangelist-phrasing:
      intent: Import loyalty points from a CSV file
      effect: write
      questions:
      - How do I bulk-load points balances from my old loyalty system with a CSV?
      - Can I import points in bulk without sending customers a notification?
      instructions:
      - text: Import the points CSV {upFile} into loyalty program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      - text: Bulk-upload points file {upFile} to program {loyaltyProgramId} with notifications set to {notificationsEnabled}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
          notificationsEnabled: query.notificationsEnabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/import_customers_tiers'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign customers to loyalty tiers from a CSV
      effect: write
      questions:
      - Can I move existing customers into specific tiers in bulk using a spreadsheet?
      - Which loyalty programs support importing customer tier assignments?
      instructions:
      - text: Import the customer tier assignments in {upFile} into loyalty program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      - text: Upload tier CSV {upFile} to place customers in tiers of program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/import_join_dates'].post
  update:
    x-apievangelist-phrasing:
      intent: Import customers' loyalty join dates from a CSV
      effect: write
      questions:
      - How do I preserve members' original sign-up dates when migrating a loyalty program?
      - Can I set the join date for many customer profiles at once?
      instructions:
      - text: Import join dates from {upFile} into loyalty program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      - text: Upload the member join-date CSV {upFile} for program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's full loyalty ledger
      effect: read
      questions:
      - Can I see a customer's complete points ledger, not just the balance?
      - What does a member's entire loyalty ledger look like in one program?
      instructions:
      - text: Get the full loyalty ledger for customer {integrationId} in program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show me every ledger entry customer {integrationId} has in loyalty program {loyaltyProgramId}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/add_points'].put
  update:
    x-apievangelist-phrasing:
      intent: Add loyalty points to a customer profile
      effect: write
      questions:
      - How do I give a customer bonus points as a goodwill gesture?
      - Can manually added points start as pending or expire after a set duration?
      instructions:
      - text: Add {points} points to customer {integrationId} in loyalty program {loyaltyProgramId}.
        slots:
          points: requestBody.points
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Credit customer {integrationId} with {points} points in program {loyaltyProgramId}, valid until {validUntil}, reason {name}.
        slots:
          integrationId: path.integrationId
          points: requestBody.points
          loyaltyProgramId: path.loyaltyProgramId
          validUntil: requestBody.validUntil
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/deduct_points'].put
  update:
    x-apievangelist-phrasing:
      intent: Deduct loyalty points from a customer profile
      effect: write
      questions:
      - How do I take points back from a customer's profile after a return?
      - Can I deduct pending points, or only active ones?
      instructions:
      - text: Deduct {points} points from customer {integrationId} in loyalty program {loyaltyProgramId}.
        slots:
          points: requestBody.points
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Remove {points} active points from profile {integrationId} in program {loyaltyProgramId} with reason {name}.
        slots:
          points: requestBody.points
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/export_log'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a customer's loyalty transactions to CSV
      effect: read
      questions:
      - Can I download one customer's points history as a CSV file?
      - How do I export a single member's loyalty transaction log for a date range?
      instructions:
      - text: Export customer {integrationId}'s loyalty log in program {loyaltyProgramId} from {rangeStart} to {rangeEnd} as CSV.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
      - text: Download customer {integrationId}'s points ledger CSV for program {loyaltyProgramId} between {rangeStart} and {rangeEnd} using date format {dateFormat}.
        slots:
          integrationId: path.integrationId
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
          dateFormat: query.dateFormat
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/export_join_dates'].get
  update:
    x-apievangelist-phrasing:
      intent: Export customers' loyalty join dates to CSV
      effect: read
      questions:
      - When did each member join my loyalty program?
      - Can I download a CSV of every customer's enrollment date?
      instructions:
      - text: Export the join dates of all members of loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Download a CSV of when each customer joined program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/export_customers_tiers'].get
  update:
    x-apievangelist-phrasing:
      intent: Export customers' loyalty tier data to CSV
      effect: read
      questions:
      - Which tier is each of my loyalty members in right now?
      - Can I export tier data only for certain tier names or subledgers?
      instructions:
      - text: Export the customer tier data for loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Download a CSV of customers in tiers {tierNames} of program {loyaltyProgramId}.
        slots:
          tierNames: query.tierNames
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/statistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get loyalty program statistics (deprecated)
      effect: read
      questions:
      - Is the older loyalty program statistics endpoint still available even though it's deprecated?
      - What overall totals did the legacy loyalty statistics call return for a program?
      instructions:
      - text: Get the legacy statistics for loyalty program {loyaltyProgramId} using the deprecated endpoint.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Call the deprecated loyalty statistics endpoint for program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/export_customer_balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Export all customers' loyalty balances to CSV
      effect: read
      questions:
      - How can I get a spreadsheet of every member's points balance?
      - Can I export customer balances as they stood on a specific end date?
      instructions:
      - text: Export every customer's balance in loyalty program {loyaltyProgramId} to CSV.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Export customer balances for program {loyaltyProgramId} as of {endDate}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/export_customer_balance'].get
  update:
    x-apievangelist-phrasing:
      intent: Export customer loyalty balances (legacy endpoint)
      effect: read
      questions:
      - Does the older singular export_customer_balance endpoint still produce a balances CSV?
      - What does the legacy customer-balance export return compared with its replacement?
      instructions:
      - text: Use the legacy single-balance export to download balances for loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Run the older export_customer_balance download for program {loyaltyProgramId} as of {endDate}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List all transactions in a loyalty program
      effect: read
      questions:
      - What points transactions happened across my whole loyalty program this week?
      - Are manual and imported transactions included when I list a program's activity?
      instructions:
      - text: List recent transactions across all members of loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show program-wide {loyaltyTransactionType} transactions in program {loyaltyProgramId} since {startDate}.
        slots:
          loyaltyTransactionType: query.loyaltyTransactionType
          loyaltyProgramId: path.loyaltyProgramId
          startDate: query.startDate
      method: generated
      generated: '2026-09-26'