# 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 Tax Exemptions API
  version: 1.0.0
extends: openapi/optimizely-tax-exemptions-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: 15
- target: $.paths['/api/v1/admin/TaxExemptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter tax exemptions
      effect: read
      questions:
      - How can I see all the tax exemptions configured in my commerce site?
      - Can I filter tax exemptions by name or only get the ones active this year?
      - Is it possible to page through tax exemptions and get a total count?
      instructions:
      - text: List every tax exemption.
      - text: List tax exemptions matching {filter}, ordered by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tax exemption
      effect: write
      questions:
      - How do I set up a new tax exemption with an exempt amount?
      - What does a new tax exemption require besides a name and description?
      instructions:
      - text: Create a tax exemption named {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      - text: Add tax exemption {name} ({description}) for amount {amount}, active from {activateOn}.
        slots:
          name: requestBody.name
          description: requestBody.description
          amount: requestBody.amount
          activateOn: requestBody.activateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one tax exemption by id
      effect: read
      questions:
      - How can I look up the details of a single tax exemption?
      - Can I pick which fields come back when fetching one tax exemption?
      instructions:
      - text: Show tax exemption {id}.
        slots:
          id: path.id
      - text: Fetch only {select} for tax exemption {id}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a tax exemption entirely
      effect: write
      questions:
      - How do I overwrite all fields of an existing tax exemption at once?
      - Does a full replace of a tax exemption clear dates I don't send?
      instructions:
      - text: Replace tax exemption {id} with name {name} and description {description}.
        slots:
          id: path.id
          name: requestBody.name
          description: requestBody.description
      - text: Overwrite the complete record of tax exemption {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one tax exemption
      effect: destructive
      questions:
      - How do I remove a single tax exemption permanently?
      - Can I make a tax exemption delete conditional on an ETag?
      instructions:
      - text: Delete tax exemption {id}.
        slots:
          id: path.id
      - text: Remove tax exemption {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/TaxExemptions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update some fields of a tax exemption
      effect: write
      questions:
      - How can I change just the exempt amount on a tax exemption?
      - Can I push back the end date of a tax exemption without resending everything?
      instructions:
      - text: Change the amount on tax exemption {id} to {amount}.
        slots:
          id: path.id
          amount: requestBody.amount
      - text: Make tax exemption {id} expire on {deactivateOn}.
        slots:
          id: path.id
          deactivateOn: requestBody.deactivateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new tax exemption
      effect: read
      questions:
      - What defaults does a new tax exemption start with?
      - Where do I get an empty tax exemption template?
      instructions:
      - text: Fetch the default tax exemption template.
      - text: Show the starting values used for new tax exemptions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/TaxExemptions/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive tax exemptions with the archive action
      effect: destructive
      questions:
      - How do I archive tax exemptions I no longer use via the archive action?
      - Can I retire several tax exemptions at once rather than deleting them?
      instructions:
      - text: Archive tax exemptions {ids} via the archive action.
        slots:
          ids: query.ids
      - text: Call the tax exemption archive operation for {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive tax exemptions via the DELETE route
      effect: destructive
      questions:
      - Is there a DELETE route that archives tax exemptions by id?
      - Can I use /taxexemptions/archive to archive a batch of exemptions?
      instructions:
      - text: Send the archive DELETE for tax exemptions {ids}.
        slots:
          ids: query.ids
      - text: Archive tax exemptions {ids} through the taxexemptions/archive route.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete tax exemptions by ids
      effect: destructive
      questions:
      - How do I delete a batch of tax exemptions in one go?
      - Can I pass several ids to remove multiple tax exemptions?
      instructions:
      - text: Bulk delete tax exemptions {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every tax exemption in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions({key})/categories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category covered by a tax exemption
      effect: read
      questions:
      - Which product categories does a tax exemption apply to?
      - How do I check one category linked to a tax exemption?
      instructions:
      - text: Get category {categoryKey} on tax exemption {key}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      - text: Check whether category {categoryKey} is covered by tax exemption {key}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of a tax exemption
      effect: read
      questions:
      - Where can I read a custom property saved on a tax exemption?
      - How do I fetch one custom attribute from a tax exemption?
      instructions:
      - text: Get custom property {custompropertyKey} of tax exemption {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Read custom field {custompropertyKey} on tax exemption {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions({key})/localtaxrates({localtaxrateKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a local tax rate tied to a tax exemption
      effect: read
      questions:
      - Which local tax rates are affected by a tax exemption?
      - How do I read one local tax rate linked to an exemption?
      instructions:
      - text: Get local tax rate {localtaxrateKey} on tax exemption {key}.
        slots:
          key: path.key
          localtaxrateKey: path.localtaxrateKey
      - text: Show the local rate {localtaxrateKey} tied to tax exemption {key}.
        slots:
          key: path.key
          localtaxrateKey: path.localtaxrateKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product covered by a tax exemption
      effect: read
      questions:
      - Is a particular product tax exempt under a given exemption?
      - How do I look up one product attached to a tax exemption?
      instructions:
      - text: Get product {productKey} on tax exemption {key}.
        slots:
          key: path.key
          productKey: path.productKey
      - text: Confirm product {productKey} is exempted by tax exemption {key}.
        slots:
          key: path.key
          productKey: path.productKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/taxexemptions({key})/states({stateKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a state covered by a tax exemption
      effect: read
      questions:
      - Which states or provinces does a tax exemption apply in?
      - Can I check one state linked to a tax exemption?
      instructions:
      - text: Get state {stateKey} on tax exemption {key}.
        slots:
          key: path.key
          stateKey: path.stateKey
      - text: Check if tax exemption {key} applies in state {stateKey}.
        slots:
          key: path.key
          stateKey: path.stateKey
      method: generated
      generated: '2026-09-26'