# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stripe Invoice Invoices API
  version: 1.0.0
extends: openapi/stripe-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: 15
- target: $.paths['/v1/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List invoices
      effect: read
      questions:
      - How do I list all the invoices I've issued?
      - Can I see only the unpaid or open invoices for one customer?
      - Can I filter invoices by due date or by subscription?
      instructions:
      - text: List my most recent invoices.
      - text: List invoices for customer {customer} with status {status}.
        slots:
          customer: query.customer
          status: query.status
      - text: Show invoices generated by subscription {subscription}.
        slots:
          subscription: query.subscription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a draft invoice
      effect: write
      questions:
      - How do I create an invoice for a customer?
      - Can I send an invoice for manual payment instead of charging the card automatically?
      - Can I set a due date on a new invoice?
      instructions:
      - text: Create a draft invoice for customer {customer}.
        slots:
          customer: requestBody.customer
      - text: Draft an invoice for customer {customer} due in {days_until_due} days, sent for manual payment.
        slots:
          customer: requestBody.customer
          days_until_due: requestBody.days_until_due
      - text: Create an invoice for customer {customer} with the memo {description}.
        slots:
          customer: requestBody.customer
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search invoices with a query
      effect: read
      questions:
      - How do I search invoices by amount, status or metadata?
      - Is invoice search up to date immediately after I create an invoice?
      instructions:
      - text: Search invoices matching {query}.
        slots:
          query: query.query
      - text: Find invoices where {query}, returning at most {limit}.
        slots:
          query: query.query
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/upcoming'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a customer's upcoming invoice
      effect: read
      questions:
      - How do I preview what a customer will be billed on their next invoice?
      - Can I see the prorated cost of a plan change before I make it?
      - Can I preview the next invoice with a coupon applied?
      instructions:
      - text: Preview the upcoming invoice for customer {customer}.
        slots:
          customer: query.customer
      - text: Show the next invoice for subscription {subscription} if it switched to items {subscription_items}.
        slots:
          subscription: query.subscription
          subscription_items: query.subscription_items
      - text: Preview customer {customer}'s upcoming invoice with coupon {coupon} applied.
        slots:
          customer: query.customer
          coupon: query.coupon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/upcoming/lines'].get
  update:
    x-apievangelist-phrasing:
      intent: List line items on an upcoming invoice
      effect: read
      questions:
      - How do I page through every line item on a customer's next invoice?
      - What if the upcoming invoice has more line items than the preview shows?
      instructions:
      - text: List the line items on customer {customer}'s upcoming invoice.
        slots:
          customer: query.customer
      - text: Show the next {limit} upcoming invoice lines for subscription {subscription}.
        slots:
          limit: query.limit
          subscription: query.subscription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an invoice
      effect: read
      questions:
      - How do I look up a single invoice?
      - Where do I check whether a specific invoice has been paid?
      instructions:
      - text: Get invoice {invoice}.
        slots:
          invoice: path.invoice
      - text: Show me the status and totals of invoice {invoice}.
        slots:
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit an invoice
      effect: write
      questions:
      - How do I change an invoice before it's finalized?
      - What can I still edit on an invoice after it's finalized?
      - Can I add a footer or custom memo to an invoice?
      instructions:
      - text: Change the due date of invoice {invoice} to {due_date}.
        slots:
          invoice: path.invoice
          due_date: requestBody.due_date
      - text: Set the memo on invoice {invoice} to {description}.
        slots:
          invoice: path.invoice
          description: requestBody.description
      - text: Add the footer {footer} to invoice {invoice}.
        slots:
          footer: requestBody.footer
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a draft invoice
      effect: destructive
      questions:
      - How do I throw away a draft invoice I don't need?
      - Can I delete an invoice that's already been finalized?
      instructions:
      - text: Delete draft invoice {invoice}.
        slots:
          invoice: path.invoice
      - text: Discard the unfinalized invoice {invoice} permanently.
        slots:
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/finalize'].post
  update:
    x-apievangelist-phrasing:
      intent: Finalize a draft invoice
      effect: write
      questions:
      - How do I finalize a draft invoice manually?
      - Can I finalize an invoice without it being collected automatically?
      instructions:
      - text: Finalize invoice {invoice}.
        slots:
          invoice: path.invoice
      - text: Finalize draft {invoice} with automatic collection set to {auto_advance}.
        slots:
          invoice: path.invoice
          auto_advance: requestBody.auto_advance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/lines'].get
  update:
    x-apievangelist-phrasing:
      intent: List an invoice's line items
      effect: read
      questions:
      - How do I get every line item on an invoice?
      - What if an invoice has more line items than are returned with it?
      instructions:
      - text: List the line items on invoice {invoice}.
        slots:
          invoice: path.invoice
      - text: Show {limit} line items from invoice {invoice}.
        slots:
          limit: query.limit
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/lines/{line_item_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a line item on an invoice
      effect: write
      questions:
      - How do I change the quantity or price of one line on an invoice?
      - Can I set tax amounts directly on an invoice line item?
      instructions:
      - text: Set the quantity of line {line_item_id} on invoice {invoice} to {quantity}.
        slots:
          line_item_id: path.line_item_id
          invoice: path.invoice
          quantity: requestBody.quantity
      - text: Change the description of line {line_item_id} on invoice {invoice} to {description}.
        slots:
          line_item_id: path.line_item_id
          invoice: path.invoice
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/mark_uncollectible'].post
  update:
    x-apievangelist-phrasing:
      intent: Write off an invoice as uncollectible
      effect: write
      questions:
      - How do I write off an invoice a customer is never going to pay?
      - Can I track bad debt by marking invoices uncollectible?
      instructions:
      - text: Mark invoice {invoice} as uncollectible.
        slots:
          invoice: path.invoice
      - text: Write off invoice {invoice} as bad debt.
        slots:
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/pay'].post
  update:
    x-apievangelist-phrasing:
      intent: Collect payment on an invoice
      effect: write
      questions:
      - How do I charge an invoice right now instead of waiting for automatic collection?
      - Can I mark an invoice as paid if the customer paid outside the platform?
      - Can I pay an invoice with a different payment method than the default?
      instructions:
      - text: Pay invoice {invoice} now.
        slots:
          invoice: path.invoice
      - text: Pay invoice {invoice} using payment method {payment_method}.
        slots:
          invoice: path.invoice
          payment_method: requestBody.payment_method
      - text: 'Mark invoice {invoice} as paid out of band: {paid_out_of_band}.'
        slots:
          invoice: path.invoice
          paid_out_of_band: requestBody.paid_out_of_band
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/send'].post
  update:
    x-apievangelist-phrasing:
      intent: Email an invoice to the customer
      effect: write
      questions:
      - How do I manually send an invoice to a customer?
      - Can I resend an invoice email outside the normal subscription schedule?
      instructions:
      - text: Send invoice {invoice} to the customer.
        slots:
          invoice: path.invoice
      - text: Email invoice {invoice} for manual payment now.
        slots:
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invoices/{invoice}/void'].post
  update:
    x-apievangelist-phrasing:
      intent: Void a finalized invoice
      effect: destructive
      questions:
      - How do I cancel an invoice that's already finalized?
      - What's the difference between voiding and deleting an invoice?
      instructions:
      - text: Void invoice {invoice}.
        slots:
          invoice: path.invoice
      - text: Cancel finalized invoice {invoice} by voiding it.
        slots:
          invoice: path.invoice
      method: generated
      generated: '2026-09-26'