# 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 Customer Orders API
  version: 1.0.0
extends: openapi/optimizely-customer-orders-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: 18
- target: $.paths['/api/v1/admin/CustomerOrders'].get
  update:
    x-apievangelist-phrasing:
      intent: List customer orders
      effect: read
      questions:
      - Which customer orders are in the commerce admin right now?
      - Can I filter and sort the full list of customer orders, say by order date?
      - How many customer orders match a given status?
      instructions:
      - text: List all customer orders.
      - text: Show the first {top} customer orders sorted by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      - text: Find customer orders matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer order
      effect: write
      questions:
      - How do I create a new customer order through the admin API?
      - What fields are required when adding an order, like PO number and terms code?
      instructions:
      - text: Create customer order {orderNumber} with customer PO {customerPO} and status {status}.
        slots:
          orderNumber: requestBody.orderNumber
          customerPO: requestBody.customerPO
          status: requestBody.status
      - text: Add a new order for customer {customerId} with ship code {shipCode}.
        slots:
          customerId: requestBody.customerId
          shipCode: requestBody.shipCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer order
      effect: read
      questions:
      - Can I pull up one customer order by its ID?
      - What does a single customer order record contain?
      instructions:
      - text: Show customer order {id}.
        slots:
          id: path.id
      - text: 'Get order {id} with its related entities expanded: {expand}.'
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a customer order
      effect: write
      questions:
      - How do I overwrite an entire customer order record with new values?
      - Does replacing an order require resending every required field?
      instructions:
      - text: Replace customer order {id} with a full record using order number {orderNumber}.
        slots:
          id: path.id
          orderNumber: requestBody.orderNumber
      - text: Overwrite all fields of order {id}, setting status to {status}.
        slots:
          id: path.id
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a customer order
      effect: destructive
      questions:
      - How do I remove a single customer order by ID?
      - Can I make an order delete conditional on an ETag?
      instructions:
      - text: Delete customer order {id}.
        slots:
          id: path.id
      - text: Delete order {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/CustomerOrders({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a customer order
      effect: write
      questions:
      - Can I change just the notes or status on an existing customer order?
      - How do I partially update an order without replacing it?
      instructions:
      - text: Change the status of customer order {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Update the notes on order {id} to {notes}.
        slots:
          id: path.id
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new customer order
      effect: read
      questions:
      - What default values does a brand-new customer order start with?
      - Is there a blank customer order template I can use before creating one?
      instructions:
      - text: Get the default customer order template.
      - text: Show the prefilled defaults for a new customer order.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrders({id})/Default.Totals()'].get
  update:
    x-apievangelist-phrasing:
      intent: Calculate totals for a customer order
      effect: read
      questions:
      - Can I get the calculated totals for a customer order via the OData Totals function?
      - What does the Totals operation return for an order?
      instructions:
      - text: Calculate totals for customer order {id} using the OData Totals function.
        slots:
          id: path.id
      - text: Run the Default.Totals function on order {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/totals'].get
  update:
    x-apievangelist-phrasing:
      intent: Get customer order totals by key route
      effect: read
      questions:
      - Is there a plain route for fetching an order's totals by its key?
      - Where can I read subtotal and tax totals for one order without the OData function syntax?
      instructions:
      - text: Get the totals for customer order {key} from the totals route.
        slots:
          key: path.key
      - text: Fetch order totals via the /totals path for order {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete customer orders
      effect: destructive
      questions:
      - Can I delete several customer orders at once by listing their IDs?
      - How do I bulk remove old orders in one call?
      instructions:
      - text: Delete customer orders {ids} in bulk.
        slots:
          ids: query.ids
      - text: Bulk remove the orders with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/creditcardtransactions({creditcardtransactionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a credit card transaction on an order
      effect: read
      questions:
      - Can I look up a specific credit card transaction recorded against an order?
      - Where do I see the card payment details for one order?
      instructions:
      - text: Show credit card transaction {transaction} on order {key}.
        slots:
          transaction: path.creditcardtransactionKey
          key: path.key
      - text: Get card transaction {transaction} for customer order {key}.
        slots:
          transaction: path.creditcardtransactionKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/customerorderpromotions({customerorderpromotionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion applied to an order
      effect: read
      questions:
      - Which promotion was applied to a given customer order?
      - Can I see the details of one applied promotion on an order?
      instructions:
      - text: Show applied promotion {promotion} on customer order {key}.
        slots:
          promotion: path.customerorderpromotionKey
          key: path.key
      - text: Get order promotion record {promotion} for order {key}.
        slots:
          promotion: path.customerorderpromotionKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/customerordertaxes({customerordertaxKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax line on an order
      effect: read
      questions:
      - Can I inspect one tax line charged on a customer order?
      - What tax was applied to an order under a particular tax record?
      instructions:
      - text: Show tax line {tax} on customer order {key}.
        slots:
          tax: path.customerordertaxKey
          key: path.key
      - text: Get order tax record {tax} for order {key}.
        slots:
          tax: path.customerordertaxKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on an order
      effect: read
      questions:
      - Can I read a custom property stored on a customer order?
      - Where are extra custom fields for an order kept?
      instructions:
      - text: Show custom property {property} on customer order {key}.
        slots:
          property: path.custompropertyKey
          key: path.key
      - text: Get order {key}'s custom field {property}.
        slots:
          property: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/giftcards({giftcardKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a gift card used on an order
      effect: read
      questions:
      - Which gift card was redeemed on a customer order?
      - Can I view one gift card applied to an order?
      instructions:
      - text: Show gift card {giftcard} used on customer order {key}.
        slots:
          giftcard: path.giftcardKey
          key: path.key
      - text: Get gift card {giftcard} for order {key}.
        slots:
          giftcard: path.giftcardKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/orderlines({orderlineKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a line item on an order
      effect: read
      questions:
      - Can I fetch a single order line from a customer order?
      - What product and quantity is on a specific line of an order?
      instructions:
      - text: Show order line {line} on customer order {key}.
        slots:
          line: path.orderlineKey
          key: path.key
      - text: Get line item {line} of order {key}.
        slots:
          line: path.orderlineKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/orderpromotioncodes({orderpromotioncodeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promo code entered on an order
      effect: read
      questions:
      - Which promo code did the buyer enter on a customer order?
      - Can I look up one promotion code record attached to an order?
      instructions:
      - text: Show promo code entry {code} on customer order {key}.
        slots:
          code: path.orderpromotioncodeKey
          key: path.key
      - text: Get the entered promotion code {code} for order {key}.
        slots:
          code: path.orderpromotioncodeKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerorders({key})/subscriptions({subscriptionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription tied to an order
      effect: read
      questions:
      - Can I see a subscription that was created from a customer order?
      - What subscription details are linked to an order?
      instructions:
      - text: Show subscription {subscription} on customer order {key}.
        slots:
          subscription: path.subscriptionKey
          key: path.key
      - text: Get subscription {subscription} linked to order {key}.
        slots:
          subscription: path.subscriptionKey
          key: path.key
      method: generated
      generated: '2026-09-26'