# 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 cards API
  version: 1.0.0
extends: openapi/talon-one-loyalty-cards-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: 19
- target: $.paths['/v2/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/link_profile'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a customer profile to a loyalty card
      effect: write
      questions:
      - How do I register a physical loyalty card to a customer's account?
      - Can a shopper attach an anonymous loyalty card to their profile after signing up?
      instructions:
      - text: Link customer {integrationId} to loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          integrationId: requestBody.integrationId
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Register card {loyaltyCardId} to profile {integrationId} in card-based program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          integrationId: requestBody.integrationId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/unlink_profile'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink a customer profile from a loyalty card
      effect: write
      questions:
      - How do I detach a customer from a loyalty card they no longer use?
      - Can I remove one profile from a card that's shared by several customers?
      instructions:
      - text: Unlink customer {integrationId} from loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          integrationId: requestBody.integrationId
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Detach profile {integrationId} from card {loyaltyCardId} of program {loyaltyProgramId}.
        slots:
          integrationId: requestBody.integrationId
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty card's point balances
      effect: read
      questions:
      - How many points are on a customer's loyalty card right now?
      - Can I check a card's balance in one subledger as of a past date?
      instructions:
      - text: Get the points balance of loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show card {loyaltyCardId}'s balance in subledger {subledgerId} of program {loyaltyProgramId} as of {endDate}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          subledgerId: query.subledgerId
          loyaltyProgramId: path.loyaltyProgramId
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a loyalty card's transactions in real time
      effect: read
      questions:
      - Where can my checkout app show the latest points earned and spent on a card, via the Integration API?
      - Can I see only a card's redemption transactions within a date range?
      instructions:
      - text: List the real-time transactions on loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show Integration API {loyaltyTransactionType} transactions for card {loyaltyCardId} in program {loyaltyProgramId} since {startDate}.
        slots:
          loyaltyTransactionType: query.loyaltyTransactionType
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          startDate: query.startDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/points'].get
  update:
    x-apievangelist-phrasing:
      intent: List a loyalty card's unused points
      effect: read
      questions:
      - Which point batches on a loyalty card are still unspent, and when do they expire?
      - Can I list only the pending points on a card?
      instructions:
      - text: List the unused points on loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show card {loyaltyCardId}'s unspent points with status {status} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          status: query.status
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards'].get
  update:
    x-apievangelist-phrasing:
      intent: List loyalty cards in a program
      effect: read
      questions:
      - Which loyalty cards have been issued in my card-based program?
      - Can I find all cards belonging to one batch or linked to one customer profile?
      instructions:
      - text: List the loyalty cards in program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Find cards in program {loyaltyProgramId} from batch {batchId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          batchId: query.batchId
      - text: Search program {loyaltyProgramId} for a card whose identifier contains {identifier}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          identifier: query.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a single loyalty card
      effect: write
      questions:
      - How do I issue one new loyalty card on demand when a customer signs up in store?
      - Can a newly generated card be linked to customer profiles right away?
      instructions:
      - text: Generate one new loyalty card in program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Generate a card in program {loyaltyProgramId} linked to customers {customerProfileIds}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
          customerProfileIds: requestBody.customerProfileIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/import_cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Import loyalty cards from a CSV file
      effect: write
      questions:
      - How do I bring my existing physical card numbers into a card-based program?
      - What columns does the loyalty card import file need?
      instructions:
      - text: Import the loyalty cards in {upFile} into program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      - text: Upload card CSV {upFile} to card-based program {loyaltyProgramId}.
        slots:
          upFile: requestBody.upFile
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a batch of loyalty cards
      effect: write
      questions:
      - Can I mint thousands of loyalty card codes at once for a print run?
      - How do I control the code format when creating cards in bulk?
      instructions:
      - text: Create {numberOfCards} loyalty cards in program {loyaltyProgramId}.
        slots:
          numberOfCards: requestBody.numberOfCards
          loyaltyProgramId: path.loyaltyProgramId
      - text: Create a batch {batchId} of {numberOfCards} cards in program {loyaltyProgramId}.
        slots:
          batchId: requestBody.batchId
          numberOfCards: requestBody.numberOfCards
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/export_card_balances'].get
  update:
    x-apievangelist-phrasing:
      intent: Export balances of all loyalty cards to CSV
      effect: read
      questions:
      - How do I get a spreadsheet of every card's points balance in a program?
      - Can I export all card balances as of a specific end date?
      instructions:
      - text: Export the balances of every card in loyalty program {loyaltyProgramId}.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Download card 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}/cards/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export loyalty cards to CSV
      effect: read
      questions:
      - Can I download the list of cards issued in a program, including who they're linked to?
      - What cards were created in a given batch or date window?
      instructions:
      - text: Export the loyalty cards of program {loyaltyProgramId} to CSV.
        slots:
          loyaltyProgramId: path.loyaltyProgramId
      - text: Export cards from batch {batchId} in program {loyaltyProgramId} created after {createdAfter}.
        slots:
          batchId: query.batchId
          loyaltyProgramId: path.loyaltyProgramId
          createdAfter: query.createdAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a loyalty card
      effect: read
      questions:
      - What are the status and linked profiles of a specific loyalty card?
      - Can I look up one card by its ID to see its details?
      instructions:
      - text: Get loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show the details of card {loyaltyCardId} from loyalty program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Activate or deactivate a loyalty card
      effect: write
      questions:
      - How do I deactivate a customer's loyalty card temporarily?
      - Can I switch an inactive card back to active?
      instructions:
      - text: Set loyalty card {loyaltyCardId} in program {loyaltyProgramId} to status {status}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          status: requestBody.status
      - text: Deactivate card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a loyalty card
      effect: destructive
      questions:
      - How do I permanently remove a loyalty card from a program?
      - Can I delete a card that was issued by mistake?
      instructions:
      - text: Delete loyalty card {loyaltyCardId} from program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Permanently remove card {loyaltyCardId} in loyalty program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/add_points'].put
  update:
    x-apievangelist-phrasing:
      intent: Add loyalty points to a card
      effect: write
      questions:
      - How do I top up points on a loyalty card manually?
      - Can points I add to a card be set to expire on a certain date?
      instructions:
      - text: Add {points} points to loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          points: requestBody.points
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Credit card {loyaltyCardId} with {points} points in program {loyaltyProgramId}, valid until {validUntil}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          points: requestBody.points
          loyaltyProgramId: path.loyaltyProgramId
          validUntil: requestBody.validUntil
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/deduct_points'].put
  update:
    x-apievangelist-phrasing:
      intent: Deduct loyalty points from a card
      effect: write
      questions:
      - How do I remove points from a loyalty card after a refund?
      - Can I deduct card points from a specific subledger?
      instructions:
      - text: Deduct {points} points from loyalty card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          points: requestBody.points
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Take {points} points off card {loyaltyCardId} in subledger {subledgerId} of program {loyaltyProgramId}.
        slots:
          points: requestBody.points
          loyaltyCardId: path.loyaltyCardId
          subledgerId: requestBody.subledgerId
          loyaltyProgramId: path.loyaltyProgramId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/export_log'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a loyalty card's ledger log to CSV
      effect: read
      questions:
      - Can I download one card's points history as a CSV for a date range?
      - What date format options are there when exporting a card's ledger?
      instructions:
      - text: Export the ledger of card {loyaltyCardId} in program {loyaltyProgramId} from {rangeStart} to {rangeEnd}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
      - text: Download card {loyaltyCardId}'s ledger CSV for program {loyaltyProgramId} between {rangeStart} and {rangeEnd} in {dateFormat} format.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          rangeStart: query.rangeStart
          rangeEnd: query.rangeEnd
          dateFormat: query.dateFormat
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/logs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a loyalty card's transactions for back-office use
      effect: read
      questions:
      - Is there a Management API way for support staff to review a card's transaction logs?
      - Can a back-office tool page through a card's transactions for specific sessions?
      instructions:
      - text: Using the Management API, list the transaction logs of card {loyaltyCardId} in program {loyaltyProgramId}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
      - text: Show back-office logs for card {loyaltyCardId} in program {loyaltyProgramId} for sessions {customerSessionIDs}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          customerSessionIDs: query.customerSessionIDs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/transfer'].put
  update:
    x-apievangelist-phrasing:
      intent: Transfer a loyalty card's data to a new card
      effect: destructive
      questions:
      - A customer lost their card; how do I move their points and linked profiles onto a replacement?
      - Does transferring card data block the original card?
      instructions:
      - text: Transfer card {loyaltyCardId} in program {loyaltyProgramId} to new card {newCardIdentifier}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          loyaltyProgramId: path.loyaltyProgramId
          newCardIdentifier: requestBody.newCardIdentifier
      - text: Replace lost card {loyaltyCardId} with {newCardIdentifier} in program {loyaltyProgramId}, blocking it for reason {blockReason}.
        slots:
          loyaltyCardId: path.loyaltyCardId
          newCardIdentifier: requestBody.newCardIdentifier
          loyaltyProgramId: path.loyaltyProgramId
          blockReason: requestBody.blockReason
      method: generated
      generated: '2026-09-26'