API Evangelist conversational phrasing for Shopify Operator Connector Storefront API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Shopify Operator Connector Storefront API
  version: 1.0.0
extends: openapi/mirakl-storefront-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: 13
- target: $.paths['/api/storefront/return'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a return from the storefront
      effect: write
      questions:
      - How can a shopper start a return for an order from my storefront?
      - Can a customer attach photos when requesting a return on the storefront?
      instructions:
      - text: Create a storefront return with request {returnRequest}.
        slots:
          returnRequest: requestBody.returnRequest
      - text: Submit return request {returnRequest} with files {files}.
        slots:
          returnRequest: requestBody.returnRequest
          files: requestBody.files
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/evaluations/assessments'].get
  update:
    x-apievangelist-phrasing:
      intent: Get seller evaluation criteria
      effect: read
      questions:
      - What criteria do customers rate sellers on in the storefront?
      - Can I get the evaluation assessments translated for a locale?
      instructions:
      - text: Get the evaluation assessments.
      - text: Show evaluation assessments in locale {locale}.
        slots:
          locale: query.locale
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/returns/items-to-return'].get
  update:
    x-apievangelist-phrasing:
      intent: Get returnable items for orders
      effect: read
      questions:
      - Which items can a shopper still return from their orders?
      - Can I check return eligibility for several orders at once on the storefront?
      instructions:
      - text: Get items to return for orders {orderCommercialIds}.
        slots:
          orderCommercialIds: query.orderCommercialIds
      - text: Show what the customer can return from order {orderCommercialIds}.
        slots:
          orderCommercialIds: query.orderCommercialIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/promotions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get promotions for offers
      effect: read
      questions:
      - Which promotions apply when a shopper buys a given offer?
      - Can the storefront show Mirakl promotions triggered by specific offers?
      instructions:
      - text: Get promotions triggered by offers {triggerOfferIds}.
        slots:
          triggerOfferIds: query.triggerOfferIds
      - text: List current storefront promotions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/returns'].get
  update:
    x-apievangelist-phrasing:
      intent: List a shopper's returns
      effect: read
      questions:
      - Where can a customer see the status of returns they've started?
      - Can I list storefront returns for particular orders?
      instructions:
      - text: List storefront returns for orders {orderCommercialIds}.
        slots:
          orderCommercialIds: query.orderCommercialIds
      - text: Show the customer's existing returns.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/shipment'].get
  update:
    x-apievangelist-phrasing:
      intent: Get shipment by Shopify fulfillment
      effect: read
      questions:
      - How do I get Mirakl shipment details from a Shopify fulfillment ID?
      - Where's the tracking for a marketplace shipment tied to a Shopify fulfillment?
      instructions:
      - text: Get the shipment for fulfillment {fulfillmentId}.
        slots:
          fulfillmentId: query.fulfillmentId
      - text: Show shipment details behind Shopify fulfillment {fulfillmentId}.
        slots:
          fulfillmentId: query.fulfillmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/orders/accounting-documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounting documents for orders
      effect: read
      questions:
      - Where can a shopper download invoices for their marketplace orders?
      - Can I get secure download links for accounting documents on several orders?
      instructions:
      - text: List accounting documents for orders {orderIds}.
        slots:
          orderIds: query.orderIds
      - text: Get invoice download links for order {orderIds}.
        slots:
          orderIds: query.orderIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/orders/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List general documents for orders
      effect: read
      questions:
      - What non-accounting documents are attached to my marketplace orders?
      - Can a customer download general order documents like delivery notes?
      instructions:
      - text: List general order documents for orders {orderIds}.
        slots:
          orderIds: query.orderIds
      - text: Get download links for the non-invoice documents of order {orderIds}.
        slots:
          orderIds: query.orderIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/products/offers'].get
  update:
    x-apievangelist-phrasing:
      intent: List offers for product pages
      effect: read
      questions:
      - How do I show all seller offers on a product detail page?
      - Can the product page offers be filtered by shipping zone?
      instructions:
      - text: List offers for products {productIds}.
        slots:
          productIds: query.productIds
      - text: Show PDP offers for {productIds} in locale {locale}.
        slots:
          productIds: query.productIds
          locale: query.locale
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/shop-ratings/{shopId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a shop's customer ratings
      effect: read
      questions:
      - What ratings and reviews have customers left for a seller?
      - Can I show a shop's evaluations on the storefront?
      instructions:
      - text: List evaluations for shop {shopId}.
        slots:
          shopId: path.shopId
      - text: Show customer ratings of seller {shopId}.
        slots:
          shopId: path.shopId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/graphql'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a GraphQL request to Mirakl
      effect: write
      questions:
      - Can my storefront query Mirakl through a GraphQL proxy?
      - Why can't I query additional fields through the storefront GraphQL endpoint?
      instructions:
      - text: Forward this GraphQL request to Mirakl.
      - text: Run the GraphQL request for a customer in country {X-Customer-Country}.
        slots:
          X-Customer-Country: header.X-Customer-Country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/graphql/upload'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload a file via Mirakl GraphQL
      effect: write
      questions:
      - How do I upload a file through the storefront GraphQL proxy?
      - Is there a separate endpoint for GraphQL file uploads?
      instructions:
      - text: Forward this file upload to the Mirakl GraphQL upload API.
      - text: Upload the attached file through GraphQL.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/storefront/fulfillments/receive'].put
  update:
    x-apievangelist-phrasing:
      intent: Confirm a fulfillment was received
      effect: write
      questions:
      - How does a shopper confirm they received a marketplace delivery?
      - Can I mark a Shopify fulfillment as received on the Mirakl side?
      instructions:
      - text: Confirm reception of fulfillment {fulfillmentId}.
        slots:
          fulfillmentId: query.fulfillmentId
      - text: Mark fulfillment {fulfillmentId} as received by the customer.
        slots:
          fulfillmentId: query.fulfillmentId
      method: generated
      generated: '2026-09-26'