Mirakl Storefront API

openapi: 3.2.0
info:
  description: '{% partial file="/partial-content/connector/operator/shopify/app-operator-shopify/rest/public/openapi-description.md" /%}'
  title: Shopify Operator Connector Storefront API
  version: ''
servers:
- description: Shopify production endpoint.
  url: https://operator-shpy.mirakl.net
tags:
- name: Storefront
paths:
  /api/storefront/return:
    post:
      description: '<div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- When you want to create a return for an order</div>

        </div>'
      operationId: CreateReturn
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            examples:
              multipart/form-data-auto:
                summary: Complete example with value types (multipart/form-data)
                value:
                  files:
                  - string
                  returnRequest:
                    description: string
                    methodCode: RETURN_METHOD_BY_MAIL
                    orderLogisticId: string
                    reasonCode: RETURN_BROKEN_ITEM
                    returnLines:
                    - orderLineId: string
                      quantity: 0
            schema:
              type: object
              properties:
                files:
                  type: array
                  description: List of attachments for the return
                  items:
                    type: string
                    format: binary
                returnRequest:
                  $ref: '#/components/schemas/CreateReturn_Request_MultipartFormData_Returnrequest'
                  description: The return data
              required:
              - returnRequest
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    miraklReturnId: 550e8400-e29b-41d4-a716-446655440000
                    shopifyReturnId: gid://shopify/Return/5551234567890
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    miraklReturnId: string
                    shopifyReturnId: string
              schema:
                type: object
                $ref: '#/components/schemas/CreateReturn_Response_200'
          description: OK
      summary: CreateReturn - Create a return for an order
      tags:
      - Storefront
      x-codeSamples:
      - lang: cURL
        source: "curl -i -X POST \\\n  https://operator-shpy.mirakl.net/api/storefront/return \\\n  -H 'Content-Type: multipart/form-data' \\\n  -F 'files=@path/to/file' \\\n  -F 'returnRequest=\"{\\\"description\\\":\\\"string\\\",\\\"methodCode\\\":\\\"RETURN_METHOD_BY_MAIL\\\",\\\"orderLogisticId\\\":\\\"string\\\",\\\"reasonCode\\\":\\\"RETURN_BROKEN_ITEM\\\",\\\"returnLines\\\":[{\\\"orderLineId\\\":\\\"string\\\",\\\"quantity\\\":0}]}\";type=application/json'\n"
  /api/storefront/evaluations/assessments:
    get:
      description: '<div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- When you want to retrieve the evaluations assessments</div>

        </div>'
      operationId: GetEvaluationsAssessments
      parameters:
      - description: Locale tag used to translate assessment labels (e.g. en_US, fr_FR). Optional — defaults to the operator's primary locale when omitted.
        explode: true
        in: query
        name: locale
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                  - code: string
                    label: string
                    type: string
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetEvaluationsAssessments_Response_200'
          description: OK
      summary: GetEvaluationsAssessments - Get evaluations assessments
      tags:
      - Storefront
  /api/storefront/returns/items-to-return:
    get:
      description: '<div class="extension-title">Description</div>


        When you want to retrieve items to return for a list of orders


        <div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- At each customer return request</div>

        <div class="max-call-frequency">Maximum usage: <br/>- At each customer return request</div>

        </div>'
      operationId: GetItemsToReturn
      parameters:
      - description: Mirakl order commercial identifiers separated by comma (e.g. order1,order2,...)
        explode: true
        in: query
        name: orderCommercialIds
        required: true
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    itemsToReturn:
                    - availableReturnMethods: null
                      availableReturnReasons: null
                      orderCommercialId: test
                      orderLineId: test-A-1
                      returnWindow: null
                      returnableQuantity: 0
                    - availableReturnMethods:
                      - RETURN_METHOD_BY_MAIL
                      - RETURN_METHOD_DROP_OFF
                      availableReturnReasons:
                      - RETURN_CHANGED_MIND
                      - RETURN_COUNTERFEIT_ITEM
                      orderCommercialId: test
                      orderLineId: test-B-1
                      returnWindow: 14
                      returnableQuantity: 1
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    itemsToReturn:
                    - availableReturnMethods:
                      - string
                      availableReturnReasons:
                      - string
                      orderCommercialId: string
                      orderLineId: string
                      returnWindow: 0
                      returnableQuantity: 0
              schema:
                type: object
                $ref: '#/components/schemas/GetItemsToReturn_Response_200'
          description: OK
      summary: GetItemsToReturn - Get items to return for a list of orders
      tags:
      - Storefront
  /api/storefront/promotions:
    get:
      description: '<div class="extension-title">Description</div>


        Returns Mirakl promotions for the given trigger offer IDs.


        <div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- Each display of the PDP for products with 3P offers</div>

        </div>'
      operationId: GetPromotions
      parameters:
      - description: Promotion-triggering offer ids, separated by commas
        explode: true
        in: query
        name: triggerOfferIds
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    promotions:
                    - amountOff: null
                      campaign:
                        identifier: SUMMERSALE
                      endDate: '2023-08-30T22:00:00Z'
                      freeItemsQuantity: null
                      internalDescription: Summer sale event
                      maxQuantityToDiscount: null
                      medias:
                      - locale: en_US
                        url: https://xxxx-xxxx.mirakl.net/mmp/media/promotion-media/ac63d67a-62c5-4c9a-8483-b704494abc45
                      - locale: fr_FR
                        url: https://xxxx-xxxx.mirakl.net/mmp/media/promotion-media/ac63d67a-62c5-4c9a-8483-b704494abc45
                      percentageOff: 10
                      publicDescriptions:
                      - locale: en_US
                        value: Summer promotions
                      - locale: fr_FR
                        value: Promotions d'été
                      reducedUnitPrice: null
                      rewardOnPurchasedItems: false
                      shopId: '3'
                      startDate: '2023-04-03T16:18:59.922Z'
                      state: ACTIVE
                      triggerOfferIds: []
                      triggers:
                      - amountPurchased: null
                        quantityPurchased: 1
                        sameItemPurchased: false
                        type: every_quantity
                      type: PERCENTAGE_OFF
                      withPromoCode: true
                    - amountOff: null
                      campaign: null
                      endDate: null
                      freeItemsQuantity: 1
                      internalDescription: Buy 5, Get 1 Free
                      maxQuantityToDiscount: null
                      medias: []
                      percentageOff: null
                      publicDescriptions: []
                      reducedUnitPrice: null
                      rewardOnPurchasedItems: true
                      shopId: '137'
                      startDate: '2026-05-28T08:57:15.642Z'
                      state: PENDING
                      triggerOfferIds: []
                      triggers:
                      - amountPurchased: null
                        quantityPurchased: 5
                        sameItemPurchased: true
                        type: minimum_quantity
                      type: FREE_ITEMS
                      withPromoCode: false
                    - amountOff: null
                      campaign:
                        identifier: 50_OFF
                      endDate: '2030-10-31T23:00:00Z'
                      freeItemsQuantity: null
                      internalDescription: 50% Off
                      maxQuantityToDiscount: 1
                      medias: []
                      percentageOff: 50
                      publicDescriptions: []
                      reducedUnitPrice: null
                      rewardOnPurchasedItems: true
                      shopId: '151'
                      startDate: '2025-09-30T22:00:00Z'
                      state: ACTIVE
                      triggerOfferIds: []
                      triggers:
                      - amountPurchased: 100
                        quantityPurchased: null
                        sameItemPurchased: null
                        type: minimum_amount
                      type: PERCENTAGE_OFF
                      withPromoCode: false
                    totalCount: 3
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    promotions:
                    - amountOff: 0
                      campaign:
                        identifier: string
                      endDate: '2023-03-28T09:34:42Z'
                      freeItemsQuantity: 0
                      internalDescription: string
                      maxQuantityToDiscount: 0
                      medias:
                      - locale: string
                        url: string
                      percentageOff: 0
                      publicDescriptions:
                      - locale: string
                        value: string
                      reducedUnitPrice: 0
                      rewardOnPurchasedItems: true
                      shopId: string
                      startDate: '2023-03-28T09:34:42Z'
                      state: string
                      triggerOfferIds:
                      - string
                      triggers:
                      - amountPurchased: 0
                        quantityPurchased: 0
                        sameItemPurchased: true
                        type: string
                      type: string
                      withPromoCode: true
                    totalCount: 0
              schema:
                type: object
                $ref: '#/components/schemas/GetPromotions_Response_200'
          description: OK
      summary: GetPromotions - Get promotions
      tags:
      - Storefront
  /api/storefront/returns:
    get:
      description: '<div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- At each page display</div>

        </div>'
      operationId: GetReturns
      parameters:
      - description: Mirakl order commercial identifiers separated by comma (e.g. order1,order2,...)
        explode: true
        in: query
        name: orderCommercialIds
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    returns:
                    - dateCreated: '2023-02-27T16:14:52Z'
                      description: Description of return
                      documents:
                      - id: 1337
                        type: SYSTEM_RETURN_LABEL
                      id: f61b5db8-d8f5-4715-b05f-aa4432c0e9e2
                      labelUrl: null
                      lastUpdated: null
                      methodCode: RETURN_METHOD_BY_MAIL
                      orderCommercialId: ORDER-1
                      orderId: ORDER-1-A
                      reasonCode: RETURN_CHANGED_MIND
                      rejectionReasonCode: null
                      returnAddress:
                        city: New York
                        countryIsoCode: USA
                        state: Manhattan
                        street1: 30, Prince Street
                        street2: 1st floor
                        zipCode: NY 10012
                      returnLines:
                      - compliance: null
                        orderLineId: ORDER-1-A-1
                        quantity: 2
                      - compliance: null
                        orderLineId: ORDER-1-A-2
                        quantity: 3
                      rma: null
                      state: WAITING_ACCEPTANCE
                      tracking:
                        carrierCode: null
                        carrierName: null
                        carrierStandardCode: ups
                        trackingNumber: 35H8O95K
                        trackingUrl: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=35H8O95K
                    - dateCreated: '2023-02-27T16:32:52Z'
                      description: null
                      documents: []
                      id: 2dc4f7d7-da59-4588-bec7-ce62daab2f93
                      labelUrl: https://www.label-url.com
                      lastUpdated: null
                      methodCode: RETURN_METHOD_DROP_OFF_POINT
                      orderCommercialId: ORDER-2
                      orderId: ORDER-2-A
                      reasonCode: RETURN_COUNTERFEIT_ITEM
                      rejectionReasonCode: null
                      returnAddress:
                        city: New York
                        countryIsoCode: USA
                        state: Manhattan
                        street1: 30, Prince Street
                        street2: 1st floor
                        zipCode: NY 10012
                      returnLines:
                      - compliance: null
                        orderLineId: ORDER-2-A-1
                        quantity: 1
                      rma: null
                      state: REFUSED
                      tracking: null
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    returns:
                    - dateCreated: '2023-03-28T09:34:42Z'
                      description: string
                      documents:
                      - id: 0
                        type: string
                      id: string
                      labelUrl: string
                      lastUpdated: '2023-03-28T09:34:42Z'
                      methodCode: RETURN_METHOD_BY_MAIL
                      orderCommercialId: string
                      orderId: string
                      reasonCode: RETURN_BROKEN_ITEM
                      rejectionReasonCode: RETURN_REJECTION_NOT_ELIGIBLE
                      returnAddress:
                        city: string
                        countryIsoCode: string
                        state: string
                        street1: string
                        street2: string
                        zipCode: string
                      returnLines:
                      - compliance:
                        - compliant: true
                          nonCompliantAdditionalInfo: string
                          nonCompliantReasonCode: string
                        orderLineId: string
                        quantity: 0
                      rma: string
                      state: CANCELED
                      tracking:
                        carrierCode: string
                        carrierName: string
                        carrierStandardCode: string
                        trackingNumber: string
                        trackingUrl: string
              schema:
                type: object
                $ref: '#/components/schemas/GetReturns_Response_200'
          description: OK
      summary: GetReturns - List returns
      tags:
      - Storefront
  /api/storefront/shipment:
    get:
      description: '<div class="extension-title">Description</div>


        When you want to retrieve shipment details


        <div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- When you want to retrieve shipment details</div>

        </div>'
      operationId: GetShipment
      parameters:
      - description: Shopify fulfillment identifier
        explode: true
        in: query
        name: fulfillmentId
        required: true
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    canMarkAsReceived: true
                    logisticOrderId: order-456
                    miraklShipmentId: 00000000-0000-0000-0000-000000000123
                    shopifyFulfillmentId: gid://shopify/Fulfillment/7175245005126
                    status: SHIPPED
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    canMarkAsReceived: true
                    logisticOrderId: string
                    miraklShipmentId: string
                    shopifyFulfillmentId: string
                    status: string
              schema:
                type: object
                $ref: '#/components/schemas/GetShipment_Response_200'
          description: OK
      summary: GetShipment - Get shipment details by Shopify fulfillment ID
      tags:
      - Storefront
  /api/storefront/orders/accounting-documents:
    get:
      description: '<div class="extension-title">Description</div>


        Retrieves a list of accounting documents for specified Mirakl orders, with secure URLs for downloading each document.


        <div class="api-description-extension">

        </div>'
      operationId: ListAccountingOrdersDocuments
      parameters:
      - description: Mirakl orders identifier
        explode: true
        in: query
        name: orderIds
        required: true
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    documents:
                    - fileName: string
                      id: string
                      type: string
                      uploadedDate: '2023-03-28T09:34:42Z'
                      url: string
              schema:
                type: object
                $ref: '#/components/schemas/ListAccountingOrdersDocuments_Response_200'
          description: OK
      summary: ListAccountingOrdersDocuments - List accounting orders documents
      tags:
      - Storefront
  /api/storefront/orders/documents:
    get:
      description: '<div class="extension-title">Description</div>


        Retrieves a list of general order documents for specified Mirakl orders, with secure URLs for downloading each document.


        <div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- When you want to get documents for orders</div>

        </div>'
      operationId: ListOrdersDocuments
      parameters:
      - description: Mirakl orders identifier
        explode: true
        in: query
        name: orderIds
        required: true
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    documents:
                    - fileName: string
                      id: string
                      type: string
                      uploadedDate: '2023-03-28T09:34:42Z'
                      url: string
              schema:
                type: object
                $ref: '#/components/schemas/ListOrdersDocuments_Response_200'
          description: OK
      summary: ListOrdersDocuments - List orders documents
      tags:
      - Storefront
  /api/storefront/products/offers:
    get:
      description: '<div class="extension-title">Description</div>


        Calls the Mirakl P11 API and returns a trimmed payload tailored to the PDP.


        <div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- At each product page display</div>

        <div class="max-call-frequency">Maximum usage: <br/>- At each product page display</div>

        </div>'
      operationId: ListProductOffers
      parameters:
      - description: Mirakl product SKUs separated by comma (max 100)
        explode: true
        in: query
        name: productIds
        required: true
        schema:
          type: array
          items:
            type: string
          maxItems: 100
          minItems: 0
        style: form
      - description: Locale tag used to translate localized fields (e.g. en_US, fr_FR). Optional - defaults to the operator's primary locale when omitted.
        explode: true
        in: query
        name: locale
        required: false
        schema:
          type: string
        style: form
      - description: List of shipping zones. Filter used to pick shipping prices on one or multiple shipping zones
        explode: true
        in: query
        name: shippingZones
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    products: []
                application/json-auto:
                  summary: Complete example with value types (application/json)
                  value:
                    products:
                    - offers:
                      - allowQuoteRequests: true
                        currencyIsoCode: string
                        description: string
                        ecoContributions:
                        - ecoContributionAmount: 0
                          eprCategoryCode: string
                          producerId: string
                        favoriteRank: 0
                        fulfillment:
                          center:
                            code: string
                        maxOrderQuantity: 0
                        minOrderQuantity: 0
                        minQuantityAlert: 0
                        minShippingPrice: 0
                        minShippingPriceAdditional: 0
                        minShippingType: string
                        minShippingZone: string
                        model: MARKETPLACE
                        nbEvaluation: 0
                        offerId: string
                        packageQuantity: 0
                        price: 0
                        quantity: 0
                        shippingDeadline: '2023-03-28T09:34:42Z'
                        shippingTypes:
                        - code: string
                          cutOffNextDate: '2023-03-28T09:34:42Z'
                          cutOffTime: string
                          deliveryTime:
                            earliestDays: 0
                            earliestDeliveryDate: '2023-03-28T09:34:42Z'
                            latestDays: 0
                            latestDeliveryDate: '2023-03-28T09:34:42Z'
                          label: string
                          shippingDeadline: '2023-03-28T09:34:42Z'
                          shippingPriceType: FIXED_PRICE
                          shippingPriceUnit: 0
                          shippingZoneCode: string
                          shippingZoneLabel: string
                          standardCode: string
                        shopGrade: 0
                        shopId: string
                        shopName: string
                        stateCode: string
                        totalPrice: 0
                      productSku: string
              schema:
                type: object
                $ref: '#/components/schemas/ListProductOffers_Response_200'
          description: OK
      summary: ListProductOffers - List offers for each given product
      tags:
      - Storefront
  /api/storefront/shop-ratings/{shopId}:
    get:
      description: '<div class="api-description-extension">

        <div class="extension-title">Call Frequency</div>


        <div class="recommended-call-frequency">Recommended usage: <br/>- When you want to display shop ratings</div>

        <div class="extension-title">Pagination</div>


        <p>This resource supports offset pagination (<a href="#section/Offset-pagination-and-sort">see documentation</a>)</p>


        </div>'
      operationId: ListShopEvaluations
      parameters:
      - description: Mirakl shop identifier
        explode: false
        in: path
        name: shopId
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              examples:
                application/json-0:
                  summary: Example with business values (application/json)
                  value:
                    evaluations:
                    - assessments:
                      - code: '1'
                        label: Shipping method as expected
                        response: '4'
                      - code: '2'
                        label: Product condition matched description
                        response: 'true'
                      - code: '3'
                        label: Delivery deadline respected
                        response: 'true'
                      - code: '4'
                        label: Product well packaged
                        response: '4'
                      comment: Perfect..
                      createdAt: '2020-07-21T13:32:47.000+00:00'
                      customerId: 449-75-7939
                      entity:
                        createdAt: '2020-07-21T13:32:31.000+00:00'
                        id: MIR-VMO2X94U-A
                        type: MMP_ORDER
                      firstname: Debi
                      grade: 4
                      lastname: Russell
                      reply: null
                      updatedAt: '2020-07-21T13:32:47.000+00:00'
                    - assessments:
                      - code: '1'
                        label: Shipping method as expected
                        response: '3'
                      - code: '2'
                        label: Product condition matched description
                        response: 'true'
                      - code: '3'
                        label: Delivery deadline respected
                        response: 'false'
                      - code: '4'
                        label: Product well packaged
                        response: '5'
                      comment: Great seller, I recommend!
                      createdAt: '2024-10-04T14:44:17.000+00:00'
                      customerId: 689-07-6514
                      entity:
                        createdAt: '2020-07-21T13:32:33.000+00:00'
                        id: MIR-F7IXKO1W-A
                        type: MMP_ORDER
                      firstname: Robin
                      grade: 4
                      lastname: Diaz
                      reply:
                        comment: Thank you for your feedback!
                        date: '2024-10-04T14:44:17.000+00:00'
                        type: OPERATOR
                      updatedAt: '2024-10-04T14:44:17.000+00:00'
                    - assessments:
                      - code: '1'
                        label: Shipping method as expected
                        response: '5'
                      - code: '2'
                        label: Product condition matched description
                        response: 'true'
                      - code: '3'
                        label: Delivery deadline respected
                        response: 'false'
                      - code: '4'
                        label: Product well packaged
                        response: '0'
                      comment: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed id tortor imperdiet, iaculis risus at, aliquet est. Fusce laoreet gravida orci vitae consectetur. Mauris ac neque semper, vehicula velit non, imperdiet nisl. Morbi pharetra urna in magna posuere fermentum. Donec id dui fermentum, ultrices ligula eu, imperdiet tellus. Morbi efficitur euismod dolor, in tincidunt orci ullamcorper nec. Proin sit amet sapien elementum, faucibus justo vitae, sollicitudin sapien. Mauris eu ipsum non nisi porta vulputate. Duis sollicitudin et felis quis mattis. In in elit lacus.\n Nullam vitae nisl lectus. Suspendisse nec leo consectetur nibh maximus dapibus. Fusce luctus feugiat gravida. Maecenas nisl massa, placerat nec congue scelerisque, euismod at eros. Morbi ac tristique magna, eu placerat ipsum. Integer et felis et lectus viverra aliquet eu vel lectus. Nam scelerisque metus ex, sed lobortis ante finibus suscipit. In vel eros sit amet est congue cursus at at nulla. Praesent volutpat, lacus in gravida digni

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/mirakl-storefront-api-openapi.yml