# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for VirtoCommerce.Orders Order Management API
  version: 1.0.0
extends: openapi/virto-commerce-order-management-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: 35
- target: $.paths['/api/order/customerOrders/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search customer orders
      effect: read
      questions:
      - How do I find all orders placed by one customer?
      - Can I filter orders by status and a date range?
      - Which orders used a particular promotion or contain a given product?
      instructions:
      - text: Search orders placed by customer {customerId}.
        slots:
          customerId: requestBody.customerId
      - text: Find orders with status {status} created between {startDate} and {endDate}.
        slots:
          status: requestBody.status
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      - text: List orders for organization {organizationId} that include product {productId}.
        slots:
          organizationId: requestBody.organizationId
          productId: requestBody.productId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/number/{number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order by its order number
      effect: read
      questions:
      - Can I look up an order using the order number the customer gave me?
      - What comes back when fetching an order by its human-readable number?
      instructions:
      - text: Get order number {number}.
        slots:
          number: path.number
      - text: Look up the customer order with number {number}.
        slots:
          number: path.number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order by ID
      effect: read
      questions:
      - How do I load a customer order with all its shipments and payments by internal ID?
      - Does fetching an order by ID return null when it doesn't exist?
      instructions:
      - text: Get customer order {id}.
        slots:
          id: path.id
      - text: Load order {id} with response group {respGroup}.
        slots:
          id: path.id
          respGroup: query.respGroup
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update an order
      effect: write
      questions:
      - Can I change a single field on an order without resending the whole document?
      - What is the way to JSON-patch a customer order?
      instructions:
      - text: Patch order {id} with only the changed fields.
        slots:
          id: path.id
      - text: Apply a partial update to customer order {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/outer/{outerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order by external ID
      effect: read
      questions:
      - Can I find an order using the ID from my ERP or external system?
      - Which lookup works when I only have an order's outer ID?
      instructions:
      - text: Get the order with external ID {outerId}.
        slots:
          outerId: path.outerId
      - text: Find the customer order whose outer ID is {outerId}.
        slots:
          outerId: path.outerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/recalculate'].put
  update:
    x-apievangelist-phrasing:
      intent: Recalculate order totals
      effect: read
      questions:
      - How do I get updated totals after editing items on an order?
      - Can I preview recalculated order totals before saving?
      instructions:
      - text: Recalculate totals for order {number}.
        slots:
          number: requestBody.number
      - text: Return this order with its totals recalculated.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{orderId}/processPayment/{paymentId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Process an order payment with the gateway
      effect: write
      questions:
      - How do I push an order's payment through the external payment system?
      - Can I pass bank card details when registering an order payment at checkout?
      instructions:
      - text: Process payment {paymentId} for order {orderId}.
        slots:
          paymentId: path.paymentId
          orderId: path.orderId
      - text: Charge payment {paymentId} on order {orderId} using the card held by {cardholderName}.
        slots:
          paymentId: path.paymentId
          orderId: path.orderId
          cardholderName: requestBody.cardholderName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{cartId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn a shopping cart into an order
      effect: write
      questions:
      - How do I convert a customer's cart into a placed order?
      - Can I check out a cart by its ID to create the order?
      instructions:
      - text: Create an order from cart {cartId}.
        slots:
          cartId: path.cartId
      - text: Check out shopping cart {cartId} into a customer order.
        slots:
          cartId: path.cartId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing order
      effect: write
      questions:
      - How do I change the status of an order that already exists?
      - Can I add a purchase order number to an existing order?
      instructions:
      - text: Set the status of existing order {number} to {status}.
        slots:
          number: requestBody.number
          status: requestBody.status
      - text: Add purchase order number {purchaseOrderNumber} to existing order {number}.
        slots:
          purchaseOrderNumber: requestBody.purchaseOrderNumber
          number: requestBody.number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an order directly
      effect: write
      questions:
      - Can I create an order from scratch without a shopping cart?
      - What is needed to enter a manual order for a customer in a store?
      instructions:
      - text: Create a new order for customer {customerId} in store {storeId}.
        slots:
          customerId: requestBody.customerId
          storeId: requestBody.storeId
      - text: Enter a manual order in {currency} for customer {customerName}.
        slots:
          currency: requestBody.currency
          customerName: requestBody.customerName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete customer orders
      effect: destructive
      questions:
      - How do I permanently delete orders?
      - Can several customer orders be deleted at once?
      instructions:
      - text: Delete orders {ids}.
        slots:
          ids: query.ids
      - text: Remove the customer orders with IDs {ids} entirely.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{id}/shipments/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a prefilled new shipment for an order
      effect: read
      questions:
      - Is there a template shipment with required fields filled for a given order?
      - How do I start a new shipment document for an order?
      instructions:
      - text: Get a new shipment template for order {id}.
        slots:
          id: path.id
      - text: Prepare a blank shipment for customer order {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{id}/payments/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a prefilled new payment for an order
      effect: read
      questions:
      - Is there a template payment with required fields filled in for an order?
      - How do I start a new payment document on an order?
      instructions:
      - text: Get a new payment template for order {id}.
        slots:
          id: path.id
      - text: Prepare a blank payment for customer order {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/dashboardStatistics/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get order dashboard statistics settings
      effect: read
      questions:
      - What settings drive the order statistics dashboard?
      - Where can I see how the Commerce Manager dashboard stats are configured?
      instructions:
      - text: Get the order dashboard statistics settings.
      - text: Show the configuration for order dashboard stats.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/dashboardStatistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get order statistics for a period
      effect: read
      questions:
      - What were my order totals and statistics for last month?
      - Can I pull order dashboard figures for a custom date range?
      instructions:
      - text: Get order statistics from {start} to {end}.
        slots:
          start: query.start
          end: query.end
      - text: Show the Commerce Manager order dashboard numbers.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/paymentcallback'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a payment callback as key-value parameters
      effect: write
      questions:
      - Where does a payment provider post its callback parameters as JSON key-value pairs?
      - Which callback endpoint accepts a parameters array after a payment?
      instructions:
      - text: Post these payment callback parameters {parameters} to finish processing.
        slots:
          parameters: requestBody.parameters
      - text: Send the gateway's key-value callback to post-process the payment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/paymentcallback-raw'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a raw-body payment callback
      effect: write
      questions:
      - Which callback URL takes the payment provider's raw request body unchanged?
      - Can a gateway notify the store with an unparsed raw payload?
      instructions:
      - text: Forward this raw gateway payload to the raw payment callback.
      - text: Post-process the payment using the raw callback body.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/paymentcallback-form'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a form-encoded payment callback
      effect: write
      questions:
      - Which callback endpoint handles a form-posted payment notification?
      - Can a gateway that submits HTML form data report payment results?
      instructions:
      - text: Submit this form-encoded payment notification to the form callback.
      - text: Post-process the payment from the gateway's form post.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/invoice/{orderNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an order invoice PDF
      effect: read
      questions:
      - How do I get a PDF invoice for an order?
      - Can I download an invoice using just the order number?
      instructions:
      - text: Download the invoice PDF for order {orderNumber}.
        slots:
          orderNumber: path.orderNumber
      - text: Get the invoice for order number {orderNumber}.
        slots:
          orderNumber: path.orderNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/{id}/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the change history of an order
      effect: read
      questions:
      - What changes have been made to a specific order over time?
      - Who edited this order and when?
      instructions:
      - text: Show the change history of order {id}.
        slots:
          id: path.id
      - text: List every change logged on customer order {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/searchChanges'].post
  update:
    x-apievangelist-phrasing:
      intent: Search order change logs
      effect: read
      questions:
      - Can I search order changes across a date range?
      - Which order edits of a certain operation type happened last week?
      instructions:
      - text: Search order changes between {startDate} and {endDate}.
        slots:
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      - text: Find changes of type {operationTypes} on order {orderId}.
        slots:
          operationTypes: requestBody.operationTypes
          orderId: requestBody.orderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/indexed/searchEnabled'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if indexed order search is enabled
      effect: read
      questions:
      - Is full-text indexed search turned on for orders?
      - Can I tell whether the order search index is available before using it?
      instructions:
      - text: Check whether indexed order search is enabled.
      - text: Tell me if full-text search is on for customer orders.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/customerOrders/indexed/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Full-text search orders with facets
      effect: read
      questions:
      - Can I run a full-text order search that returns facets?
      - What is the fastest way to search orders through the search index by keyword?
      instructions:
      - text: Full-text search the order index for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Search indexed orders by {keyword} with facet {facet}.
        slots:
          keyword: requestBody.keyword
          facet: requestBody.facet
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search order payments
      effect: read
      questions:
      - Which payments were captured in a given date range?
      - Can I list all payments for one order number?
      - Can I find a customer's payments filtered by status?
      instructions:
      - text: List payments for order number {orderNumber}.
        slots:
          orderNumber: requestBody.orderNumber
      - text: Find payments captured between {capturedStartDate} and {capturedEndDate}.
        slots:
          capturedStartDate: requestBody.capturedStartDate
          capturedEndDate: requestBody.capturedEndDate
      - text: Search payments by customer {customerId} with status {status}.
        slots:
          customerId: requestBody.customerId
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order payment by ID
      effect: read
      questions:
      - What does one order payment record look like, including its transactions?
      - Where do I read a single payment by its internal ID?
      instructions:
      - text: Get order payment {id}.
        slots:
          id: path.id
      - text: Show payment {id} with response group {respGroup}.
        slots:
          id: path.id
          respGroup: query.respGroup
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update an order payment
      effect: write
      questions:
      - Can I change one field of a payment without sending the full record?
      - What is the way to JSON-patch an order payment?
      instructions:
      - text: Patch payment {id} with only the changed fields.
        slots:
          id: path.id
      - text: Apply a partial update to order payment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/outer/{outerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment by external ID
      effect: read
      questions:
      - Can I find a payment using the gateway's or external system's ID?
      - Which lookup works when I only have a payment's outer ID?
      instructions:
      - text: Get the payment with external ID {outerId}.
        slots:
          outerId: path.outerId
      - text: Find the order payment whose outer ID is {outerId}.
        slots:
          outerId: path.outerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing order payment
      effect: write
      questions:
      - How do I change the status of an existing payment?
      - Can I switch the payment method on a payment that's already recorded?
      instructions:
      - text: Set existing payment {id} status to {paymentStatus}.
        slots:
          id: requestBody.id
          paymentStatus: requestBody.paymentStatus
      - text: Change the payment method of existing payment {id} to {paymentMethod}.
        slots:
          id: requestBody.id
          paymentMethod: requestBody.paymentMethod
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a payment to an order
      effect: write
      questions:
      - How do I record a new payment against an order?
      - Can I choose the payment gateway when adding a payment to an order?
      instructions:
      - text: Add a payment of {sum} to order {orderId}.
        slots:
          sum: requestBody.sum
          orderId: requestBody.orderId
      - text: Record a new payment on order {orderId} through gateway {gatewayCode}.
        slots:
          orderId: requestBody.orderId
          gatewayCode: requestBody.gatewayCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete order payments
      effect: destructive
      questions:
      - How do I remove payment records from orders?
      - Can several order payments be deleted in one call?
      instructions:
      - text: Delete order payments {ids}.
        slots:
          ids: query.ids
      - text: Remove the payment records {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/payment/capture'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture an authorized payment
      effect: write
      questions:
      - How do I capture funds that were only authorized on an order?
      - Can I capture a partial amount and close the transaction?
      instructions:
      - text: Capture payment {paymentId} on order {orderId}.
        slots:
          paymentId: requestBody.paymentId
          orderId: requestBody.orderId
      - text: Capture {amount} of payment {paymentId} and close the transaction.
        slots:
          amount: requestBody.amount
          paymentId: requestBody.paymentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/payments/payment/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund an order payment
      effect: destructive
      questions:
      - How do I refund money back to a customer for an order?
      - Can I refund only part of a payment and record a reason?
      instructions:
      - text: Refund payment {paymentId} on order {orderId}.
        slots:
          paymentId: requestBody.paymentId
          orderId: requestBody.orderId
      - text: Refund {amount} of payment {paymentId} with reason {reasonMessage}.
        slots:
          amount: requestBody.amount
          paymentId: requestBody.paymentId
          reasonMessage: requestBody.reasonMessage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Save an order shipment
      effect: write
      questions:
      - How do I add tracking information to an order's shipment?
      - Can I set the fulfillment center and shipping method for a shipment?
      instructions:
      - text: Save shipment for order {customerOrderId} with tracking number {trackingNumber}.
        slots:
          customerOrderId: requestBody.customerOrderId
          trackingNumber: requestBody.trackingNumber
      - text: Ship order {customerOrderId} from fulfillment center {fulfillmentCenterId} via {shipmentMethodCode}.
        slots:
          customerOrderId: requestBody.customerOrderId
          fulfillmentCenterId: requestBody.fulfillmentCenterId
          shipmentMethodCode: requestBody.shipmentMethodCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/shipments/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search order shipments
      effect: read
      questions:
      - Which shipments are still pending for my fulfillment center?
      - Can I list the shipments for one order number?
      instructions:
      - text: List shipments for order number {orderNumber}.
        slots:
          orderNumber: requestBody.orderNumber
      - text: Find shipments from fulfillment center {fulfillmentCenterId} with status {status}.
        slots:
          fulfillmentCenterId: requestBody.fulfillmentCenterId
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/order/shipments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a shipment
      effect: write
      questions:
      - Can I change one field of a shipment without sending the whole shipment?
      - What is the way to JSON-patch an order shipment?
      instructions:
      - text: Patch shipment {id} with only the changed fields.
        slots:
          id: path.id
      - text: Apply a partial update to order shipment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'