# 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'