# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Avalara Items API
  version: 1.0.0
extends: openapi/avalara-items-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: 32
- target: $.paths['/api/v2/companies/{companyId}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's items
      effect: read
      questions:
      - Which products and items are catalogued under my company?
      - Can I filter my company's item list by tax code?
      instructions:
      - text: List items for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show items for company {companyId} matching {filter}.
        slots:
          companyId: path.companyId
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add items to a company catalog
      effect: write
      questions:
      - Can I add products to my company's item catalog?
      - Is it possible to create several items for a company at once?
      instructions:
      - text: Create items for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Add new products to the item catalog of company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List an item's tax system classifications
      effect: read
      questions:
      - Which tax system classifications are attached to one of my items?
      - Can I see every product code an item carries across different tax systems?
      instructions:
      - text: List the classifications on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Show every tax system code assigned to item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications'].post
  update:
    x-apievangelist-phrasing:
      intent: Add tax system classifications to an item
      effect: write
      questions:
      - How do I give an item a product code for another tax system?
      - Can an item hold more than one classification for the same tax system?
      instructions:
      - text: Add classifications to item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Attach new tax system product codes to item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all classifications from an item
      effect: destructive
      questions:
      - Can I wipe every classification off an item in one call?
      - What happens to an item's tax rates once all its classifications are cleared?
      instructions:
      - text: Delete all classifications on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Clear every tax system code from item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters'].get
  update:
    x-apievangelist-phrasing:
      intent: List an item's tax-affecting parameters
      effect: read
      questions:
      - Which tax-affecting properties like grade or measurement are set on an item?
      - What default parameters does an item apply during tax calculation?
      instructions:
      - text: List the parameters on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Show the grade and measurement properties stored for item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters'].post
  update:
    x-apievangelist-phrasing:
      intent: Add tax-affecting parameters to an item
      effect: write
      questions:
      - How do I record an item's grade or size so it changes the tax it gets?
      - Can I set default parameters on an item instead of on every transaction line?
      instructions:
      - text: Add parameters to item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Store new tax-affecting properties on item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all parameters from an item
      effect: destructive
      questions:
      - Can I strip every tax-affecting parameter off an item at once?
      - Is there a bulk way to clear an item's default grade and measurement values?
      instructions:
      - text: Delete all parameters on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Clear every tax-affecting property from item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk upload items to a company
      effect: write
      questions:
      - Can I create or update a large batch of items in a single upload?
      - Is there a bulk upload that both adds new items and updates existing ones?
      instructions:
      - text: Bulk upload items to company {companyId}.
        slots:
          companyId: path.companyId
      - text: Upload this item list to company {companyId}, creating or updating each one.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tags on an item
      effect: read
      questions:
      - Which grouping labels are attached to one of my items?
      - Can I see the tags I used to group a particular product?
      instructions:
      - text: Get the tags on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Show the labels attached to item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag an item
      effect: write
      questions:
      - How do I label an item so I can group it with similar products?
      - Can I add several tags to one item at once?
      instructions:
      - text: Add tags to item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Label item {itemId} with new grouping tags.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/tags'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all tags from an item
      effect: destructive
      questions:
      - Can I clear every tag off an item in one request?
      - Is there a way to drop all the grouping labels on a product?
      instructions:
      - text: Delete all tags on item {itemId} in company {companyId}.
        slots:
          itemId: path.itemId
          companyId: path.companyId
      - text: Strip every grouping label from item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/classificationrequests/taxcode'].get
  update:
    x-apievangelist-phrasing:
      intent: Check status of tax code classification requests
      effect: read
      questions:
      - Where can I see whether my tax code classification requests are finished?
      - What status are a company's pending tax code classification requests in?
      instructions:
      - text: Show the tax code classification request status for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Check progress of my tax code classification requests in company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/classificationrequests/taxcode'].post
  update:
    x-apievangelist-phrasing:
      intent: Request tax code classification for items
      effect: write
      questions:
      - Can Avalara recommend tax codes for my items if I submit a classification request?
      - How do I ask for my products to be mapped to the right tax codes?
      instructions:
      - text: Submit a tax code classification request for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Ask for tax code recommendations on my items in company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/itemcatalogue/{itemCode}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalogue item by item code
      effect: destructive
      questions:
      - Can I delete an item using its item code rather than its numeric ID?
      - Does deleting a catalogue item also remove its classifications and categories?
      instructions:
      - text: Delete catalogue item with code {itemCode} from company {companyId}.
        slots:
          itemCode: path.itemCode
          companyId: path.companyId
      - text: Remove item code {itemCode} and its product categories from the catalogue.
        slots:
          itemCode: path.itemCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one item by ID
      effect: read
      questions:
      - Can I look up a single item by its numeric ID?
      - What tax code and description are stored on one specific item?
      instructions:
      - text: Get item {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Show the tax code and description on item {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an item
      effect: write
      questions:
      - How do I change the tax code or description on an existing item?
      - Does updating an item replace the whole record?
      instructions:
      - text: Update item {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Replace the record for item {id} with corrected details.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an item by ID
      effect: destructive
      questions:
      - Can I delete an item using its numeric ID?
      - Is removing an item by ID from my company permanent?
      instructions:
      - text: Delete item {id} from company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Remove the item with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one item classification
      effect: read
      questions:
      - Can I fetch a single classification of an item by its ID?
      - What product code does one particular item classification hold?
      instructions:
      - text: Get classification {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Show the product code in classification {id} on item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an item classification
      effect: write
      questions:
      - How do I correct the product code on one classification of an item?
      - Can I change a single classification without touching the item's others?
      instructions:
      - text: Update classification {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Change the product code in classification {id} on item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/classifications/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one item classification
      effect: destructive
      questions:
      - Can I remove just one classification from an item and keep the rest?
      - Is there a way to drop a single tax system code from a product?
      instructions:
      - text: Delete classification {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Remove only classification {id} from item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one item parameter
      effect: read
      questions:
      - Can I look up a single parameter on an item by its ID?
      - What value does one specific tax-affecting property on an item hold?
      instructions:
      - text: Get parameter {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Show the value of parameter {id} on item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one item parameter
      effect: write
      questions:
      - How do I change the value of one tax-affecting property on an item?
      - Can I edit a single item parameter without resubmitting all of them?
      instructions:
      - text: Update parameter {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Change the value of parameter {id} on item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/parameters/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one item parameter
      effect: destructive
      questions:
      - Can I remove a single parameter from an item and leave the others?
      - Is there a way to drop just one grade or measurement value from a product?
      instructions:
      - text: Delete parameter {id} of item {itemId} in company {companyId}.
        slots:
          id: path.id
          itemId: path.itemId
          companyId: path.companyId
      - text: Remove only parameter {id} from item {itemId}.
        slots:
          id: path.id
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemId}/tags/{itemTagDetailId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one tag from an item
      effect: destructive
      questions:
      - Can I take a single tag off an item and keep its other labels?
      - How do I untag one product from a group?
      instructions:
      - text: Delete tag {itemTagDetailId} from item {itemId} in company {companyId}.
        slots:
          itemTagDetailId: path.itemTagDetailId
          itemId: path.itemId
          companyId: path.companyId
      - text: Remove only tag {itemTagDetailId} from item {itemId}.
        slots:
          itemTagDetailId: path.itemTagDetailId
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemCode}/premiumClassification/{systemCode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an item's premium classification
      effect: read
      questions:
      - Can I retrieve the premium classification for an item code in a given system?
      - What premium classification has an item received for a particular system code?
      instructions:
      - text: Get the premium classification for item code {itemCode} under system {systemCode} in company {companyId}.
        slots:
          itemCode: path.itemCode
          systemCode: path.systemCode
          companyId: path.companyId
      - text: Show premium classification {systemCode} for item code {itemCode}.
        slots:
          systemCode: path.systemCode
          itemCode: path.itemCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/classificationrequests/taxcode/{requestId}/recommendations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get tax code recommendations for a request
      effect: read
      questions:
      - Which tax codes were recommended for the items in my classification request?
      - Can I see the suggestions that came back from one tax code request?
      instructions:
      - text: Get tax code recommendations for request {requestId} in company {companyId}.
        slots:
          requestId: path.requestId
          companyId: path.companyId
      - text: Show the suggested tax codes from classification request {requestId}.
        slots:
          requestId: path.requestId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/{itemCode}/restrictions/import/{countryOfImport}'].get
  update:
    x-apievangelist-phrasing:
      intent: List import restrictions for an item by country
      effect: read
      questions:
      - Are there import restrictions on one of my products for a destination country?
      - Can I check what a country restricts before importing a specific item?
      instructions:
      - text: List import restrictions for item code {itemCode} into {countryOfImport} for company {companyId}.
        slots:
          itemCode: path.itemCode
          countryOfImport: path.countryOfImport
          companyId: path.companyId
      - text: Check whether {countryOfImport} restricts importing item {itemCode}.
        slots:
          countryOfImport: path.countryOfImport
          itemCode: path.itemCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List items across all companies
      effect: read
      questions:
      - Can I list items from every company in my account at once?
      - Which items exist across all of my companies, not just one?
      instructions:
      - text: List items across all my companies.
      - text: Show every item in the account regardless of company.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/bytags/{tag}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a company's items by tag
      effect: read
      questions:
      - Which of my items carry a particular grouping tag?
      - Can I pull all products in a company that share one label?
      instructions:
      - text: List items tagged {tag} in company {companyId}.
        slots:
          tag: path.tag
          companyId: path.companyId
      - text: Find every product labelled {tag}.
        slots:
          tag: path.tag
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/itemcatalogue'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync an item catalogue with categories
      effect: write
      questions:
      - Can my accounting system sync its whole item catalogue with Avalara?
      - Is there a way to create or update items along with their AvaTax category?
      instructions:
      - text: Sync the item catalogue for company {companyId}, including AvaTax categories.
        slots:
          companyId: path.companyId
      - text: Push my catalogue items with their extra properties to company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/items/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync a large item list without waiting
      effect: write
      questions:
      - How do I sync a big product list without waiting for each item to be created?
      - What is the per-call limit when syncing items asynchronously?
      instructions:
      - text: Sync up to 1000 items into company {companyId} in the background.
        slots:
          companyId: path.companyId
      - text: Queue an asynchronous item sync for company {companyId}, skipping invalid or duplicate items.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'