# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Cards API
  version: 1.0.0
extends: openapi/square-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: 4
- target: $.paths['/v2/cards'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved cards on file
      effect: read
      questions:
      - Which cards on file does a customer have?
      - Can I include disabled cards when listing saved cards?
      instructions:
      - text: List cards on file for customer {customer_id}.
        slots:
          customer_id: query.customer_id
      - text: List saved cards with reference {reference_id}, including disabled {include_disabled}.
        slots:
          reference_id: query.reference_id
          include_disabled: query.include_disabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a card on file
      effect: write
      questions:
      - How do I store a card for future charges using the Cards API?
      - Can I save a card from a payment token or a previous payment?
      instructions:
      - text: Save card {card} on file from source {source_id}.
        slots:
          card: requestBody.card
          source_id: requestBody.source_id
      - text: Store card {card} from token {source_id} with verification {verification_token}.
        slots:
          card: requestBody.card
          source_id: requestBody.source_id
          verification_token: requestBody.verification_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/cards/{card_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a saved card
      effect: read
      questions:
      - What brand, last four and expiry does a saved card have?
      - Can I look up one card on file by its ID?
      instructions:
      - text: Get card {card_id}.
        slots:
          card_id: path.card_id
      - text: Show brand and expiry of saved card {card_id}.
        slots:
          card_id: path.card_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/cards/{card_id}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable a saved card
      effect: destructive
      questions:
      - How do I stop a saved card from being charged again?
      - What happens if I disable a card that's already disabled?
      instructions:
      - text: Disable card {card_id}.
        slots:
          card_id: path.card_id
      - text: Prevent any further charges on saved card {card_id}.
        slots:
          card_id: path.card_id
      method: generated
      generated: '2026-09-26'