# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mirakl Orders API
  version: 1.0.0
extends: openapi/mirakl-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: 47
- target: $.paths['/v1/orders/documents/{channel_document_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a channel order document from Connect
      effect: destructive
      questions:
      - Can I remove a document I previously pushed to Mirakl Connect for a channel order?
      - What do I need to send to delete a channel order document from Connect?
      instructions:
      - text: Delete Connect channel document {channel_document_id} sent from origin {origin}.
        slots:
          channel_document_id: path.channel_document_id
          origin: requestBody.origin
      - text: Remove the channel-side order document {channel_document_id} from Mirakl Connect.
        slots:
          channel_document_id: path.channel_document_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orders/actions/{action_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Report the final outcome of an async order action
      effect: write
      questions:
      - How do I tell Mirakl Connect that an asynchronous command event action succeeded or failed?
      - Can I attach error details when reporting a failed asynchronous action back to Connect?
      instructions:
      - text: Mark asynchronous action {action_id} as {status}.
        slots:
          action_id: path.action_id
          status: requestBody.status
      - text: Report action {action_id} as FAILURE with errors {errors}.
        slots:
          action_id: path.action_id
          errors: requestBody.errors
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orders/anonymize-after'].put
  update:
    x-apievangelist-phrasing:
      intent: Set when Connect should anonymize orders
      effect: destructive
      questions:
      - How do I tell Mirakl Connect after which date my orders should be anonymized?
      - Is order anonymization in Connect reversible once the date passes?
      instructions:
      - text: 'Set the anonymize-after date for these orders: {orders}.'
        slots:
          orders: requestBody.orders
      - text: Schedule customer data anonymization in Connect for orders {orders}.
        slots:
          orders: requestBody.orders
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orders/{channel_order_id}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a document to a channel order in Connect
      effect: write
      questions:
      - How do I attach a document to a channel order using its channel order ID in Mirakl Connect?
      - Can I upload a document for a return linked to a channel order?
      instructions:
      - text: Upload {file} with metadata {metadata} to channel order {channel_order_id} from origin {origin}.
        slots:
          file: requestBody.file
          metadata: requestBody.metadata
          channel_order_id: path.channel_order_id
          origin: requestBody.origin
      - text: Attach a document to channel order {channel_order_id} in Connect.
        slots:
          channel_order_id: path.channel_order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Push channel orders into Mirakl Connect
      effect: write
      questions:
      - How do I synchronize orders from my sales channel into Mirakl Connect?
      - What happens if one order in an order upsert batch is invalid?
      - Do I have to resend every field when updating a channel order in Connect?
      instructions:
      - text: 'Upsert these channel orders into Connect from origin {origin}: {orders}.'
        slots:
          origin: requestBody.origin
          orders: requestBody.orders
      - text: Sync the latest full versions of orders {orders} to Mirakl Connect.
        slots:
          orders: requestBody.orders
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orders/{order_id}/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or refuse Connect order lines (original)
      effect: write
      questions:
      - Which endpoint do I use to accept or refuse Connect order lines synchronously, the original non-v2 one?
      - Can I refuse some lines of a Connect order that is awaiting acceptance using the first-version accept call?
      instructions:
      - text: Using the original accept endpoint, accept or refuse lines {order_lines} on Connect order {order_id}.
        slots:
          order_lines: requestBody.order_lines
          order_id: path.order_id
      - text: Synchronously accept all awaiting lines of Connect order {order_id} with the v1 call.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List Mirakl Connect orders (original version)
      effect: read
      questions:
      - How do I pull Connect orders updated since my last sync using the original orders list?
      - Can I filter the first-version Connect order list by fulfillment type?
      instructions:
      - text: With the original Connect orders list, fetch orders updated since {updated_from}.
        slots:
          updated_from: query.updated_from
      - text: List v1 Connect orders with statuses {statuses}.
        slots:
          statuses: query.statuses
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or refuse Connect order lines (v2)
      effect: write
      questions:
      - How do I accept or refuse Connect order lines with the v2 asynchronous accept endpoint?
      - Does the v2 accept call also sync the line status back to the sales channel?
      instructions:
      - text: Using v2, accept or refuse order lines {order_lines} on Connect order {order_id}.
        slots:
          order_lines: requestBody.order_lines
          order_id: path.order_id
      - text: Send a v2 acceptance decision for every awaiting line of Connect order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel lines of a Connect order
      effect: destructive
      questions:
      - Can I cancel only part of a Mirakl Connect order rather than all of it?
      - What is the v2 call for cancelling Connect order lines?
      instructions:
      - text: Cancel lines {cancelations} of Connect order {order_id}.
        slots:
          cancelations: requestBody.cancelations
          order_id: path.order_id
      - text: Cancel every line on Connect order {order_id} via v2.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: Download documents from one Connect order
      effect: read
      questions:
      - How do I download the documents attached to a single Connect order?
      - Can I download only certain document types, like return labels, from one Connect order?
      instructions:
      - text: Download the documents of Connect order {order_id}.
        slots:
          order_id: path.order_id
      - text: Download documents of type {types} from Connect order {order_id}.
        slots:
          types: query.types
          order_id: path.order_id
      - text: Fetch documents {document_ids} from Connect order {order_id}.
        slots:
          document_ids: query.document_ids
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a return label or invoice to a Connect order
      effect: write
      questions:
      - How do I upload a customer invoice to a Connect order by its Mirakl order ID?
      - Which document types does the v2 Connect order document upload accept?
      instructions:
      - text: Upload {file} as a v2 document with metadata {metadata} to Connect order {order_id}.
        slots:
          file: requestBody.file
          metadata: requestBody.metadata
          order_id: path.order_id
      - text: Attach a return label to Connect order {order_id} using v2.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/actions/{action_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an async Connect order action
      effect: read
      questions:
      - How can I tell whether my asynchronous accept request on a Connect order finished?
      - Where do I see errors raised while Connect processed an order action request?
      instructions:
      - text: Check the status of Connect action request {action_id}.
        slots:
          action_id: path.action_id
      - text: Show any processing errors for action {action_id}.
        slots:
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/tracking/{tracking_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Connect action result by tracking ID (deprecated)
      effect: read
      questions:
      - Is the Connect order tracking-ID lookup still supported or deprecated?
      - Can I still look up an old order request result using its tracking ID?
      instructions:
      - text: Look up deprecated tracking result {tracking_id} for a Connect order request.
        slots:
          tracking_id: path.tracking_id
      - text: Use the legacy tracking endpoint to fetch request {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents across Connect orders
      effect: read
      questions:
      - How do I list documents across all my Connect orders, newest first?
      - Can I list only Connect order documents updated after a certain date?
      - What metadata comes back for each order document, like size and type?
      instructions:
      - text: List Connect order documents updated since {updated_from}.
        slots:
          updated_from: query.updated_from
      - text: List documents of type {types} for Connect orders {order_ids}.
        slots:
          types: query.types
          order_ids: query.order_ids
      - text: Show order documents from channel types {channel_types}.
        slots:
          channel_types: query.channel_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List Mirakl Connect orders (v2)
      effect: read
      questions:
      - What is the v2 way to list Mirakl Connect orders for syncing into my system?
      - Can I page through v2 Connect orders by status and last update time?
      instructions:
      - text: With the v2 orders list, fetch Connect orders updated since {updated_from}.
        slots:
          updated_from: query.updated_from
      - text: List v2 Connect orders {order_ids}.
        slots:
          order_ids: query.order_ids
      - text: List v2 Connect orders with fulfillment type {fulfillment_type}.
        slots:
          fulfillment_type: query.fulfillment_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund lines of a Connect order
      effect: write
      questions:
      - How do I refund some or all lines of a Mirakl Connect order?
      - Is there a v2 Connect call for issuing order line refunds?
      instructions:
      - text: Refund lines {refunds} on Connect order {order_id}.
        slots:
          refunds: requestBody.refunds
          order_id: path.order_id
      - text: Issue a v2 refund for every line of Connect order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Log order action results and errors to Connect
      effect: write
      questions:
      - How does my connector report back-order sync results and errors to Mirakl Connect?
      - Can I get a centralized view in Connect of errors from actions my system ran on orders?
      instructions:
      - text: 'Log these order action results in Connect: {actions}.'
        slots:
          actions: requestBody.actions
      - text: Report the failed order sync actions {actions} to Connect.
        slots:
          actions: requestBody.actions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List marketplace orders with filters
      effect: read
      questions:
      - How do I list marketplace orders by state and creation date through OR11?
      - Can I filter marketplace orders to those with an open incident or awaiting tax confirmation?
      - What happens if I pass too many customer or offer IDs when listing orders?
      instructions:
      - text: List marketplace orders in states {order_state_codes}.
        slots:
          order_state_codes: query.order_state_codes
      - text: List orders for shop {shop_ids} created between {start_date} and {end_date}.
        slots:
          shop_ids: query.shop_ids
          start_date: query.start_date
          end_date: query.end_date
      - text: Find marketplace orders {order_ids}.
        slots:
          order_ids: query.order_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders'].put
  update:
    x-apievangelist-phrasing:
      intent: Update order fields in bulk
      effect: write
      questions:
      - Can I update just a few fields on marketplace orders without resending everything?
      - How many orders can I patch in one OR04 call?
      instructions:
      - text: 'Patch these marketplace orders field by field: {orders}.'
        slots:
          orders: requestBody.orders
      - text: Clear a field on orders {orders} by sending it as null.
        slots:
          orders: requestBody.orders
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/shipping_from'].put
  update:
    x-apievangelist-phrasing:
      intent: Update the ship-from origin of order lines
      effect: write
      questions:
      - How do I change where marketplace order lines ship from?
      - How many order lines can I update shipping origin for at once?
      instructions:
      - text: Set the shipping origin on order lines {order_lines}.
        slots:
          order_lines: requestBody.order_lines
      - text: 'Update shipping_from details for these lines: {order_lines}.'
        slots:
          order_lines: requestBody.order_lines
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one marketplace order (deprecated)
      effect: read
      questions:
      - Is the single marketplace order lookup by ID deprecated?
      - Can I still fetch one order's details directly by its order ID with OR12?
      instructions:
      - text: Get marketplace order {order_id} using the deprecated single-order call.
        slots:
          order_id: path.order_id
      - text: Show the details of order {order_id} via OR12.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/async-export'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an asynchronous bulk order export
      effect: read
      questions:
      - How do I export a very large number of marketplace orders without paginating?
      - Can I split an asynchronous order export into chunked files?
      - Which date filters are required to start an order export?
      instructions:
      - text: Start an async export of orders created between {start_date} and {end_date}.
        slots:
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Export orders updated since {start_update_date} in chunks of {items_per_chunk} items.
        slots:
          start_update_date: requestBody.start_update_date
          items_per_chunk: requestBody.items_per_chunk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/async-export/status/{tracking_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an order export
      effect: read
      questions:
      - How do I know when my asynchronous order export has completed?
      - Where do I get the file URLs for a finished order export?
      instructions:
      - text: Check the status of order export {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      - text: Get the download URLs for completed export {tracking_id}.
        slots:
          tracking_id: path.tracking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dynamic-url/The+URL+is+retrieved+from+OR14+output/OR15'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an order export file chunk
      effect: read
      questions:
      - How do I retrieve the actual order export files once the export is done?
      - Can I download each chunk of a completed order export separately?
      instructions:
      - text: Download the order export chunk from the URL the export status returned.
      - text: Fetch each file of my completed order export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or refuse marketplace order lines as seller
      effect: write
      questions:
      - As a seller, how do I accept or refuse order lines that are waiting for acceptance in OR21?
      - What error do I get if the marketplace order is not in the right state to accept?
      instructions:
      - text: As the shop, accept or refuse lines {order_lines} on marketplace order {order_id}.
        slots:
          order_lines: requestBody.order_lines
          order_id: path.order_id
      - text: Accept all waiting lines of seller order {order_id} with OR21.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/tracking'].put
  update:
    x-apievangelist-phrasing:
      intent: Set carrier tracking for an order
      effect: write
      questions:
      - How do I add a tracking number and carrier to a marketplace order?
      - Can I give a full tracking URL when the carrier isn't registered on the platform?
      instructions:
      - text: Set tracking number {tracking_number} with carrier {carrier_code} on order {order_id}.
        slots:
          tracking_number: requestBody.tracking_number
          carrier_code: requestBody.carrier_code
          order_id: path.order_id
      - text: Add tracking URL {carrier_url} for carrier {carrier_name} to order {order_id}.
        slots:
          carrier_url: requestBody.carrier_url
          carrier_name: requestBody.carrier_name
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/ship'].put
  update:
    x-apievangelist-phrasing:
      intent: Confirm an order has shipped
      effect: write
      questions:
      - How do I mark a marketplace order in SHIPPING status as shipped?
      - Does validating an order shipment need a request body?
      instructions:
      - text: Validate the shipment of order {order_id}.
        slots:
          order_id: path.order_id
      - text: Mark marketplace order {order_id} as shipped.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel an entire marketplace order
      effect: destructive
      questions:
      - How do I cancel a whole marketplace order at once?
      - Is there a single call to fully cancel an order rather than line by line?
      instructions:
      - text: Fully cancel marketplace order {order_id}.
        slots:
          order_id: path.order_id
      - text: Cancel every line of order {order_id} in one go with OR29.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel specific marketplace order lines
      effect: destructive
      questions:
      - Can a shop cancel individual lines across marketplace orders?
      - When is a seller allowed to cancel an order line under pay-on-delivery workflows?
      instructions:
      - text: 'Cancel these marketplace order lines: {cancelations}.'
        slots:
          cancelations: requestBody.cancelations
      - text: Cancel lines {cancelations} using tax mode {order_tax_mode}.
        slots:
          cancelations: requestBody.cancelations
          order_tax_mode: requestBody.order_tax_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/additional_fields'].put
  update:
    x-apievangelist-phrasing:
      intent: Update custom fields on an order
      effect: write
      questions:
      - How do I set custom field values on a marketplace order and its lines?
      - Can I clear a custom field on an order, and what about required ones?
      instructions:
      - text: Update custom fields {order_additional_fields} on order {order_id}.
        slots:
          order_additional_fields: requestBody.order_additional_fields
          order_id: path.order_id
      - text: Set order line custom fields {order_lines} on order {order_id}.
        slots:
          order_lines: requestBody.order_lines
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages on an order (deprecated)
      effect: read
      questions:
      - How do I see the messages exchanged on a marketplace order?
      - Can I list only the messages I received on an order?
      instructions:
      - text: List messages on order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show only received messages ({received}) for order {order_id}.
        slots:
          received: query.received
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/evaluation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the customer evaluation of an order
      effect: read
      questions:
      - How do I see the rating a customer left on a product marketplace order?
      - Where can I read the evaluation for an order I shipped?
      instructions:
      - text: Get the evaluation for marketplace order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show the customer rating on product order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents attached to marketplace orders
      effect: read
      questions:
      - Which documents are attached to a given marketplace order?
      - Can I list the documents for several seller orders in one call?
      instructions:
      - text: List the documents on marketplace orders {order_ids}.
        slots:
          order_ids: query.order_ids
      - text: Show what documents seller order {order_ids} has.
        slots:
          order_ids: query.order_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/documents/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download marketplace order documents
      effect: read
      questions:
      - How do I download all documents from several marketplace orders as a ZIP?
      - Can I download a single order document without it being zipped?
      instructions:
      - text: Download documents {document_ids} from marketplace orders.
        slots:
          document_ids: query.document_ids
      - text: Download all documents from seller orders {order_ids}.
        slots:
          order_ids: query.order_ids
      - text: Download documents with codes {document_codes}.
        slots:
          document_codes: query.document_codes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload documents to a marketplace order
      effect: write
      questions:
      - Which file types can I attach to a marketplace order, and how many?
      - Can I upload several documents to one seller order in one request?
      instructions:
      - text: Upload files {files} described by {order_documents} to marketplace order {order_id}.
        slots:
          files: requestBody.files
          order_documents: requestBody.order_documents
          order_id: path.order_id
      - text: Attach a PDF invoice to seller order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/taxes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the order taxes on the platform
      effect: read
      questions:
      - What order taxes are configured on the marketplace?
      - Where can I get the list of tax codes I can use on orders?
      instructions:
      - text: List all order taxes available on the platform.
      - text: Show me the order tax codes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/documents/{document_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a marketplace order document
      effect: destructive
      questions:
      - How do I remove a document I attached to a marketplace order?
      - Can I delete a single seller order document by its ID?
      instructions:
      - text: Delete marketplace order document {document_id}.
        slots:
          document_id: path.document_id
      - text: Remove attached order document {document_id}.
        slots:
          document_id: path.document_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/refund'].put
  update:
    x-apievangelist-phrasing:
      intent: Refund lines of one order (deprecated)
      effect: write
      questions:
      - Is the per-order refund endpoint for marketplace orders deprecated?
      - Can I still refund lines of a single order with the older OR26 call?
      instructions:
      - text: Using the deprecated per-order refund, refund lines {order_lines} of order {order_id}.
        slots:
          order_lines: requestBody.order_lines
          order_id: path.order_id
      - text: Refund order {order_id} lines for shop {shop_id} via OR26.
        slots:
          order_id: path.order_id
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/refund'].put
  update:
    x-apievangelist-phrasing:
      intent: Refund marketplace order lines
      effect: write
      questions:
      - How do I refund order lines across marketplace orders as a seller?
      - Can I choose the tax mode when refunding order lines?
      instructions:
      - text: 'Refund these marketplace order lines: {refunds}.'
        slots:
          refunds: requestBody.refunds
      - text: Issue refunds {refunds} for shop {shop_id} with tax mode {order_tax_mode}.
        slots:
          refunds: requestBody.refunds
          shop_id: query.shop_id
          order_tax_mode: requestBody.order_tax_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/adjust'].put
  update:
    x-apievangelist-phrasing:
      intent: Adjust the measured quantity of an order line
      effect: write
      questions:
      - Can I adjust an order line's actual weight or measurement after picking?
      - What happens if the adjusted measurement equals what was ordered?
      instructions:
      - text: Adjust the actual measurement on order lines {order_lines}.
        slots:
          order_lines: requestBody.order_lines
      - text: Adjust order lines {order_lines} for shop {shop_id}.
        slots:
          order_lines: requestBody.order_lines
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a service order
      effect: write
      questions:
      - How do I change the price or booking on a service order?
      - Can I update a service order that is already closed or cancelled?
      instructions:
      - text: Update the price of service order {order_id} to {price}.
        slots:
          order_id: path.order_id
          price: requestBody.price
      - text: Change the booking on service order {order_id} to {booking}.
        slots:
          order_id: path.order_id
          booking: requestBody.booking
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List service orders
      effect: read
      questions:
      - How do I list service orders by state or service code?
      - Can I find refunded service orders or ones with an open incident?
      instructions:
      - text: List service orders in state {state}.
        slots:
          state: query.state
      - text: List service orders for service {service_code} created after {date_created_start}.
        slots:
          service_code: query.service_code
          date_created_start: query.date_created_start
      - text: Find service orders for customer {customer_id}.
        slots:
          customer_id: query.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept a service order
      effect: write
      questions:
      - How do I accept a service order that is waiting for acceptance?
      - Can a shop accept a whole service order in one call?
      instructions:
      - text: Accept service order {order_id}.
        slots:
          order_id: path.order_id
      - text: Accept service order {order_id} for shop {shop_id}.
        slots:
          order_id: path.order_id
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/refuse'].put
  update:
    x-apievangelist-phrasing:
      intent: Refuse a service order
      effect: destructive
      questions:
      - How do I decline a service order waiting for my acceptance?
      - Can a shop refuse a service order it cannot fulfil?
      instructions:
      - text: Refuse service order {order_id}.
        slots:
          order_id: path.order_id
      - text: Decline service order {order_id} for shop {shop_id}.
        slots:
          order_id: path.order_id
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/consume'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a service order as consumed
      effect: write
      questions:
      - How do I record that a customer used their service order?
      - Can I pass a voucher code when consuming a pending service order?
      instructions:
      - text: Consume service order {order_id} with voucher {voucher_code}.
        slots:
          order_id: path.order_id
          voucher_code: requestBody.voucher_code
      - text: Mark service order {order_id} consumed on {date_consumed}.
        slots:
          order_id: path.order_id
          date_consumed: requestBody.date_consumed
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/refund'].put
  update:
    x-apievangelist-phrasing:
      intent: Request a refund on a service order
      effect: write
      questions:
      - How do I refund an amount on a service order?
      - Does a service order refund need a reason code and currency?
      instructions:
      - text: Refund {amount} {currency_code} on service order {order_id} for reason {reason_code}.
        slots:
          amount: requestBody.amount
          currency_code: requestBody.currency_code
          order_id: path.order_id
          reason_code: requestBody.reason_code
      - text: Request a refund on service order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/evaluation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the evaluation of a service order
      effect: read
      questions:
      - Where can I see the customer's evaluation of a service order?
      - Did the customer rate the service they booked?
      instructions:
      - text: Get the evaluation of service order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show the rating on service order {order_id} for shop {shop_id}.
        slots:
          order_id: path.order_id
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'