API Evangelist conversational phrasing for Square Invoices API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Invoices API
  version: 1.0.0
extends: openapi/square-invoices-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: 10
- target: $.paths['/v2/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List invoices for a location
      effect: read
      questions:
      - How do I see all invoices issued from one of my locations?
      - Can I page through a location's invoices a few at a time?
      instructions:
      - text: List invoices for location {location_id}.
        slots:
          location_id: query.location_id
      - text: Show the first {limit} invoices at location {location_id}.
        slots:
          limit: query.limit
          location_id: query.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices'].post
  update:
    x-apievangelist-phrasing:
      intent: Draft an invoice for an order
      effect: write
      questions:
      - How do I create an invoice for an order I already made?
      - Does a new invoice get sent right away or stay as a draft?
      instructions:
      - text: Create a draft invoice {invoice}.
        slots:
          invoice: requestBody.invoice
      - text: 'Draft an invoice for this order: {invoice}.'
        slots:
          invoice: requestBody.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search invoices by location and customer
      effect: read
      questions:
      - Which invoices have I sent to a particular customer?
      - Can I search invoices across a location with a customer filter?
      instructions:
      - text: Search invoices matching {query}.
        slots:
          query: requestBody.query
      - text: Find up to {limit} invoices for the filter {query}.
        slots:
          limit: requestBody.limit
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an invoice
      effect: read
      questions:
      - How do I look up one invoice and its payment status?
      - What details come back when I fetch an invoice by ID?
      instructions:
      - text: Get invoice {invoice_id}.
        slots:
          invoice_id: path.invoice_id
      - text: Show me the status and amounts of invoice {invoice_id}.
        slots:
          invoice_id: path.invoice_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an invoice
      effect: write
      questions:
      - How do I change the due date or recipient on an existing invoice?
      - Can I clear specific fields on an invoice without resending everything?
      instructions:
      - text: Update invoice {invoice_id} with {invoice}.
        slots:
          invoice_id: path.invoice_id
          invoice: requestBody.invoice
      - text: Clear fields {fields_to_clear} on invoice {invoice_id}.
        slots:
          fields_to_clear: requestBody.fields_to_clear
          invoice_id: path.invoice_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a draft invoice
      effect: destructive
      questions:
      - How do I throw away a draft invoice I no longer need?
      - Can a published invoice be deleted, or only drafts?
      instructions:
      - text: Delete draft invoice {invoice_id}.
        slots:
          invoice_id: path.invoice_id
      - text: Delete invoice {invoice_id} at version {version}.
        slots:
          invoice_id: path.invoice_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a file to an invoice
      effect: write
      questions:
      - How do I attach a receipt or PDF to an invoice?
      - Can I upload an image file onto an existing invoice?
      instructions:
      - text: Attach {image_file} to invoice {invoice_id}.
        slots:
          image_file: requestBody.image_file
          invoice_id: path.invoice_id
      - text: Upload a file to invoice {invoice_id}.
        slots:
          invoice_id: path.invoice_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}/attachments/{attachment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an attachment from an invoice
      effect: destructive
      questions:
      - How do I remove a file I attached to an invoice?
      - Which invoice states still allow attachments to be deleted?
      instructions:
      - text: Delete attachment {attachment_id} from invoice {invoice_id}.
        slots:
          attachment_id: path.attachment_id
          invoice_id: path.invoice_id
      - text: Remove file {attachment_id} from invoice {invoice_id} permanently.
        slots:
          attachment_id: path.attachment_id
          invoice_id: path.invoice_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a published invoice
      effect: destructive
      questions:
      - How do I stop collecting payment on an invoice I already sent?
      - Can a draft or paid invoice be canceled?
      instructions:
      - text: Cancel invoice {invoice_id} at version {version}.
        slots:
          invoice_id: path.invoice_id
          version: requestBody.version
      - text: Void the outstanding invoice {invoice_id}, version {version}.
        slots:
          invoice_id: path.invoice_id
          version: requestBody.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invoices/{invoice_id}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish and send a draft invoice
      effect: write
      questions:
      - How do I send a draft invoice to my customer?
      - What happens after an invoice is published, like emailing or charging a card on file?
      instructions:
      - text: Publish invoice {invoice_id} at version {version}.
        slots:
          invoice_id: path.invoice_id
          version: requestBody.version
      - text: Send draft invoice {invoice_id} (version {version}) to the customer.
        slots:
          invoice_id: path.invoice_id
          version: requestBody.version
      method: generated
      generated: '2026-09-26'