# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Terminal API
  version: 1.0.0
extends: openapi/square-terminal-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: 15
- target: $.paths['/v2/terminals/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an action request to a Terminal device
      effect: write
      questions:
      - How do I push a custom action, like a device pairing check, to a Square Terminal?
      - Can I ask a Terminal device to collect something other than a payment?
      instructions:
      - text: Send Terminal action {action} to the device.
        slots:
          action: requestBody.action
      - text: Create a Terminal action request {action} with idempotency key {idempotency_key}.
        slots:
          action: requestBody.action
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/actions/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search Terminal action requests
      effect: read
      questions:
      - Which Terminal action requests did I send in the last 30 days?
      - Can I filter Terminal actions by device or status?
      instructions:
      - text: Search Terminal actions matching {query}.
        slots:
          query: requestBody.query
      - text: List my recent Terminal action requests, up to {limit}.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/actions/{action_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Terminal action request
      effect: read
      questions:
      - What is the status of an action I sent to a Terminal?
      - Can I look up one Terminal action request by its ID?
      instructions:
      - text: Get Terminal action {action_id}.
        slots:
          action_id: path.action_id
      - text: Check the status of Terminal action {action_id}.
        slots:
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/actions/{action_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a Terminal action request
      effect: destructive
      questions:
      - Can I cancel an action request before the device completes it?
      - What statuses allow a Terminal action to be canceled?
      instructions:
      - text: Cancel Terminal action {action_id}.
        slots:
          action_id: path.action_id
      - text: Stop the pending Terminal action {action_id} on the device.
        slots:
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/actions/{action_id}/dismiss'].post
  update:
    x-apievangelist-phrasing:
      intent: Dismiss a Terminal action request
      effect: write
      questions:
      - How do I clear a finished action off the Terminal screen?
      - When is dismissing a Terminal action allowed?
      instructions:
      - text: Dismiss Terminal action {action_id}.
        slots:
          action_id: path.action_id
      - text: Clear Terminal action {action_id} from the device display.
        slots:
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/checkouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a checkout to a Terminal device
      effect: write
      questions:
      - How do I make a Square Terminal prompt the customer to pay a set amount?
      - Can I start an in-person card payment from my app on a Terminal?
      instructions:
      - text: Send checkout {checkout} to the Terminal.
        slots:
          checkout: requestBody.checkout
      - text: Create a Terminal checkout {checkout} with idempotency key {idempotency_key}.
        slots:
          checkout: requestBody.checkout
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/checkouts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search Terminal checkout requests
      effect: read
      questions:
      - Which Terminal checkouts did my app create recently?
      - Can I find Terminal checkouts that are still pending on a device?
      instructions:
      - text: Search Terminal checkouts matching {query}.
        slots:
          query: requestBody.query
      - text: List recent Terminal checkouts, at most {limit}.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/checkouts/{checkout_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Terminal checkout request
      effect: read
      questions:
      - Did the customer finish paying on the Terminal checkout I sent?
      - What details come back for one Terminal checkout?
      instructions:
      - text: Get Terminal checkout {checkout_id}.
        slots:
          checkout_id: path.checkout_id
      - text: Check whether Terminal checkout {checkout_id} was completed.
        slots:
          checkout_id: path.checkout_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/checkouts/{checkout_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a Terminal checkout
      effect: destructive
      questions:
      - Can I cancel a checkout that is waiting on the Terminal?
      - How do I stop a customer from paying a checkout I sent by mistake?
      instructions:
      - text: Cancel Terminal checkout {checkout_id}.
        slots:
          checkout_id: path.checkout_id
      - text: Abort the pending payment on Terminal checkout {checkout_id}.
        slots:
          checkout_id: path.checkout_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/checkouts/{checkout_id}/dismiss'].post
  update:
    x-apievangelist-phrasing:
      intent: Dismiss a Terminal checkout
      effect: write
      questions:
      - Is it possible to dismiss a checkout from the Terminal screen?
      - When can a Terminal checkout be dismissed instead of canceled?
      instructions:
      - text: Dismiss Terminal checkout {checkout_id}.
        slots:
          checkout_id: path.checkout_id
      - text: Clear Terminal checkout {checkout_id} off the device.
        slots:
          checkout_id: path.checkout_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/refunds'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund an Interac payment on a Terminal
      effect: write
      questions:
      - How do I refund an Interac debit payment taken on a Square Terminal in Canada?
      - Why must Interac refunds go through the Terminal device?
      instructions:
      - text: Create a Terminal refund {refund}.
        slots:
          refund: requestBody.refund
      - text: Start an Interac refund {refund} on the Terminal with key {idempotency_key}.
        slots:
          refund: requestBody.refund
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/refunds/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search Interac Terminal refunds
      effect: read
      questions:
      - Which Interac Terminal refunds were requested in the last 30 days?
      - Can I filter Terminal refund requests by status?
      instructions:
      - text: Search Terminal refunds matching {query}.
        slots:
          query: requestBody.query
      - text: List Interac Terminal refund requests, up to {limit}.
        slots:
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/refunds/{terminal_refund_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Interac Terminal refund
      effect: read
      questions:
      - What is the status of an Interac refund I started on the Terminal?
      - Can I retrieve a Terminal refund object by its ID?
      instructions:
      - text: Get Terminal refund {terminal_refund_id}.
        slots:
          terminal_refund_id: path.terminal_refund_id
      - text: Check Interac Terminal refund {terminal_refund_id}.
        slots:
          terminal_refund_id: path.terminal_refund_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/refunds/{terminal_refund_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an Interac Terminal refund
      effect: destructive
      questions:
      - Can I cancel an Interac refund request before it finishes?
      - What happens if I cancel a pending Terminal refund?
      instructions:
      - text: Cancel Terminal refund {terminal_refund_id}.
        slots:
          terminal_refund_id: path.terminal_refund_id
      - text: Stop the pending Interac refund {terminal_refund_id}.
        slots:
          terminal_refund_id: path.terminal_refund_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/terminals/refunds/{terminal_refund_id}/dismiss'].post
  update:
    x-apievangelist-phrasing:
      intent: Dismiss an Interac Terminal refund
      effect: write
      questions:
      - How do I dismiss a refund request showing on the Terminal?
      - When is it allowed to dismiss a Terminal refund?
      instructions:
      - text: Dismiss Terminal refund {terminal_refund_id}.
        slots:
          terminal_refund_id: path.terminal_refund_id
      - text: Clear Interac refund request {terminal_refund_id} from the Terminal screen.
        slots:
          terminal_refund_id: path.terminal_refund_id
      method: generated
      generated: '2026-09-26'