# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for stax-api Invoice API
  version: 1.0.0
extends: openapi/stax-invoice-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: 13
- target: $.paths['/invoice/schedule/'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule a recurring or one-time invoice
      effect: write
      questions:
      - Can I set up an invoice that bills a customer automatically every month?
      - Is it possible to schedule a one-time invoice for a future date with a recurrence rule?
      - Can a scheduled invoice charge a saved payment method automatically?
      instructions:
      - text: Schedule a recurring {total} invoice for customer {customer_id} using rule {rule}, linking to {url}.
        slots:
          total: requestBody.total
          customer_id: requestBody.customer_id
          rule: requestBody.rule
          url: requestBody.url
      - text: Create an invoice schedule for {total} that auto-charges payment method {payment_method_id}, payment page {url}.
        slots:
          total: requestBody.total
          payment_method_id: requestBody.payment_method_id
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search invoices
      effect: read
      questions:
      - Which invoices have I sent to a particular customer email?
      - Can I find all invoices generated by a specific recurring schedule?
      - What invoices do I have for a given company name?
      instructions:
      - text: List all my invoices.
      - text: Find invoices sent to {email}.
        slots:
          email: query.email
      - text: Show the invoices created by schedule {schedule_id}.
        slots:
          schedule_id: query.schedule_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an invoice for a customer
      effect: write
      questions:
      - How do I bill a customer with a one-off invoice?
      - Can I let a customer pay an invoice in partial payments?
      - Can I set a due date when I create an invoice?
      instructions:
      - text: Create a {total} invoice for customer {customer_id} with payment page {url}.
        slots:
          total: requestBody.total
          customer_id: requestBody.customer_id
          url: requestBody.url
      - text: Invoice customer {customer_id} for {total}, due {due_at}, payable at {url}.
        slots:
          customer_id: requestBody.customer_id
          total: requestBody.total
          due_at: requestBody.due_at
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one invoice
      effect: read
      questions:
      - What is the status and balance of a specific invoice?
      - Can I look up a single invoice by its ID?
      instructions:
      - text: Get invoice {id}.
        slots:
          id: path.id
      - text: Show me the line items and total on invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing invoice
      effect: write
      questions:
      - Can I change the invoice date on an invoice I already created?
      - Is it possible to edit an invoice after it has been issued?
      instructions:
      - text: Change the invoice date on invoice {id} to {invoice_date_at}.
        slots:
          id: path.id
          invoice_date_at: query.invoice_date_at
      - text: Update existing invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an invoice
      effect: destructive
      questions:
      - Can I delete an invoice that was created by mistake?
      - What happens to a single invoice when I remove it?
      instructions:
      - text: Delete invoice {id}.
        slots:
          id: path.id
      - text: Remove the invoice {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/schedule/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an invoice schedule
      effect: write
      questions:
      - Can I pause a recurring invoice schedule without deleting it?
      - Is it possible to change the amount or recurrence rule on an existing invoice schedule?
      instructions:
      - text: Set invoice schedule {id} active to {active}.
        slots:
          id: path.id
          active: requestBody.active
      - text: Change invoice schedule {id} to bill {total} on rule {rule}.
        slots:
          id: path.id
          total: requestBody.total
          rule: requestBody.rule
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/schedule/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a recurring invoice schedule
      effect: destructive
      questions:
      - Can I stop a recurring billing schedule for good?
      - Does deleting an invoice schedule need merchant authentication?
      instructions:
      - text: Delete invoice schedule {id}.
        slots:
          id: path.id
      - text: Cancel the recurring invoice schedule {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}/pay/{method}'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark an invoice paid by cash, check or gift card
      effect: write
      questions:
      - Can I record that a customer paid an invoice with cash or a check outside of Stax?
      - Is it possible to log a check number when marking an invoice paid manually?
      - Can I record a partial cash payment against an invoice?
      instructions:
      - text: Mark invoice {id} as paid by {method}.
        slots:
          id: path.id
          method: path.method
      - text: Mark invoice {id} paid by {method} with check number {check_number}.
        slots:
          id: path.id
          method: path.method
          check_number: query.check_number
      - text: 'Record a manual {method} payment of {apply_balance} on invoice {id} and email the receipt: {email_receipt}.'
        slots:
          method: path.method
          apply_balance: query.apply_balance
          id: path.id
          email_receipt: query.email_receipt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}/pay'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay an invoice with a payment method
      effect: write
      questions:
      - How do I charge a customer's saved card to pay off an invoice?
      - Can I apply a partial payment to an invoice using a stored payment method?
      instructions:
      - text: Pay invoice {id} with payment method {payment_method_id}.
        slots:
          id: path.id
          payment_method_id: query.payment_method_id
      - text: Charge {apply_balance} toward invoice {id} on payment method {payment_method_id}.
        slots:
          apply_balance: query.apply_balance
          id: path.id
          payment_method_id: query.payment_method_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/schedule'].get
  update:
    x-apievangelist-phrasing:
      intent: List scheduled invoices
      effect: read
      questions:
      - Which recurring invoice schedules are set up on my merchant account?
      - Can I see the invoice schedules for just one customer?
      instructions:
      - text: List all my scheduled invoices.
      - text: Show the invoice schedules for customer {customer_id}.
        slots:
          customer_id: query.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}/send/email'].put
  update:
    x-apievangelist-phrasing:
      intent: Email an invoice to the customer
      effect: write
      questions:
      - Can I email an invoice to a customer and copy other addresses on it?
      - Is there a way to resend an invoice to a customer's inbox?
      instructions:
      - text: Email invoice {id} to the customer.
        slots:
          id: path.id
      - text: Email invoice {id} and CC {ccEmails}.
        slots:
          id: path.id
          ccEmails: requestBody.ccEmails
      method: generated
      generated: '2026-09-26'
- target: $.paths['/invoice/{id}/send/sms'].put
  update:
    x-apievangelist-phrasing:
      intent: Text an invoice to the customer
      effect: write
      questions:
      - Can I send an invoice to a customer by text message?
      - Is it possible to include a custom message when texting an invoice?
      instructions:
      - text: Text invoice {id} to {phone}.
        slots:
          id: path.id
          phone: query.phone
      - text: Send invoice {id} by SMS with the message {message}.
        slots:
          id: path.id
          message: query.message
      method: generated
      generated: '2026-09-26'