# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Avalara Transactions API
  version: 1.0.0
extends: openapi/avalara-transactions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List VAT reporting transactions
      effect: read
      questions:
      - Which VAT transactions have I submitted for reporting?
      - Can I page through my VAT reporting transactions?
      instructions:
      - text: List my VAT reporting transactions.
      - text: Show VAT transactions page {page}, {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit transactions for VAT reporting
      effect: write
      questions:
      - How do I send a batch of sales to be included in my VAT returns?
      - Can I submit VAT transactions for a specific company?
      instructions:
      - text: Submit VAT transactions {transactions} for company {companyId}.
        slots:
          transactions: requestBody.transactions
          companyId: requestBody.companyId
      - text: Send these sales {transactions} for VAT reporting.
        slots:
          transactions: requestBody.transactions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/transactions/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate tax by creating a sales transaction
      effect: write
      questions:
      - How do I calculate sales tax on an order in AvaTax?
      - Can I calculate tax and commit the sale in the same call?
      - What do I need to send to get tax on a sales invoice?
      instructions:
      - text: Create a {type} for company {companyCode}, customer {customerCode}, dated {date}, with lines {lines}.
        slots:
          type: requestBody.type
          companyCode: requestBody.companyCode
          customerCode: requestBody.customerCode
          date: requestBody.date
          lines: requestBody.lines
      - text: 'Calculate and commit tax for customer {customerCode} in {companyCode}: {type} on {date}, lines {lines}, commit {commit}.'
        slots:
          customerCode: requestBody.customerCode
          companyCode: requestBody.companyCode
          type: requestBody.type
          date: requestBody.date
          lines: requestBody.lines
          commit: requestBody.commit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a sales transaction by code
      effect: read
      questions:
      - Can I look up a sales transaction by its document code?
      - How much tax was charged on a specific invoice?
      instructions:
      - text: Get transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Show transaction {transactionCode} for {companyCode} including {include}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
          include: query.$include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/adjust'].post
  update:
    x-apievangelist-phrasing:
      intent: Adjust a committed transaction
      effect: write
      questions:
      - Can I change a transaction that has already been committed?
      - What reason must I give when adjusting a committed invoice?
      instructions:
      - text: Adjust transaction {transactionCode} in {companyCode} for reason {adjustmentReason} using {newTransaction}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
          adjustmentReason: requestBody.adjustmentReason
          newTransaction: requestBody.newTransaction
      - text: Replace committed invoice {transactionCode} of {companyCode} with {newTransaction}, reason {adjustmentReason}, note {adjustmentDescription}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
          newTransaction: requestBody.newTransaction
          adjustmentReason: requestBody.adjustmentReason
          adjustmentDescription: requestBody.adjustmentDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/commit'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit a sales transaction for reporting
      effect: write
      questions:
      - How do I finalize a sales invoice so it is reported to tax authorities?
      - Can I commit an uncommitted transaction by its code?
      instructions:
      - text: Commit transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Set commit to {commit} on transaction {transactionCode} of {companyCode}.
        slots:
          commit: requestBody.commit
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/void'].post
  update:
    x-apievangelist-phrasing:
      intent: Void a sales transaction
      effect: destructive
      questions:
      - Can I void a transaction so it drops out of tax reporting?
      - What void reason code do I use when cancelling an invoice?
      instructions:
      - text: Void transaction {transactionCode} in company {companyCode} with reason {code}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
          code: requestBody.code
      - text: Cancel invoice {transactionCode} for {companyCode} as {code}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/transactions/{transactionCode}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a committed transaction
      effect: write
      questions:
      - How do I issue a partial refund on a committed sale?
      - Can I refund only the tax on a transaction, or a percentage of it?
      instructions:
      - text: Refund transaction {transactionCode} as {refundTransactionCode} on {refundDate}, type {refundType}.
        slots:
          transactionCode: path.transactionCode
          refundTransactionCode: requestBody.refundTransactionCode
          refundDate: requestBody.refundDate
          refundType: requestBody.refundType
      - text: Refund {refundPercentage} percent of {transactionCode} as {refundTransactionCode} on {refundDate}, type {refundType}.
        slots:
          refundPercentage: requestBody.refundPercentage
          transactionCode: path.transactionCode
          refundTransactionCode: requestBody.refundTransactionCode
          refundDate: requestBody.refundDate
          refundType: requestBody.refundType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List excise transactions
      effect: read
      questions:
      - Which excise transactions did I record last quarter?
      - Can I list excise tax transactions within a date range?
      instructions:
      - text: List excise transactions from {startDate} to {endDate}.
        slots:
          startDate: query.startDate
          endDate: query.endDate
      - text: Show all my excise transactions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an excise transaction
      effect: write
      questions:
      - Can I record an excise transaction with its invoice number and total tax?
      - What fields go into a new excise transaction record?
      instructions:
      - text: Create an excise transaction for invoice {invoiceNumber} dated {transactionDate}.
        slots:
          invoiceNumber: requestBody.invoiceNumber
          transactionDate: requestBody.transactionDate
      - text: Record excise transaction {transactionId} with total {totalAmount} and tax {totalTax}.
        slots:
          transactionId: requestBody.transactionId
          totalAmount: requestBody.totalAmount
          totalTax: requestBody.totalTax
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Transactions/{transactionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an excise transaction
      effect: read
      questions:
      - Can I pull up a single excise transaction by its ID?
      - What excise tax total was recorded on one transaction?
      instructions:
      - text: Get excise transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      - text: Show the totals on excise transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/transactions/lines/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Add lines to an unlocked transaction
      effect: write
      questions:
      - Can I append more line items to a transaction I already created?
      - Is there a way to build a very large transaction across several calls?
      instructions:
      - text: Add these new lines to my existing unlocked transaction.
      - text: Append extra line items to the open sales transaction and recalculate tax.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: Audit how a transaction was created
      effect: read
      questions:
      - Can I see the original API request and server timing behind a transaction?
      - When exactly did the server record a given transaction, and how long did it take?
      instructions:
      - text: Get the audit record for transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Show the original request and server timestamp for {transactionCode}.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/types/{documentType}/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: Audit a transaction by code and document type
      effect: read
      questions:
      - How do I audit a transaction when two documents share the same code but differ in type?
      - Can I pull audit details for the return invoice rather than the sales invoice with that code?
      instructions:
      - text: Pull audit details for the {documentType} copy of {transactionCode} under company {companyCode}.
        slots:
          documentType: path.documentType
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Audit document type {documentType} of transaction {transactionCode}.
        slots:
          documentType: path.documentType
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transactions/lock'].post
  update:
    x-apievangelist-phrasing:
      intent: Lock many transactions at once
      effect: destructive
      questions:
      - Can I lock a whole set of documents by their IDs in one request?
      - Once transactions are bulk locked, can they still be voided?
      instructions:
      - text: Bulk lock these document IDs so they can no longer be voided.
      - text: Lock the listed transactions in a single batch.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/changecode'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename a transaction's code
      effect: write
      questions:
      - Can I change the document code on a saved or posted transaction?
      - What happens to a transaction's URL after I rename its code?
      instructions:
      - text: Change the code of transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Rename uncommitted transaction {transactionCode} to a new document code.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transactions/createoradjust'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a transaction or adjust it if it exists
      effect: write
      questions:
      - How do I make transaction creation idempotent so a retry adjusts instead of duplicating?
      - Will sending the same document code again update the original transaction?
      instructions:
      - text: Create this transaction, or adjust the existing one if its code is already recorded.
      - text: Upsert the sales document by code so retries never create duplicates.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/transactions/lines/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete lines from an unlocked transaction
      effect: destructive
      questions:
      - Can I remove specific line items from a transaction that is not locked?
      - Is there a way to drop a few lines and keep the rest of the transaction?
      instructions:
      - text: Remove these line numbers from my unlocked transaction.
      - text: Delete the listed lines from the existing sales document and recalculate.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/AllVariance'].get
  update:
    x-apievangelist-phrasing:
      intent: Get variance reports for a whole company
      effect: read
      questions:
      - Where can I see the variance report for every transaction in a company?
      - Can I pull all variance results for one company code?
      instructions:
      - text: Get all variance reports for company {companyCode}.
        slots:
          companyCode: path.companyCode
      - text: Show the company-wide variance results for {companyCode}.
        slots:
          companyCode: path.companyCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/types/{documentType}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transaction by code and type (deprecated)
      effect: read
      questions:
      - Is there still an older endpoint to fetch a transaction by code plus document type?
      - Can I retrieve the purchase invoice version of a code using the deprecated lookup?
      instructions:
      - text: Use the deprecated lookup to get {documentType} {transactionCode} in company {companyCode}.
        slots:
          documentType: path.documentType
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Fetch transaction {transactionCode} of document type {documentType} via the legacy endpoint.
        slots:
          transactionCode: path.transactionCode
          documentType: path.documentType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transactions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transaction by its numeric ID
      effect: read
      questions:
      - Can I fetch a transaction using its internal ID number instead of its code?
      - Does looking up a transaction by ID return only the latest version?
      instructions:
      - text: Get transaction with ID {id}.
        slots:
          id: path.id
      - text: Look up the latest version of transaction number {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionId}/variance'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the variance report for one transaction
      effect: read
      questions:
      - Can I see the variance result for a single transaction?
      - What did the variance report find for one specific transaction ID?
      instructions:
      - text: Get the variance report for transaction {transactionId} in company {companyCode}.
        slots:
          transactionId: path.transactionId
          companyCode: path.companyCode
      - text: Show variance details on transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's sales tax transactions
      effect: read
      questions:
      - Which AvaTax transactions did one company record in the last 30 days?
      - What is the maximum number of transactions returned per company listing?
      instructions:
      - text: List AvaTax transactions for company {companyCode}.
        slots:
          companyCode: path.companyCode
      - text: Show the past month of AvaTax documents recorded by {companyCode}.
        slots:
          companyCode: path.companyCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/lock'].post
  update:
    x-apievangelist-phrasing:
      intent: Lock a single transaction
      effect: destructive
      questions:
      - Can I simulate Returns locking one document so it can't be voided or adjusted?
      - What subscriptions do I need to lock a transaction in sandbox?
      instructions:
      - text: Lock transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Lock only document {transactionCode} so no one can void or adjust it.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a sale within a company
      effect: write
      questions:
      - How do I create a return invoice for a sale recorded under a specific company code?
      - Can I refund selected lines of a company's sales invoice?
      instructions:
      - text: Create a refund for transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Issue a return invoice against {companyCode} sale {transactionCode}.
        slots:
          companyCode: path.companyCode
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/settle'].post
  update:
    x-apievangelist-phrasing:
      intent: 'Settle a transaction: rename, verify and commit'
      effect: write
      questions:
      - Can I change the code, verify totals and commit a transaction in one call?
      - Is there a single step that combines verifying and committing a sale?
      instructions:
      - text: Settle transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Verify, rename and commit {transactionCode} together as one settle action.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/uncommit'].post
  update:
    x-apievangelist-phrasing:
      intent: Uncommit a transaction
      effect: write
      questions:
      - Can I move a committed transaction back to uncommitted?
      - Why can't a transaction already reported by Managed Returns be uncommitted?
      instructions:
      - text: Uncommit transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Return {transactionCode} to uncommitted status so it can be edited.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/unvoid'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a voided transaction
      effect: write
      questions:
      - Can I undo a void on a transaction I cancelled by mistake?
      - Is it possible to bring a voided invoice back into reporting?
      instructions:
      - text: Unvoid transaction {transactionCode} in company {companyCode}.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Reverse the void on document {transactionCode}.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/variance'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a variance report for a company
      effect: write
      questions:
      - How do I submit transactions for a new variance report?
      - Can I generate a fresh variance report for one company code?
      instructions:
      - text: Run a variance report for company {companyCode}.
        slots:
          companyCode: path.companyCode
      - text: Submit these transactions to the {companyCode} variance check.
        slots:
          companyCode: path.companyCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyCode}/transactions/{transactionCode}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a transaction matches expected values
      effect: write
      questions:
      - Can I check that a transaction's date and totals match what my system expects?
      - What error comes back when a transaction doesn't match the expected values?
      instructions:
      - text: Verify transaction {transactionCode} in company {companyCode} against my expected totals.
        slots:
          transactionCode: path.transactionCode
          companyCode: path.companyCode
      - text: Confirm that {transactionCode} matches the amount and tax my ledger shows.
        slots:
          transactionCode: path.transactionCode
      method: generated
      generated: '2026-10-01'