# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for 2026-07 Gift Cards API
  version: 1.0.0
extends: openapi/lightspeed-gift-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: 11
- target: $.paths['/gift_cards'].get
  update:
    x-apievangelist-phrasing:
      intent: List gift cards
      effect: read
      questions:
      - Which gift cards have been issued by my store?
      - Can I list only gift cards with a particular status, like voided ones?
      - What is the most gift cards I can pull back per page?
      instructions:
      - text: List all gift cards with status {status}.
        slots:
          status: query.status
      - text: Page through gift cards issued before gift card {before}.
        slots:
          before: query.before
      - text: Show my store's gift cards, {size} per page.
        slots:
          size: query.page_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue and activate a new gift card
      effect: write
      questions:
      - How do I sell a new gift card with a starting balance?
      - Can I set an expiry date when issuing a gift card?
      instructions:
      - text: Issue gift card number {number} with a balance of {amount}.
        slots:
          number: requestBody.number
          amount: requestBody.amount
      - text: Activate gift card {number} loaded with {amount} that expires on {expires}.
        slots:
          number: requestBody.number
          amount: requestBody.amount
          expires: requestBody.expires_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/by_id/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a gift card by its internal ID
      effect: read
      questions:
      - Can I fetch a gift card and its transaction history using its internal ID rather than the card number?
      - What does a gift card record show about activations, redemptions and reloads?
      instructions:
      - text: Get the gift card with internal ID {id}.
        slots:
          id: path.id
      - text: Show the balance and transactions of gift card ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/by_id/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void a gift card by its internal ID
      effect: destructive
      questions:
      - Can I cancel a gift card using its internal ID so its balance goes to zero?
      - What happens to the balance when a gift card is voided by ID?
      instructions:
      - text: Void the gift card with internal ID {id}.
        slots:
          id: path.id
      - text: Zero out and void gift card record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/by_number/{card_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a gift card by card number
      effect: read
      questions:
      - What's the remaining balance on the gift card a customer just handed me?
      - Can I see every redemption made on a gift card by its printed number?
      instructions:
      - text: Look up gift card {card_number} using the by-number endpoint.
        slots:
          card_number: path.card_number
      - text: Check the balance of gift card number {card_number}.
        slots:
          card_number: path.card_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/by_number/{card_number}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void a gift card by card number
      effect: destructive
      questions:
      - How do I void a lost gift card using the number printed on it?
      - Does voiding a card by its number set its status to VOIDED?
      instructions:
      - text: Void gift card number {card_number} through the by-number endpoint.
        slots:
          card_number: path.card_number
      - text: Cancel the gift card printed with number {card_number} and zero its balance.
        slots:
          card_number: path.card_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/transactions/{transaction_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the gift card behind a transaction
      effect: read
      questions:
      - Which gift card was used in a given gift card transaction?
      - Can I look up a transaction that came from the e-series system instead of x-series?
      instructions:
      - text: Find the gift card for transaction {transaction}.
        slots:
          transaction: path.transaction_id
      - text: Find the gift card for transaction {transaction} in source system {system}.
        slots:
          transaction: path.transaction_id
          system: query.system_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/transactions/{transaction_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reverse a gift card redemption
      effect: destructive
      questions:
      - Can I undo a gift card redemption that was charged by mistake?
      - Which gift card transactions are allowed to be reversed?
      instructions:
      - text: Reverse gift card transaction {transaction}.
        slots:
          transaction: path.transaction_id
      - text: Undo the redemption recorded as transaction {transaction}.
        slots:
          transaction: path.transaction_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/{card_number}/transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Redeem or reload a gift card
      effect: write
      questions:
      - How do I take money off a gift card balance at checkout?
      - Can I top up an existing gift card and extend its expiry at the same time?
      - What happens if the gift card does not have enough credit for a redemption?
      instructions:
      - text: Create a {type} transaction of {amount} on gift card {card_number} with client reference {client}.
        slots:
          amount: requestBody.amount
          card_number: path.card_number
          client: requestBody.client_id
          type: requestBody.type
      - text: Reload gift card {card_number} with {amount}, reference {client}.
        slots:
          card_number: path.card_number
          amount: requestBody.amount
          client: requestBody.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/{number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a gift card (legacy number path)
      effect: read
      questions:
      - Is there an older endpoint that looks up a gift card directly under /gift_cards by number?
      - Can I read a gift card's transactions through the plain gift card number path?
      instructions:
      - text: Fetch gift card {number} using the legacy plain number path.
        slots:
          number: path.number
      - text: Read gift card {number} and its transactions from the legacy route.
        slots:
          number: path.number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gift_cards/{number}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void a gift card (legacy number path)
      effect: destructive
      questions:
      - Is there an older endpoint to void a gift card directly under /gift_cards by number?
      - Can I still void a card through the plain gift card number path?
      instructions:
      - text: Void gift card {number} using the legacy plain number path.
        slots:
          number: path.number
      - text: Void card {number} with the older gift card endpoint.
        slots:
          number: path.number
      method: generated
      generated: '2026-09-26'