# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mirakl Returns API
  version: 1.0.0
extends: openapi/mirakl-returns-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: 17
- target: $.paths['/v1/orders/returns'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync returns into Mirakl Connect
      effect: write
      questions:
      - How do I push returns from my sales channel into Mirakl Connect?
      - Does sending a return that already exists update it or create a duplicate?
      instructions:
      - text: Upsert returns {returns} from origin {origin}.
        slots:
          returns: requestBody.returns
          origin: requestBody.origin
      - text: Synchronize these channel returns {returns} with Connect.
        slots:
          returns: requestBody.returns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/returns/{return_id}/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or refuse a Connect return
      effect: write
      questions:
      - Can I approve a return request that's still waiting in REQUEST_INITIATED from Connect?
      - What do I send to reject a customer's return with a reason in Mirakl Connect?
      instructions:
      - text: Set accepted to {accepted} for Connect return {return_id}.
        slots:
          accepted: requestBody.accepted
          return_id: path.return_id
      - text: Refuse Connect return {return_id} because {rejection_reason}.
        slots:
          return_id: path.return_id
          rejection_reason: requestBody.rejection_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/returns/{return_id}/receive'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a Connect return as received
      effect: write
      questions:
      - How do I confirm I physically got the item back for a Connect return?
      - Does marking a Connect return received also update the sales channel?
      instructions:
      - text: Mark Connect return {return_id} as received.
        slots:
          return_id: path.return_id
      - text: Confirm the returned item for Connect return {return_id} arrived at the warehouse.
        slots:
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/returns/{return_id}/close'].put
  update:
    x-apievangelist-phrasing:
      intent: Close a Connect return
      effect: destructive
      questions:
      - When the refund and checks are done, how do I close a return in Connect?
      - Can I finalize a single Connect return once all steps are complete?
      instructions:
      - text: Close Connect return {return_id}.
        slots:
          return_id: path.return_id
      - text: Mark Connect return {return_id} as closed now that the refund is done.
        slots:
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/returns'].get
  update:
    x-apievangelist-phrasing:
      intent: List Mirakl Connect returns
      effect: read
      questions:
      - Which Connect returns changed since my last sync?
      - Can I list Connect returns for specific orders or statuses?
      instructions:
      - text: List Connect returns updated since {updated_from}.
        slots:
          updated_from: query.updated_from
      - text: Show Connect returns for orders {order_ids} updated since {updated_from}.
        slots:
          order_ids: query.order_ids
          updated_from: query.updated_from
      - text: List Connect returns in status {statuses} updated from {updated_from}.
        slots:
          statuses: query.statuses
          updated_from: query.updated_from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/returns/{return_id}/trackings'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Connect return's tracking
      effect: write
      questions:
      - How do I add a return shipping tracking number to a Connect return?
      - Can I attach a return label URL or RMA to a Connect return?
      instructions:
      - text: Set tracking {tracking} on Connect return {return_id}.
        slots:
          tracking: requestBody.tracking
          return_id: path.return_id
      - text: Add label {label_url} and RMA {rma_id} to Connect return {return_id}.
        slots:
          label_url: requestBody.label_url
          rma_id: requestBody.rma_id
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns'].get
  update:
    x-apievangelist-phrasing:
      intent: List marketplace returns
      effect: read
      questions:
      - Which returns are open on the marketplace right now?
      - Can I find returns by order, RMA number or customer?
      instructions:
      - text: List marketplace returns in state {return_state}.
        slots:
          return_state: query.return_state
      - text: Find the returns for order {order_commercial_id}.
        slots:
          order_commercial_id: query.order_commercial_id
      - text: Look up the return with RMA {return_rma}.
        slots:
          return_rma: query.return_rma
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns'].put
  update:
    x-apievangelist-phrasing:
      intent: Patch-update marketplace returns
      effect: write
      questions:
      - How do I change details on returns that already exist on the marketplace?
      - Can I edit several returns in one partial update?
      instructions:
      - text: Patch these returns {returns}.
        slots:
          returns: requestBody.returns
      - text: Update returns {returns} for shop {shop_id}.
        slots:
          returns: requestBody.returns
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns'].post
  update:
    x-apievangelist-phrasing:
      intent: Create marketplace returns
      effect: write
      questions:
      - How do I open new returns for order lines on the marketplace?
      - What's the maximum number of returns I can create in one request?
      instructions:
      - text: Create these returns {returns}.
        slots:
          returns: requestBody.returns
      - text: Open a batch of new return requests {returns}.
        slots:
          returns: requestBody.returns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/items_to_return'].get
  update:
    x-apievangelist-phrasing:
      intent: List items eligible for return
      effect: read
      questions:
      - Which items on an order can still be returned?
      - Is a specific order line eligible to be returned?
      instructions:
      - text: List the returnable items of order {order_commercial_id}.
        slots:
          order_commercial_id: query.order_commercial_id
      - text: Check whether order line {order_line_id} can be returned.
        slots:
          order_line_id: query.order_line_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/receive'].put
  update:
    x-apievangelist-phrasing:
      intent: Validate returns as received
      effect: write
      questions:
      - How do I confirm reception for many marketplace returns at once?
      - How many returns can I mark as received in one call?
      instructions:
      - text: Mark returns {returns} as received.
        slots:
          returns: requestBody.returns
      - text: Validate reception of this batch of returns {returns}.
        slots:
          returns: requestBody.returns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/cancel'].put
  update:
    x-apievangelist-phrasing:
      intent: Cancel marketplace returns
      effect: destructive
      questions:
      - How do I cancel a return that should no longer go ahead?
      - Can I cancel up to 100 returns in one request?
      instructions:
      - text: Cancel returns {returns}.
        slots:
          returns: requestBody.returns
      - text: Mark this batch of returns {returns} as canceled.
        slots:
          returns: requestBody.returns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/return-labels'].get
  update:
    x-apievangelist-phrasing:
      intent: List return label requests
      effect: read
      questions:
      - What's the state of the return labels I requested?
      - Can I find return labels created within a date range?
      instructions:
      - text: List return labels for return {return_id}.
        slots:
          return_id: query.return_id
      - text: Show return labels in state {label_state}.
        slots:
          label_state: query.label_state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/return-labels'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate return labels
      effect: write
      questions:
      - How do I generate prepaid return labels for returns?
      - Can I request return labels for several returns at once?
      instructions:
      - text: Create return labels {return_labels}.
        slots:
          return_labels: requestBody.return_labels
      - text: Generate shipping labels for these returns {return_labels}.
        slots:
          return_labels: requestBody.return_labels
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/accept'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or refuse marketplace return requests
      effect: write
      questions:
      - As a seller, how do I approve or decline several return requests in bulk?
      - Is there a limit on how many return requests I can accept in one call?
      instructions:
      - text: Accept or refuse return requests {returns}.
        slots:
          returns: requestBody.returns
      - text: Decide on return requests {returns} for shop {shop_id}.
        slots:
          returns: requestBody.returns
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/compliance'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark returns compliant or non-compliant
      effect: write
      questions:
      - How do I record that a returned item failed inspection?
      - Can I flag returned items as compliant after checking them?
      instructions:
      - text: Set compliance on returns {returns}.
        slots:
          returns: requestBody.returns
      - text: Mark returns {returns} as compliant or non compliant for shop {shop_id}.
        slots:
          returns: requestBody.returns
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/returns/close'].put
  update:
    x-apievangelist-phrasing:
      intent: Close marketplace returns in bulk
      effect: destructive
      questions:
      - How do I close a batch of finished returns on the marketplace?
      - Can I close up to 100 returns at once as a seller?
      instructions:
      - text: Close returns {returns}.
        slots:
          returns: requestBody.returns
      - text: Mark returns {returns} as closed for shop {shop_id}.
        slots:
          returns: requestBody.returns
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'