# 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 Carrier Zones API
  version: 1.0.0
extends: openapi/optimizely-carrier-zones-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: 11
- target: $.paths['/api/v1/admin/CarrierZones'].get
  update:
    x-apievangelist-phrasing:
      intent: List carrier shipping zones
      effect: read
      questions:
      - Which shipping zones are set up for my carriers?
      - Can I filter carrier zones by carrier and count how many there are?
      instructions:
      - text: List all carrier zones.
      - text: List carrier zones matching {filter} and include a total count.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a shipping zone to a carrier
      effect: write
      questions:
      - How do I define a new shipping zone for a carrier?
      - What does a carrier zone need besides the zone name?
      instructions:
      - text: Create zone {zone} for carrier {carrierId}.
        slots:
          zone: requestBody.zone
          carrierId: requestBody.carrierId
      - text: Add a new carrier zone called {zone}.
        slots:
          zone: requestBody.zone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one carrier zone
      effect: read
      questions:
      - How do I look up a single carrier zone by its ID?
      - Can I expand the rates or postal ranges when reading one carrier zone?
      instructions:
      - text: Get carrier zone {id}.
        slots:
          id: path.id
      - text: Show carrier zone {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a carrier zone record
      effect: write
      questions:
      - How do I overwrite a carrier zone with a complete new record?
      - Does a full replace of a carrier zone reset fields I leave out?
      instructions:
      - text: Replace carrier zone {id} with zone {zone} for carrier {carrierId}.
        slots:
          id: path.id
          zone: requestBody.zone
          carrierId: requestBody.carrierId
      - text: Fully overwrite carrier zone {id} as {zone}.
        slots:
          id: path.id
          zone: requestBody.zone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a carrier zone
      effect: destructive
      questions:
      - How do I remove one shipping zone from a carrier?
      - Can I make a carrier zone delete conditional on its ETag?
      instructions:
      - text: Delete carrier zone {id}.
        slots:
          id: path.id
      - text: Delete carrier zone {id} if its ETag still matches {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or reassign a carrier zone
      effect: write
      questions:
      - Can I just rename a carrier zone without touching its other fields?
      - How do I move an existing zone over to a different carrier?
      instructions:
      - text: Rename carrier zone {id} to {zone}.
        slots:
          id: path.id
          zone: requestBody.zone
      - text: Move carrier zone {id} to carrier {carrierId}.
        slots:
          id: path.id
          carrierId: requestBody.carrierId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CarrierZones/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the Default function on carrier zones
      effect: read
      questions:
      - What does the Default OData function on carrier zones give back?
      - Is there a default carrier zone entity I can read as a template?
      instructions:
      - text: Call the Default function on carrier zones.
      - text: Get the default carrier zone entity.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carrierzones/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete carrier zones by ID
      effect: destructive
      questions:
      - Can I remove several carrier zones in a single request?
      - How do I clear out a list of old shipping zones at once?
      instructions:
      - text: Bulk delete carrier zones {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these carrier zones together: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carrierzones({key})/carrierzonepostalcoderanges({carrierzonepostalcoderangeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a postal code range in a carrier zone
      effect: read
      questions:
      - Which postal code ranges fall inside a given carrier zone?
      - Can I look up one postal code range that defines a shipping zone?
      instructions:
      - text: Get postal code range {carrierzonepostalcoderangeKey} of carrier zone {key}.
        slots:
          carrierzonepostalcoderangeKey: path.carrierzonepostalcoderangeKey
          key: path.key
      - text: Show the zip range {carrierzonepostalcoderangeKey} assigned to zone {key}.
        slots:
          carrierzonepostalcoderangeKey: path.carrierzonepostalcoderangeKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carrierzones({key})/carrierzonerates({carrierzonerateKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping rate in a carrier zone
      effect: read
      questions:
      - What shipping rate applies inside a particular carrier zone?
      - Can I read one rate entry configured for a carrier zone?
      instructions:
      - text: Get rate {carrierzonerateKey} for carrier zone {key}.
        slots:
          carrierzonerateKey: path.carrierzonerateKey
          key: path.key
      - text: Show the shipping rate {carrierzonerateKey} in zone {key}.
        slots:
          carrierzonerateKey: path.carrierzonerateKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carrierzones({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a carrier zone
      effect: read
      questions:
      - How do I read a custom property stored on a carrier zone?
      - Can carrier zones hold custom fields I can fetch one at a time?
      instructions:
      - text: Get custom property {custompropertyKey} of carrier zone {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Read carrier zone {key}'s custom field {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'