# 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 Ship Rules API
  version: 1.0.0
extends: openapi/optimizely-ship-rules-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: 9
- target: $.paths['/api/v1/admin/ShipRules'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipping rules
      effect: read
      questions:
      - How do I see all the rules that decide which carriers and ship methods apply to an order?
      - Can I filter shipping rules by country or rule type?
      - Which ship rules run in a given execution group?
      instructions:
      - text: List all ship rules.
      - text: List ship rules matching {filter}, ordered by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRules'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shipping rule
      effect: write
      questions:
      - How do I add a rule that restricts a ship method by postal code range or order amount?
      - What rule type, condition and terms code does a new ship rule need?
      instructions:
      - text: Create a {shipRuleType} ship rule with condition {condition} and terms code {termsCode}.
        slots:
          shipRuleType: requestBody.shipRuleType
          condition: requestBody.condition
          termsCode: requestBody.termsCode
      - text: Add a ship rule for carrier {carrierId} covering postal codes {postalCodeLowerRange} to {postalCodeUpperRange}.
        slots:
          carrierId: requestBody.carrierId
          postalCodeLowerRange: requestBody.postalCodeLowerRange
          postalCodeUpperRange: requestBody.postalCodeUpperRange
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRules({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one shipping rule
      effect: read
      questions:
      - How do I look up the conditions on a single ship rule?
      - Can I fetch a shipping rule by its ID?
      instructions:
      - text: Get ship rule {id}.
        slots:
          id: path.id
      - text: Show the condition and limits set on ship rule {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRules({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a shipping rule
      effect: write
      questions:
      - How do I overwrite a whole ship rule definition?
      - Is there a way to fully replace a shipping rule instead of patching it?
      instructions:
      - text: Replace ship rule {id} with type {shipRuleType}, condition {condition} and terms {termsCode}.
        slots:
          id: path.id
          shipRuleType: requestBody.shipRuleType
          condition: requestBody.condition
          termsCode: requestBody.termsCode
      - text: Overwrite shipping rule {id} with a complete new definition.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRules({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shipping rule
      effect: destructive
      questions:
      - How do I remove one shipping rule?
      - Can I delete a ship rule only if its ETag still matches?
      instructions:
      - text: Delete ship rule {id}.
        slots:
          id: path.id
      - text: Remove shipping rule {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/ShipRules({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust limits on a shipping rule
      effect: write
      questions:
      - How do I change the minimum or maximum order amount on a ship rule?
      - Can I change the execution order of an existing shipping rule?
      instructions:
      - text: Set the order amount range of ship rule {id} to {minimumAmount} through {maximumAmount}.
        slots:
          id: path.id
          minimumAmount: requestBody.minimumAmount
          maximumAmount: requestBody.maximumAmount
      - text: Move ship rule {id} to execution order {executionOrder}.
        slots:
          id: path.id
          executionOrder: requestBody.executionOrder
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRules/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank shipping rule template
      effect: read
      questions:
      - What default values does a new ship rule start with?
      - Can I fetch an empty shipping rule template before creating one?
      instructions:
      - text: Fetch the default ship rule template.
      - text: Show me the starting values for a new shipping rule.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shiprules/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete shipping rules
      effect: destructive
      questions:
      - How do I delete several ship rules at once?
      - Can I clear out a batch of shipping rules by ID?
      instructions:
      - text: Bulk delete the ship rules with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these shipping rules in one call: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shiprules({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a shipping rule
      effect: read
      questions:
      - How do I read a custom property stored on a ship rule?
      - Can I fetch one extra field value from a shipping rule?
      instructions:
      - text: Get custom property {custompropertyKey} on ship rule {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of shipping rule {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'