# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Commerce Partner Orders API
  version: 1.0.0
extends: openapi/adobe-suite-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: 9
- target: $.paths['/v2/customers/{customer-id}/orderpreviews'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview an order before placing it
      effect: read
      questions:
      - Can I preview pricing for an order before actually placing it?
      - How do I check what an order would look like for a customer?
      instructions:
      - text: Preview an order for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          currency: requestBody.currencyCode
      - text: Show a preview of ordering {items} for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          items: requestBody.lineItems
          currency: requestBody.currencyCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer-id}/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's order history (v2)
      effect: read
      questions:
      - How do I pull a customer's order history using the v2 API?
      - Does the v2 order history endpoint support any filters?
      instructions:
      - text: List v2 order history for customer {customer}.
        slots:
          customer: path.customer-id
      - text: Show all orders for customer {customer} from the v2 endpoint.
        slots:
          customer: path.customer-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer-id}/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Place an order for a customer (v2)
      effect: write
      questions:
      - How do I place an order for a customer with the v2 orders API?
      - What currency and line items does a v2 order need?
      instructions:
      - text: Place a v2 order for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          currency: requestBody.currencyCode
      - text: Using v2, order {items} for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          items: requestBody.lineItems
          currency: requestBody.currencyCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer-id}/orders/{order-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's details (v2)
      effect: read
      questions:
      - How do I read one order's details using the v2 API?
      - What line items were on a specific v2 order?
      instructions:
      - text: Get v2 order {order} for customer {customer}.
        slots:
          customer: path.customer-id
          order: path.order-id
      - text: Show the details of order {order} for customer {customer} via v2.
        slots:
          customer: path.customer-id
          order: path.order-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customers/{customer-id}/orders/{order-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel a customer's order
      effect: destructive
      questions:
      - How do I cancel an order that was placed for a customer?
      - Can I cancel an order after it's been submitted?
      instructions:
      - text: Cancel order {order} for customer {customer}; the currency is {currency}.
        slots:
          customer: path.customer-id
          order: path.order-id
          currency: requestBody.currencyCode
      - text: Cancel customer {customer}'s order {order}.
        slots:
          customer: path.customer-id
          order: path.order-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/customers/{customer-id}/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: Search a customer's order history (v3)
      effect: read
      questions:
      - Can I filter a customer's orders by date range or status?
      - How do I find orders for a specific subscription or offer?
      - Which orders reference an earlier order ID?
      instructions:
      - text: List v3 orders for customer {customer} between {start} and {end}.
        slots:
          customer: path.customer-id
          start: query.start-date
          end: query.end-date
      - text: Show orders for customer {customer} with status {status}.
        slots:
          customer: path.customer-id
          status: query.status
      - text: Find orders for customer {customer} on subscription {subscription}.
        slots:
          customer: path.customer-id
          subscription: query.subscription-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/customers/{customer-id}/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Place an order for a customer (v3)
      effect: write
      questions:
      - How do I create a new order or renewal with the v3 orders API?
      - Can I pass an external reference ID on a v3 order?
      instructions:
      - text: Place a v3 order for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          currency: requestBody.currencyCode
      - text: On v3, order {items} for customer {customer} in {currency} as type {type}.
        slots:
          customer: path.customer-id
          items: requestBody.lineItems
          currency: requestBody.currencyCode
          type: requestBody.orderType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/customers/{customer-id}/orders/{order-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order's details (v3)
      effect: read
      questions:
      - How do I check the status of a single order on v3?
      - Can I see an order's line items from the v3 endpoint?
      instructions:
      - text: Get v3 order {order} for customer {customer}.
        slots:
          customer: path.customer-id
          order: path.order-id
      - text: Check the status of order {order} for customer {customer} on v3.
        slots:
          customer: path.customer-id
          order: path.order-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/customers/{customer-id}/orders/{order-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set an order's external reference ID
      effect: write
      questions:
      - How do I change the external reference ID on an existing order?
      - Can I tag an order with my own system's reference after it's placed?
      instructions:
      - text: Set external reference {ref} on order {order} for customer {customer} in {currency}.
        slots:
          customer: path.customer-id
          order: path.order-id
          ref: requestBody.externalReferenceId
          currency: requestBody.currencyCode
      - text: Update the external reference ID of order {order} for customer {customer}.
        slots:
          customer: path.customer-id
          order: path.order-id
      method: generated
      generated: '2026-09-26'