# 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 Carriers API
  version: 1.0.0
extends: openapi/optimizely-carriers-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: 16
- target: $.paths['/api/v1/admin/Carriers'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipping carriers
      effect: read
      questions:
      - Which shipping carriers are configured in Optimizely Commerce?
      - Can I narrow the carrier list to only enabled, live carriers?
      instructions:
      - text: List all shipping carriers.
      - text: Show carriers matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a shipping carrier
      effect: write
      questions:
      - What credentials and URLs do I need to register a new carrier?
      - Can a new carrier authenticate with OAuth client credentials instead of a password?
      instructions:
      - text: Create carrier {name} with account number {accountNumber} and rating service {ratingService}.
        slots:
          name: requestBody.name
          accountNumber: requestBody.accountNumber
          ratingService: requestBody.ratingService
      - text: Add carrier {name} using tracking URL {trackingUrl} and contact email {contactEmail}.
        slots:
          name: requestBody.name
          trackingUrl: requestBody.trackingUrl
          contactEmail: requestBody.contactEmail
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one shipping carrier
      effect: read
      questions:
      - What settings are stored for a single carrier?
      - Can I look up a carrier's live and test URLs by its id?
      instructions:
      - text: Fetch carrier {id}.
        slots:
          id: path.id
      - text: Show the configuration of carrier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a shipping carrier's full setup
      effect: write
      questions:
      - Can I overwrite a carrier's entire configuration in one call?
      - Does replacing a carrier mean resending every required credential field?
      instructions:
      - text: Replace carrier {id} with name {name} and live URL {liveUrl}.
        slots:
          id: path.id
          name: requestBody.name
          liveUrl: requestBody.liveUrl
      - text: Overwrite the whole record of carrier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one shipping carrier
      effect: destructive
      questions:
      - How do I remove a single shipping carrier?
      - Can deleting a carrier be guarded by an ETag check?
      instructions:
      - text: Delete carrier {id}.
        slots:
          id: path.id
      - text: Delete carrier {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update selected carrier settings
      effect: write
      questions:
      - Can I switch a carrier from test to live mode without resending everything?
      - Is there a way to set a backup carrier for an existing one?
      instructions:
      - text: Set carrier {id} live flag to {isLive}.
        slots:
          id: path.id
          isLive: requestBody.isLive
      - text: Make {backUpCarrierId} the backup for carrier {id}.
        slots:
          id: path.id
          backUpCarrierId: requestBody.backUpCarrierId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Carriers/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new carrier
      effect: read
      questions:
      - What defaults does a new carrier record start with?
      - Is there a blank carrier template to fill in?
      instructions:
      - text: Get the default field values for a new carrier.
      - text: Show the empty carrier template.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete shipping carriers
      effect: destructive
      questions:
      - Can I remove several carriers in one request?
      - Is there a batch delete for carriers by a list of ids?
      instructions:
      - text: Bulk delete carriers {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every carrier in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/carrierpackages({carrierpackageKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a package type offered by a carrier
      effect: read
      questions:
      - Which package definitions belong to a carrier?
      - Can I read one carrier package record through its carrier?
      instructions:
      - text: Get package {carrierpackageKey} of carrier {key}.
        slots:
          key: path.key
          carrierpackageKey: path.carrierpackageKey
      - text: Show carrier package {carrierpackageKey} under carrier {key}.
        slots:
          key: path.key
          carrierpackageKey: path.carrierpackageKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/carrierzones({carrierzoneKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping zone of a carrier
      effect: read
      questions:
      - What shipping zones has a carrier been set up with?
      - Can I fetch a single carrier zone by key?
      instructions:
      - text: Get zone {carrierzoneKey} of carrier {key}.
        slots:
          key: path.key
          carrierzoneKey: path.carrierzoneKey
      - text: Show carrier zone {carrierzoneKey} for carrier {key}.
        slots:
          key: path.key
          carrierzoneKey: path.carrierzoneKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/customers({customerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer assigned to a carrier
      effect: read
      questions:
      - Which customers are linked to a particular carrier?
      - Can I check one customer's association with a carrier?
      instructions:
      - text: Get customer {customerKey} assigned to carrier {key}.
        slots:
          key: path.key
          customerKey: path.customerKey
      - text: Show customer {customerKey} linked to carrier {key}.
        slots:
          key: path.key
          customerKey: path.customerKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a carrier
      effect: read
      questions:
      - How can I read a custom property stored on a carrier?
      - Can I fetch one custom field value from a carrier record?
      instructions:
      - text: Get custom property {custompropertyKey} of carrier {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on carrier {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/shipcharges({shipchargeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping charge of a carrier
      effect: read
      questions:
      - What shipping charges are defined for a carrier?
      - Can I look up one ship charge entry through its carrier?
      instructions:
      - text: Get ship charge {shipchargeKey} of carrier {key}.
        slots:
          key: path.key
          shipchargeKey: path.shipchargeKey
      - text: Show shipping charge {shipchargeKey} for carrier {key}.
        slots:
          key: path.key
          shipchargeKey: path.shipchargeKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/shiprules({shipruleKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping rule of a carrier
      effect: read
      questions:
      - Which shipping rules apply to a carrier?
      - Can I read one ship rule attached to a carrier?
      instructions:
      - text: Get ship rule {shipruleKey} of carrier {key}.
        slots:
          key: path.key
          shipruleKey: path.shipruleKey
      - text: Show shipping rule {shipruleKey} under carrier {key}.
        slots:
          key: path.key
          shipruleKey: path.shipruleKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/shipvias({shipviaKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ship via service of a carrier
      effect: read
      questions:
      - What ship via service levels does a carrier offer?
      - Can I fetch one ship via option, like ground or overnight, for a carrier?
      instructions:
      - text: Get ship via {shipviaKey} of carrier {key}.
        slots:
          key: path.key
          shipviaKey: path.shipviaKey
      - text: Show ship via service {shipviaKey} offered by carrier {key}.
        slots:
          key: path.key
          shipviaKey: path.shipviaKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/carriers({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website that uses a carrier
      effect: read
      questions:
      - Which storefront websites is a carrier enabled on?
      - Can I check whether one website is linked to a carrier?
      instructions:
      - text: Get website {websiteKey} linked to carrier {key}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
      - text: Show website {websiteKey} that uses carrier {key}.
        slots:
          key: path.key
          websiteKey: path.websiteKey
      method: generated
      generated: '2026-09-26'