# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tabby API Reference Payments API
  version: 1.0.0
extends: openapi/tabby-payments-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: 6
- target: $.paths['/api/v2/payments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a payment with its captures and refunds
      effect: read
      questions:
      - What is the current status of a specific Tabby payment?
      - Can I see which captures and refunds have been made on one payment?
      instructions:
      - text: Retrieve payment {id}.
        slots:
          id: path.id
      - text: Show the status, captures and refunds for payment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/payments/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a payment's order reference ID
      effect: write
      questions:
      - How do I change the order reference number attached to a payment?
      - Which payment statuses allow me to update the reference ID?
      instructions:
      - text: Update the order reference on payment {id} to {order}.
        slots:
          id: path.id
          order: requestBody.order
      - text: Set a new reference ID on authorized payment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/payments/{id}/captures'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture an authorized payment
      effect: write
      questions:
      - How do I collect the money for an order once it ships?
      - Can I capture only part of an authorized payment and the rest later?
      - What happens to the payment after I capture the full amount?
      instructions:
      - text: Capture {amount} on payment {id} with reference {reference_id}.
        slots:
          amount: requestBody.amount
          id: path.id
          reference_id: requestBody.reference_id
      - text: Capture {amount} for shipped items {items} on payment {id}, idempotency key {reference_id}.
        slots:
          amount: requestBody.amount
          items: requestBody.items
          id: path.id
          reference_id: requestBody.reference_id
      - text: Capture {amount} on payment {id} including {tax_amount} tax and {shipping_amount} shipping, reference {reference_id}.
        slots:
          amount: requestBody.amount
          id: path.id
          tax_amount: requestBody.tax_amount
          shipping_amount: requestBody.shipping_amount
          reference_id: requestBody.reference_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/payments/{id}/refunds'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a closed payment
      effect: write
      questions:
      - How do I refund a customer who returned their order?
      - Can I issue a partial refund instead of refunding the whole payment?
      - Why can I only refund payments that are already closed?
      instructions:
      - text: Refund {amount} on payment {id} with reference {reference_id}.
        slots:
          amount: requestBody.amount
          id: path.id
          reference_id: requestBody.reference_id
      - text: Refund {amount} of payment {id} for returned items {items} because {reason}, key {reference_id}.
        slots:
          amount: requestBody.amount
          id: path.id
          items: requestBody.items
          reason: requestBody.reason
          reference_id: requestBody.reference_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/payments/{id}/close'].post
  update:
    x-apievangelist-phrasing:
      intent: Close a payment as final
      effect: destructive
      questions:
      - How do I cancel a whole order so the customer gets back everything they paid?
      - What should I do with the undelivered remainder after a partial capture?
      instructions:
      - text: Close payment {id}.
        slots:
          id: path.id
      - text: Close payment {id} without capturing because the order was fully cancelled.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/payments'].get
  update:
    x-apievangelist-phrasing:
      intent: List my payments
      effect: read
      questions:
      - Which payments have I taken, newest first?
      - Can I filter my payments by creation date or status?
      - How many payments can I pull back at a time, and how do I page through them?
      instructions:
      - text: List my recent payments.
      - text: List payments created between {created_at__gte} and {created_at__lte}.
        slots:
          created_at__gte: query.created_at__gte
          created_at__lte: query.created_at__lte
      - text: Show {limit} payments with status {status} starting at offset {offset}.
        slots:
          limit: query.limit
          status: query.status
          offset: query.offset
      method: generated
      generated: '2026-09-26'