# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Gift Cards API
  version: 1.0.0
extends: openapi/square-gift-cards-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: 7
- target: $.paths['/v2/gift-cards'].get
  update:
    x-apievangelist-phrasing:
      intent: List gift cards
      effect: read
      questions:
      - Which gift cards are active in my account?
      - Can I list only physical or digital gift cards linked to a customer?
      instructions:
      - text: List all gift cards.
      - text: List {type} gift cards in state {state} for customer {customer_id}.
        slots:
          type: query.type
          state: query.state
          customer_id: query.customer_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or register a gift card
      effect: write
      questions:
      - How do I issue a new digital gift card?
      - Can I register a plastic gift card I already have in stock?
      - Why is a newly created gift card still pending?
      instructions:
      - text: Create gift card {gift_card} at location {location_id}.
        slots:
          gift_card: requestBody.gift_card
          location_id: requestBody.location_id
      - text: Register physical gift card {gift_card} for location {location_id} with key {idempotency_key}.
        slots:
          gift_card: requestBody.gift_card
          location_id: requestBody.location_id
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards/from-gan'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a gift card by its number
      effect: read
      questions:
      - Can I find a gift card using the number printed on it?
      - What is the balance on the gift card with this account number?
      instructions:
      - text: Look up the gift card with GAN {gan}.
        slots:
          gan: requestBody.gan
      - text: Check the balance of gift card number {gan}.
        slots:
          gan: requestBody.gan
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards/from-nonce'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a gift card from a payment token
      effect: read
      questions:
      - How do I identify a gift card from the secure token my payment form returned?
      - Can I get gift card details from a nonce without the card number?
      instructions:
      - text: Retrieve the gift card for nonce {nonce}.
        slots:
          nonce: requestBody.nonce
      - text: Find which gift card payment token {nonce} represents.
        slots:
          nonce: requestBody.nonce
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards/{gift_card_id}/link-customer'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a customer to a gift card
      effect: write
      questions:
      - Can I save a gift card on file for a customer?
      - How do I attach a gift card to a customer's profile?
      instructions:
      - text: Link customer {customer_id} to gift card {gift_card_id}.
        slots:
          customer_id: requestBody.customer_id
          gift_card_id: path.gift_card_id
      - text: Add gift card {gift_card_id} on file for customer {customer_id}.
        slots:
          gift_card_id: path.gift_card_id
          customer_id: requestBody.customer_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards/{gift_card_id}/unlink-customer'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink a customer from a gift card
      effect: write
      questions:
      - How do I remove a gift card from a customer's saved cards?
      - Can I detach a customer from a gift card without deactivating it?
      instructions:
      - text: Unlink customer {customer_id} from gift card {gift_card_id}.
        slots:
          customer_id: requestBody.customer_id
          gift_card_id: path.gift_card_id
      - text: Take gift card {gift_card_id} off customer {customer_id}'s profile.
        slots:
          gift_card_id: path.gift_card_id
          customer_id: requestBody.customer_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/gift-cards/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a gift card by ID
      effect: read
      questions:
      - What state and balance does a gift card have when I know its Square ID?
      - Can I fetch a gift card using its ID rather than its number?
      instructions:
      - text: Get gift card {id}.
        slots:
          id: path.id
      - text: Show balance and state of gift card ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'