# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stripe Tax API
  version: 1.0.0
extends: openapi/stripe-tax-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['/v1/tax/calculations'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate tax for a sale
      effect: write
      questions:
      - How do I work out how much tax to charge on an order?
      - Can tax be calculated on shipping costs too?
      - Can I calculate tax as of a specific date?
      instructions:
      - text: Calculate tax on line items {line_items} in {currency} for customer {customer}.
        slots:
          line_items: requestBody.line_items
          currency: requestBody.currency
          customer: requestBody.customer
      - text: Calculate tax for {line_items} shipped to {customer_details} in {currency}.
        slots:
          line_items: requestBody.line_items
          customer_details: requestBody.customer_details
          currency: requestBody.currency
      - text: Work out tax on {line_items} plus shipping {shipping_cost} in {currency}.
        slots:
          line_items: requestBody.line_items
          shipping_cost: requestBody.shipping_cost
          currency: requestBody.currency
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/calculations/{calculation}/line_items'].get
  update:
    x-apievangelist-phrasing:
      intent: List line items of a tax calculation
      effect: read
      questions:
      - How do I see the tax breakdown per line item in a calculation?
      - Which items in my tax calculation were taxed and at what amount?
      instructions:
      - text: List line items for tax calculation {calculation}.
        slots:
          calculation: path.calculation
      - text: Show the per-item tax breakdown of calculation {calculation}.
        slots:
          calculation: path.calculation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/registrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List tax registrations
      effect: read
      questions:
      - Where am I registered to collect tax?
      - Which of my tax registrations are active, scheduled or expired?
      instructions:
      - text: List my tax registrations.
      - text: Show tax registrations with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/registrations'].post
  update:
    x-apievangelist-phrasing:
      intent: Register to collect tax in a country
      effect: write
      questions:
      - How do I start collecting tax in a new country?
      - Can I schedule a tax registration to start at a future date?
      instructions:
      - text: Register for tax in {country} starting {active_from}.
        slots:
          country: requestBody.country
          active_from: requestBody.active_from
      - text: Add a tax registration in {country} with options {country_options} from {active_from}.
        slots:
          country: requestBody.country
          country_options: requestBody.country_options
          active_from: requestBody.active_from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/registrations/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change or end a tax registration
      effect: write
      questions:
      - How do I stop collecting tax in a country I'm registered in?
      - Can I delete a tax registration once it's created?
      instructions:
      - text: End tax registration {id} at {expires_at}.
        slots:
          id: path.id
          expires_at: requestBody.expires_at
      - text: Move the start of tax registration {id} to {active_from}.
        slots:
          id: path.id
          active_from: requestBody.active_from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get your tax settings
      effect: read
      questions:
      - What head office address and default tax behavior do I have set?
      - Is my account ready to calculate tax?
      instructions:
      - text: Show my tax settings.
      - text: Check whether my tax settings are complete.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/settings'].post
  update:
    x-apievangelist-phrasing:
      intent: Update your tax settings
      effect: write
      questions:
      - How do I set my head office address for tax calculations?
      - Can I remove a tax setting once it's been set?
      instructions:
      - text: Set my tax head office to {head_office}.
        slots:
          head_office: requestBody.head_office
      - text: Update my default tax behavior to {defaults}.
        slots:
          defaults: requestBody.defaults
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/transactions/create_from_calculation'].post
  update:
    x-apievangelist-phrasing:
      intent: Record tax from a calculation
      effect: write
      questions:
      - How do I record the tax I actually collected on an order?
      - Can I link a tax transaction to my own order number?
      instructions:
      - text: Record a tax transaction from calculation {calculation} with reference {reference}.
        slots:
          calculation: requestBody.calculation
          reference: requestBody.reference
      - text: Commit tax calculation {calculation} as order {reference}.
        slots:
          calculation: requestBody.calculation
          reference: requestBody.reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/transactions/create_reversal'].post
  update:
    x-apievangelist-phrasing:
      intent: Reverse recorded tax
      effect: write
      questions:
      - How do I reverse the tax on an order that was refunded?
      - Can I reverse tax on only some line items?
      - Can I reverse a flat amount of tax instead of specific items?
      instructions:
      - text: Fully reverse tax transaction {original_transaction} as {reference}.
        slots:
          original_transaction: requestBody.original_transaction
          reference: requestBody.reference
      - text: Reverse {mode} tax on {line_items} of transaction {original_transaction}, reference {reference}.
        slots:
          mode: requestBody.mode
          line_items: requestBody.line_items
          original_transaction: requestBody.original_transaction
          reference: requestBody.reference
      - text: Reverse a flat {flat_amount} from tax transaction {original_transaction}, reference {reference}.
        slots:
          flat_amount: requestBody.flat_amount
          original_transaction: requestBody.original_transaction
          reference: requestBody.reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/transactions/{transaction}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax transaction
      effect: read
      questions:
      - How do I look up tax recorded for an order?
      - What was the total tax on this transaction?
      instructions:
      - text: Show tax transaction {transaction}.
        slots:
          transaction: path.transaction
      - text: Get the tax recorded on transaction {transaction}.
        slots:
          transaction: path.transaction
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax/transactions/{transaction}/line_items'].get
  update:
    x-apievangelist-phrasing:
      intent: List line items of a tax transaction
      effect: read
      questions:
      - How do I see per-item tax on a recorded tax transaction?
      - Which products in a committed tax transaction were taxed?
      instructions:
      - text: List line items for tax transaction {transaction}.
        slots:
          transaction: path.transaction
      - text: Show the first {limit} taxed items on transaction {transaction}.
        slots:
          limit: query.limit
          transaction: path.transaction
      method: generated
      generated: '2026-09-26'