# 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 Tax Rates API
  version: 1.0.0
extends: openapi/stripe-tax-rates-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: 4
- target: $.paths['/v1/tax_rates'].get
  update:
    x-apievangelist-phrasing:
      intent: List tax rates
      effect: read
      questions:
      - How do I see all the tax rates I've set up for invoices and subscriptions?
      - Can I list only active tax rates, or only tax-inclusive ones?
      instructions:
      - text: List my tax rates.
      - text: List tax rates where active is {active}.
        slots:
          active: query.active
      - text: List tax rates where inclusive is {inclusive}.
        slots:
          inclusive: query.inclusive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax_rates'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tax rate
      effect: write
      questions:
      - How do I add a sales tax or VAT rate to apply to my invoices?
      - Can a tax rate be inclusive of the price rather than added on top?
      - Can I scope a tax rate to a country, state or jurisdiction?
      instructions:
      - text: Create a tax rate {display_name} at {percentage} percent with inclusive set to {inclusive}.
        slots:
          display_name: requestBody.display_name
          percentage: requestBody.percentage
          inclusive: requestBody.inclusive
      - text: Create a {display_name} tax of {percentage} percent for state {state} in {country}, with inclusive set to {inclusive}.
        slots:
          display_name: requestBody.display_name
          percentage: requestBody.percentage
          country: requestBody.country
          state: requestBody.state
          inclusive: requestBody.inclusive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax_rates/{tax_rate}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a tax rate
      effect: read
      questions:
      - How do I check the percentage and jurisdiction of one tax rate?
      - Is a particular tax rate inclusive or exclusive?
      instructions:
      - text: Get tax rate {tax_rate}.
        slots:
          tax_rate: path.tax_rate
      - text: Show me the percentage of tax rate {tax_rate}.
        slots:
          tax_rate: path.tax_rate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tax_rates/{tax_rate}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a tax rate
      effect: write
      questions:
      - How do I archive a tax rate I no longer charge?
      - Can I change a tax rate's display name or jurisdiction but not its percentage?
      instructions:
      - text: Set tax rate {tax_rate} active to {active}.
        slots:
          tax_rate: path.tax_rate
          active: requestBody.active
      - text: Rename tax rate {tax_rate} to {display_name}.
        slots:
          tax_rate: path.tax_rate
          display_name: requestBody.display_name
      method: generated
      generated: '2026-09-26'