# 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 Local Tax Rates API
  version: 1.0.0
extends: openapi/optimizely-local-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: 10
- target: $.paths['/api/v1/admin/LocalTaxRates'].get
  update:
    x-apievangelist-phrasing:
      intent: List local tax rates
      effect: read
      questions:
      - How do I see every local tax rate configured by postal code?
      - Can I filter the local tax rate list to a single postal code with $filter?
      instructions:
      - text: List local tax rates matching {filter}.
        slots:
          filter: query.$filter
      - text: Show all postal-code tax rates sorted by {orderby}.
        slots:
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/LocalTaxRates'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a local tax rate for a postal code
      effect: write
      questions:
      - What do I need to add a new sales tax rate for a postal code?
      - Can I choose whether a new local tax rate also applies to freight?
      instructions:
      - text: Create a local tax rate of {taxRate} for postal code {postalCode} with tax code {taxCode}.
        slots:
          taxRate: requestBody.taxRate
          postalCode: requestBody.postalCode
          taxCode: requestBody.taxCode
      - text: 'Add tax code {taxCode} for postal code {postalCode} and tax freight: {taxFreight}.'
        slots:
          taxCode: requestBody.taxCode
          postalCode: requestBody.postalCode
          taxFreight: requestBody.taxFreight
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/LocalTaxRates({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one local tax rate
      effect: read
      questions:
      - Where do I look up a single local tax rate by its id?
      - Which postal code and tax code does a given local tax rate record hold?
      instructions:
      - text: Get local tax rate {id}.
        slots:
          id: path.id
      - text: Show the postal code and rate stored on tax rate record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/LocalTaxRates({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a local tax rate record
      effect: write
      questions:
      - How do I overwrite a local tax rate record with a complete new version?
      - Does a full replace of a tax rate require the postal code and tax code again?
      instructions:
      - text: Replace local tax rate {id} with postal code {postalCode}, tax code {taxCode} and rate {taxRate}.
        slots:
          id: path.id
          postalCode: requestBody.postalCode
          taxCode: requestBody.taxCode
          taxRate: requestBody.taxRate
      - text: Overwrite the whole tax rate record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/LocalTaxRates({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a local tax rate
      effect: destructive
      questions:
      - Can I remove one local tax rate that no longer applies?
      - Is there an ETag check to avoid deleting a tax rate someone just edited?
      instructions:
      - text: Delete local tax rate {id}.
        slots:
          id: path.id
      - text: Delete tax rate {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/LocalTaxRates({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change fields on a local tax rate
      effect: write
      questions:
      - Can I change just the percentage on an existing local tax rate?
      - How do I stop taxing freight for one postal code's rate without replacing it?
      instructions:
      - text: Change the rate on local tax rate {id} to {taxRate}.
        slots:
          id: path.id
          taxRate: requestBody.taxRate
      - text: Set tax freight on local tax rate {id} to {taxFreight}.
        slots:
          id: path.id
          taxFreight: requestBody.taxFreight
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/LocalTaxRates/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the Default function on local tax rates
      effect: read
      questions:
      - What does the Default function on the LocalTaxRates set return?
      - Where do I get the default local tax rate entity?
      instructions:
      - text: Call the Default function on LocalTaxRates.
      - text: Fetch the default local tax rate entity.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/localtaxrates/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete local tax rates
      effect: destructive
      questions:
      - Can I delete many local tax rates at once by listing their ids?
      - Is there a bulk delete for outdated postal-code tax rates?
      instructions:
      - text: Bulk delete local tax rates {ids}.
        slots:
          ids: query.ids
      - text: Remove every tax rate in the id list {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/localtaxrates({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a local tax rate
      effect: read
      questions:
      - How do I read a custom property stored on a local tax rate?
      - Can I fetch one extension field value from a tax rate record?
      instructions:
      - text: Get custom property {custompropertyKey} of local tax rate {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show custom field {custompropertyKey} on tax rate {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/localtaxrates({key})/taxexemptions({taxexemptionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax exemption linked to a local tax rate
      effect: read
      questions:
      - Which tax exemption is attached to a given local tax rate?
      - Can I read one exemption record through the local tax rate it applies to?
      instructions:
      - text: Get tax exemption {taxexemptionKey} for local tax rate {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      - text: Show exemption {taxexemptionKey} applied to tax rate {key}.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
      method: generated
      generated: '2026-09-26'