# 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 States API
  version: 1.0.0
extends: openapi/optimizely-states-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: 13
- target: $.paths['/api/v1/admin/States'].get
  update:
    x-apievangelist-phrasing:
      intent: List states and provinces
      effect: read
      questions:
      - Which states and provinces are set up in the Optimizely Configured Commerce admin?
      - Can I filter the state list to only active, taxable states?
      - Is there a way to get a count of states along with the results?
      instructions:
      - text: List all states in the commerce admin.
      - text: List states matching {filter}, ordered by {orderby}, top {top}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
          top: query.$top
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a state with its tax settings
      effect: write
      questions:
      - What tax codes and descriptions do I need to add a new state?
      - Can I set a state's tax rate and handling amount when creating it?
      instructions:
      - text: Create state {name} ({abbreviation}) with tax code {taxCode}, tax code 2 {taxCode2}, tax description {taxDescription} and tax description 2 {taxDescription2}.
        slots:
          name: requestBody.name
          abbreviation: requestBody.abbreviation
          taxCode: requestBody.taxCode
          taxCode2: requestBody.taxCode2
          taxDescription: requestBody.taxDescription
          taxDescription2: requestBody.taxDescription2
      - text: Add state {abbreviation} under country {countryId} with tax rate {taxRate}.
        slots:
          abbreviation: requestBody.abbreviation
          countryId: requestBody.countryId
          taxRate: requestBody.taxRate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one state by ID
      effect: read
      questions:
      - How do I look up a single state's tax configuration by its ID?
      - Can I expand related data when fetching one state record?
      instructions:
      - text: Show state {id}.
        slots:
          id: path.id
      - text: Fetch state {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a state record entirely
      effect: write
      questions:
      - Can I overwrite a state with a complete new set of tax values?
      - What happens to state fields I leave out when replacing the whole record?
      instructions:
      - text: Replace state {id} with a full record named {name}, abbreviation {abbreviation}.
        slots:
          id: path.id
          name: requestBody.name
          abbreviation: requestBody.abbreviation
      - text: Overwrite every field of state {id}, setting tax description to {taxDescription}.
        slots:
          id: path.id
          taxDescription: requestBody.taxDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single state
      effect: destructive
      questions:
      - How do I remove one state from the admin by its ID?
      - Can I make a state delete conditional on an ETag?
      instructions:
      - text: Delete state {id}.
        slots:
          id: path.id
      - text: Delete state {id} only if its ETag still matches {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update selected fields on a state
      effect: write
      questions:
      - Can I change just a state's tax rate without resending everything?
      - How would I deactivate a state or stop taxing freight there?
      instructions:
      - text: Patch state {id} so its tax rate is {taxRate}.
        slots:
          id: path.id
          taxRate: requestBody.taxRate
      - text: Update state {id} to set active to {isActive} and tax freight to {taxFreight}.
        slots:
          id: path.id
          isActive: requestBody.isActive
          taxFreight: requestBody.taxFreight
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new state
      effect: read
      questions:
      - What default values does the admin pre-fill for a state before I create one?
      - Where do I get a blank state template?
      instructions:
      - text: Get the default state template.
      - text: Show me the pre-filled defaults for a new state.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/States/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive states with the archive action
      effect: destructive
      questions:
      - Can I archive several states at once with the OData archive action?
      - Is there a POST action that archives a batch of states by ID?
      instructions:
      - text: Archive states {ids} using the archive action.
        slots:
          ids: query.ids
      - text: Run the POST archive action on state IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/states/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive states through the archive route
      effect: destructive
      questions:
      - Is there a DELETE-style route for archiving a list of states?
      - Which endpoint archives states when called with a DELETE request?
      instructions:
      - text: Archive states {ids} through the DELETE archive route.
        slots:
          ids: query.ids
      - text: Send a DELETE to the states archive route for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/states/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete states by ID
      effect: destructive
      questions:
      - How do I permanently delete several states in one request?
      - Can I bulk-remove states rather than archive them?
      instructions:
      - text: Bulk delete states {ids}.
        slots:
          ids: query.ids
      - text: Permanently remove the states with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/states({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a state
      effect: read
      questions:
      - How can I read one custom property attached to a state?
      - Can I select only certain fields of a state's custom property?
      instructions:
      - text: Show custom property {custompropertyKey} on state {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Fetch state {key}'s custom property {custompropertyKey}, selecting {select}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/states({key})/taxexemptions({taxexemptionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax exemption linked to a state
      effect: read
      questions:
      - Which tax exemption details apply to a particular state?
      - Can I look up one tax exemption record under a state?
      instructions:
      - text: Show tax exemption {taxexemptionKey} for state {key}.
        slots:
          taxexemptionKey: path.taxexemptionKey
          key: path.key
      - text: Fetch state {key}'s tax exemption {taxexemptionKey} with {expand} expanded.
        slots:
          key: path.key
          taxexemptionKey: path.taxexemptionKey
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/states({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website linked to a state
      effect: read
      questions:
      - Which website is a state assigned to, looked up by both keys?
      - Can I fetch one website record through its state?
      instructions:
      - text: Show website {websiteKey} linked to state {key}.
        slots:
          websiteKey: path.websiteKey
          key: path.key
      - text: Fetch state {key}'s website {websiteKey}, selecting {select}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
          select: query.$select
      method: generated
      generated: '2026-09-26'