# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drip Invoices API
  version: 1.0.0
extends: openapi/drippay-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: 13
- target: $.paths['/v1/invoices/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a draft invoice from usage charges
      effect: write
      questions:
      - How do I turn a customer's usage charges for a period into an invoice?
      - Can I build an invoice that only includes charges that have already settled?
      instructions:
      - text: Generate an invoice from charges for customer {customerId} between {periodStart} and {periodEnd}.
        slots:
          customerId: requestBody.customerId
          periodStart: requestBody.periodStart
          periodEnd: requestBody.periodEnd
      - text: Draft a usage invoice for {customerId} from {periodStart} to {periodEnd}, due {dueDate}.
        slots:
          customerId: requestBody.customerId
          periodStart: requestBody.periodStart
          periodEnd: requestBody.periodEnd
          dueDate: requestBody.dueDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/generate-from-subscription'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a draft invoice for a subscription period
      effect: write
      questions:
      - Can I invoice a subscription for a partial period with proration?
      - Is it possible to include usage charges on a subscription invoice?
      instructions:
      - text: Generate an invoice for subscription {subscriptionId} of customer {customerId}.
        slots:
          subscriptionId: requestBody.subscriptionId
          customerId: requestBody.customerId
      - text: 'Invoice subscription {subscriptionId} for {customerId} and include usage charges: {includeUsageCharges}.'
        slots:
          subscriptionId: requestBody.subscriptionId
          customerId: requestBody.customerId
          includeUsageCharges: requestBody.includeUsageCharges
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List invoices
      effect: read
      questions:
      - Which invoices are still unpaid?
      - Can I list one customer's invoices within a date range?
      instructions:
      - text: List invoices with status {status}.
        slots:
          status: query.status
      - text: Show invoices for customer {customerId} from {startDate} to {endDate}.
        slots:
          customerId: query.customerId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an invoice
      effect: read
      questions:
      - What line items and totals are on a specific invoice?
      - Can I fetch one invoice by its ID?
      instructions:
      - text: Show invoice {id}.
        slots:
          id: path.id
      - text: Get the details of invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit terms and notes on a draft invoice
      effect: write
      questions:
      - Can I add a PO number or change NET terms on an invoice before it's issued?
      - Are invoice notes still editable after the invoice is issued?
      instructions:
      - text: Update the payment terms and PO number on draft invoice {id}.
        slots:
          id: path.id
      - text: Change the customer notes on draft invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}/line-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a one-off line item to a draft invoice
      effect: write
      questions:
      - How do I add a setup fee or manual adjustment to an invoice?
      - Can I append a line item after an invoice has been issued?
      instructions:
      - text: Add a one-off line item to draft invoice {id}.
        slots:
          id: path.id
      - text: Append a setup fee line to invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a draft invoice
      effect: write
      questions:
      - How do I finalize a draft invoice so it's pending payment?
      - What happens to a draft invoice when I issue it?
      instructions:
      - text: Issue invoice {id}.
        slots:
          id: path.id
      - text: Finalize draft invoice {id} and send it for payment.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}/paid'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark an invoice as paid
      effect: write
      questions:
      - Can I record a partial payment against an invoice?
      - How do I mark an invoice settled when the customer paid outside the system?
      instructions:
      - text: Mark invoice {id} as paid in full.
        slots:
          id: path.id
      - text: Record a payment of {amount} on invoice {id}.
        slots:
          amount: requestBody.amount
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}/void'].post
  update:
    x-apievangelist-phrasing:
      intent: Void an invoice
      effect: destructive
      questions:
      - How do I cancel an invoice that was sent by mistake?
      - Can an invoice be voided once it's been paid?
      instructions:
      - text: Void invoice {id} because {reason}.
        slots:
          id: path.id
          reason: requestBody.reason
      - text: Cancel invoice {id} with reason {reason}.
        slots:
          id: path.id
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get invoice statistics
      effect: read
      questions:
      - What are my aggregate invoice totals across the business?
      - How much am I owed across all outstanding invoices?
      instructions:
      - text: Show my invoice summary stats.
      - text: Give me aggregated invoice totals for the business.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{id}/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an invoice PDF
      effect: read
      questions:
      - Can I get a PDF copy of an invoice to send to a customer?
      - Where do I download an invoice as a PDF file?
      instructions:
      - text: Download the PDF for invoice {id}.
        slots:
          id: path.id
      - text: Generate a PDF of invoice {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/subscriptions/{id}/upcoming-invoice'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a subscription's upcoming invoice
      effect: read
      questions:
      - What will a customer's next subscription invoice look like, usage included?
      - Can I see the upcoming bill for a subscription without creating anything?
      instructions:
      - text: Preview the upcoming invoice for subscription {id}.
        slots:
          id: path.id
      - text: Show what subscription {id} will be billed next period.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview an invoice for any period
      effect: read
      questions:
      - Can I preview what a customer would be invoiced over an arbitrary date range?
      - What would an invoice for a custom period come to before I generate it?
      instructions:
      - text: Preview an invoice for a customer over a custom period.
      - text: Estimate an arbitrary-period invoice without saving it.
      method: generated
      generated: '2026-09-26'