# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Storefront API V1 Billtos API
  version: 1.0.0
extends: openapi/optimizely-billtos-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: 8
- target: $.paths['/api/v1/billtos/{billToId}/shiptos/{shipToId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ship-to address under a bill-to
      effect: read
      questions:
      - How do I look up a specific ship-to address for a billing account?
      - Can I see whether a particular ship-to is the default or a one-time address?
      instructions:
      - text: Get ship-to {shipToId} under bill-to {billToId}.
        slots:
          shipToId: path.shipToId
          billToId: path.billToId
      - text: Show the address details of ship-to {shipToId} for account {billToId}.
        slots:
          shipToId: path.shipToId
          billToId: path.billToId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos/{billToId}/shiptos/{shipToId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a ship-to address
      effect: write
      questions:
      - How do I change the street or city on an existing ship-to address?
      - Can I make one of my ship-to addresses the default?
      instructions:
      - text: Update ship-to {shipToId} on bill-to {billToId} to {address1}, {city} {postalCode}.
        slots:
          shipToId: path.shipToId
          billToId: path.billToId
          address1: requestBody.address1
          city: requestBody.city
          postalCode: requestBody.postalCode
      - text: 'Make ship-to {shipToId} the default for bill-to {billToId}: {isDefault}.'
        slots:
          shipToId: path.shipToId
          billToId: path.billToId
          isDefault: requestBody.isDefault
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos/{billToId}/shiptos'].get
  update:
    x-apievangelist-phrasing:
      intent: List ship-to addresses for a bill-to
      effect: read
      questions:
      - Which shipping addresses are on file for a billing account?
      - Can I filter, sort and page the ship-tos under a bill-to?
      instructions:
      - text: List the ship-to addresses for bill-to {billToId}.
        slots:
          billToId: path.billToId
      - text: List ship-tos for bill-to {billToId} matching {filter}, page {page}.
        slots:
          billToId: path.billToId
          filter: query.apiParameter.filter
          page: query.apiParameter.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos/{billToId}/shiptos'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a ship-to address to a bill-to
      effect: write
      questions:
      - How do I add a new shipping address to a customer's billing account?
      - Can I create a one-time ship-to address that isn't saved for reuse?
      instructions:
      - text: Add a ship-to for bill-to {billToId} at {address1}, {city}, {state} {postalCode}.
        slots:
          billToId: path.billToId
          address1: requestBody.address1
          city: requestBody.city
          state: requestBody.state
          postalCode: requestBody.postalCode
      - text: Create a one-time ship-to for {companyName} under bill-to {billToId}.
        slots:
          companyName: requestBody.companyName
          billToId: path.billToId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos'].get
  update:
    x-apievangelist-phrasing:
      intent: List bill-to billing accounts
      effect: read
      questions:
      - Which billing accounts can the current storefront user order against?
      - Can I page and sort the list of bill-to addresses?
      instructions:
      - text: List my bill-to accounts.
      - text: List bill-tos matching {filter}, sorted by {sort}.
        slots:
          filter: query.parameter.filter
          sort: query.parameter.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a bill-to billing account
      effect: write
      questions:
      - How do I create a new billing address for a customer?
      - Can I create a guest bill-to during checkout?
      instructions:
      - text: Create a bill-to for {companyName} at {address1}, {city} {postalCode}.
        slots:
          companyName: requestBody.companyName
          address1: requestBody.address1
          city: requestBody.city
          postalCode: requestBody.postalCode
      - text: Create a guest bill-to with email {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos/{billToId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one bill-to billing account
      effect: read
      questions:
      - How do I view the details of a single billing account, including its cost codes?
      - What budget enforcement level applies to a given bill-to?
      instructions:
      - text: Get bill-to {billToId}.
        slots:
          billToId: path.billToId
      - text: Show the billing address and cost codes for bill-to {billToId}.
        slots:
          billToId: path.billToId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billtos/{billToId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a bill-to billing account
      effect: write
      questions:
      - How do I change the billing address or contact on a bill-to?
      - Can I update the email and phone on an existing billing account?
      instructions:
      - text: Update bill-to {billToId} to billing address {address1}, {city}.
        slots:
          billToId: path.billToId
          address1: requestBody.address1
          city: requestBody.city
      - text: Change the email on bill-to {billToId} to {email}.
        slots:
          billToId: path.billToId
          email: requestBody.email
      method: generated
      generated: '2026-09-26'