# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Invoice Histories API
  version: 1.0.0
extends: openapi/optimizely-invoice-histories-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: 11
- target: $.paths['/api/v1/admin/InvoiceHistories'].get
  update:
    x-apievangelist-phrasing:
      intent: List historical invoices
      effect: read
      questions:
      - How do I pull invoice history synced from our ERP?
      - Can I list only the invoices that are still open?
      - Which invoices for a customer number have a balance due?
      instructions:
      - text: List all invoice history records.
      - text: List invoice histories matching {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      - text: Show the next {top} invoices after skipping {skip}.
        slots:
          top: query.$top
          skip: query.$skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a historical invoice record
      effect: write
      questions:
      - How do I load an ERP invoice into the invoice history?
      - What fields are required when creating an invoice history record?
      instructions:
      - text: Create invoice history {invoiceNumber} of type {invoiceType} for customer {customerNumber}.
        slots:
          invoiceNumber: requestBody.invoiceNumber
          invoiceType: requestBody.invoiceType
          customerNumber: requestBody.customerNumber
      - text: Add invoice {invoiceNumber} with total {invoiceTotal} due on {dueDate}.
        slots:
          invoiceNumber: requestBody.invoiceNumber
          invoiceTotal: requestBody.invoiceTotal
          dueDate: requestBody.dueDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one historical invoice
      effect: read
      questions:
      - How do I view the totals and current balance of one invoice?
      - Can I choose which fields come back for a single invoice history record?
      instructions:
      - text: Get invoice history {id}.
        slots:
          id: path.id
      - text: Show only {select} for invoice history {id}.
        slots:
          select: query.$select
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a historical invoice record
      effect: write
      questions:
      - How do I overwrite an entire invoice history record?
      - Is there a way to fully replace a past invoice with new ERP data?
      instructions:
      - text: Replace invoice history {id} with the full record for invoice {invoiceNumber}.
        slots:
          id: path.id
          invoiceNumber: requestBody.invoiceNumber
      - text: Overwrite past invoice {id} entirely, setting current balance to {currentBalance}.
        slots:
          id: path.id
          currentBalance: requestBody.currentBalance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a historical invoice
      effect: destructive
      questions:
      - How do I remove one invoice from invoice history?
      - Can I delete a past invoice only if its ETag still matches?
      instructions:
      - text: Delete invoice history {id}.
        slots:
          id: path.id
      - text: Remove past invoice {id} if its ETag is still {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a historical invoice
      effect: write
      questions:
      - How do I mark a past invoice as closed?
      - Can I update just the current balance on an invoice history record?
      instructions:
      - text: Set isOpen to {isOpen} on invoice history {id}.
        slots:
          isOpen: requestBody.isOpen
          id: path.id
      - text: Update the balance of past invoice {id} to {currentBalance}.
        slots:
          id: path.id
          currentBalance: requestBody.currentBalance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/InvoiceHistories/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank invoice history template
      effect: read
      questions:
      - What default values does a new invoice history record start with?
      - Can I fetch an empty invoice template before loading invoices?
      instructions:
      - text: Fetch the default invoice history template.
      - text: Show me the starting values for a new invoice history record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/invoicehistories/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete historical invoices
      effect: destructive
      questions:
      - How do I delete several past invoices at once?
      - Can I purge a batch of invoice history records by ID?
      instructions:
      - text: Bulk delete the invoice histories with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these past invoices in one call: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/invoicehistories({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a historical invoice
      effect: read
      questions:
      - How do I read a custom property stored on a past invoice?
      - Can I fetch one extra field value from an invoice history record?
      instructions:
      - text: Get custom property {custompropertyKey} on invoice history {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of past invoice {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/invoicehistories({key})/invoicehistorylines({invoicehistorylineKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a line item on a historical invoice
      effect: read
      questions:
      - How do I see a single billed line from a past invoice?
      - Can I read one invoice history line by its key?
      instructions:
      - text: Get line {invoicehistorylineKey} of invoice history {key}.
        slots:
          invoicehistorylineKey: path.invoicehistorylineKey
          key: path.key
      - text: Show billed line {invoicehistorylineKey} on past invoice {key}.
        slots:
          invoicehistorylineKey: path.invoicehistorylineKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/invoicehistories({key})/invoicehistorytaxes({invoicehistorytaxKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax entry on a historical invoice
      effect: read
      questions:
      - How do I see a tax breakdown entry on a past invoice?
      - Can I read one invoice history tax record by its key?
      instructions:
      - text: Get tax entry {invoicehistorytaxKey} on invoice history {key}.
        slots:
          invoicehistorytaxKey: path.invoicehistorytaxKey
          key: path.key
      - text: Show tax line {invoicehistorytaxKey} for past invoice {key}.
        slots:
          invoicehistorytaxKey: path.invoicehistorytaxKey
          key: path.key
      method: generated
      generated: '2026-09-26'