# Changelog

The Postman collection is continuously updated based on changes made to the API. Remember to regularly [download the latest version of the collection](/specs/content/connector/operator/shopify/app-operator-shopify/rest/public/postman-app-operator-shopify-public.json?download) and update it.

## April 07, 2026

### Added

#### Platform Settings

- `GET /platform-settings/operator-return-configurations` (GetOperatorReturnConfigurations) - Retrieves the operator-level return configuration from the Mirakl platform. Exposes the return feature enablement status, the platform model, the handler responsible for processing returns, the operator return address, the return window, the available return methods, reasons and rejection reasons, the return policy, and whether shops are allowed to override return methods or policies.


#### Product Bindings

Three new endpoints for managing the mapping between Shopify products and Mirakl products. These bindings determine how the connector synchronizes price and stock.

- `POST /api/product-bindings` (ImportProductBindings) - Registers Shopify products and variants against their Mirakl counterparts.
  - `operatorManaged` defaults to true when omitted. Mirakl will not overwrite the product's content, media, or price in Shopify. Set to false for products whose content is fully driven by Mirakl.
  - Existing bindings with a matching `variantGroupCode` and Shopify GID are silently skipped.
  - Failures are collected in the response errors array without rolling back successful entries.
  - Maximum of 2,048 variants per request
- `POST /api/product-bindings/delete` (DeleteProductBindings) - Deletes bindings by any of four identifiers: `VARIANT_GROUP_CODE`, `SKU`, `SHOPIFY_GID`, or `MIRAKL_PRODUCT_ID`.
  - Deleting by `VARIANT_GROUP_CODE` removes the base product binding and all associated variants atomically.
  - Deleting a variant by `SKU`, `SHOPIFY_GID`, or `MIRAKL_PRODUCT_ID` also removes the parent binding if no other variants remain.
  - Same partial-success model as the import endpoint.
  - Maximum of 2,048 entries per request
- `GET /api/product-bindings` (ListProductBindings) - Returns bindings with offset-based pagination. All filters are optional and can be combined.


#### Storefront

- `POST /api/storefront/return` (CreateReturn) - Creates a return request for one or more items from a Mirakl logistic order, accepting a return reason, return method, line items with quantities, and optional file attachments. The return is created in Mirakl with any provided documents uploaded, and mirrored in Shopify on a best-effort basis — if the Shopify call fails, the return still exists in Mirakl and the Shopify return ID may be `null` in the response. It can be reconciled later via `POST /api/sync/returns` (if the scheduler is enabled, reconciliation will occur automatically during the next scheduled synchronization).
- `GET /api/storefront/returns` (GetReturns) - Retrieves the list of returns associated with one or more Mirakl commercial order IDs. Returns full return details including state, return lines, return address, tracking information, attached documents, and rejection reason when applicable. When called from a storefront context, results are automatically scoped to the authenticated customer's orders. Results are currently capped at 100 items (pagination not yet supported).
- `GET /api/storefront/returns/items-to-return` (GetItemsToReturn) - Returns the list of order line items eligible for return across one or more Mirakl commercial order IDs. For each eligible item, provides the returnable quantity, the applicable return window, and the available return methods and reasons. When called from a storefront context, ownership of the specified orders is validated against the authenticated customer. Results are currently capped at 100 items (pagination not yet supported).


#### Synchronization

- `POST /api/sync/returns` (SyncReturns) - Triggers an asynchronous synchronization of return states from Mirakl to Shopify. Accepts an optional `sinceDate` to restrict the sync to returns updated after a given timestamp; if omitted, the last recorded sync date is used. Handles the full return lifecycle — including state transitions such as approval, declination, cancellation, and closure — and retries Shopify return creations that previously failed. The sync is unidirectional (Mirakl → Shopify) and non-blocking: individual return errors do not interrupt the process and failed returns are retried on the next run.


## February 26, 2026

### Added

#### Settings

The `GET /api/settings` (ListSettings) and `PATCH /api/settings` (UpdateSettings) endpoints now support a new configuration node (`product.skuGenerations`) to provide more control over how product SKUs are generated in Shopify.

This new setting allows you to define an ordered list of fallback strategies for SKU generation (each defining a single strategy). When a product is synchronized, the connector will process this list in sequence, using the first strategy that produces a valid SKU.

Two strategies are available:

- `UNIQUE_IDENTIFIER_BASED`: uses the value from another Mirakl product attribute (e.g., barcode, EAN, ISBN) as the SKU.
- `MIRAKL_PRODUCT_ID_BASED`: generates a SKU using the internal Mirakl Product ID. This is the default behavior if no strategies are configured.


Example:


```JSON
"product": {
  "skuGenerations": [
    {
      "strategy": "UNIQUE_IDENTIFIER_BASED",
      "attributeCode": "manufacturer_id"
    },
    {
      "strategy": "UNIQUE_IDENTIFIER_BASED",
      "attributeCode": "ean"
    },
    {
      "strategy": "MIRAKL_PRODUCT_ID_BASED",
      "prefix": "mp-"
    }
  ]
}
```

## December 09, 2025

### Added

#### Storefront

- `GET /api/storefront/orders/accounting-documents` (GetAccountingOrdersDocuments)
Acts as a proxy for the Mirakl Platform API `DR73 - Download accounting documents` ([Front](/content/product/mmp/rest/front/openapi3/invoicing-and-accounting/dr73)).
- `GET /api/storefront/orders/documents` (GetOrdersDocuments)
Acts as a proxy for the Mirakl Platform API `OR73 - Download one or multiple documents attached to one or multiple orders` ([Front](/content/product/mmp/rest/front/openapi3/orders/or73)).


## December 05, 2025

### Added

#### Storefront

- `GET /api/storefront/evaluations/assessments` (GetEvaluationsAssessments)
Acts as a proxy for the Mirakl Platform API `EV01 - List rating types on your platform` ([Front](/content/product/mmp/rest/front/openapi3/platform-settings/ev01)).