Skip to content
Connectors
/
/
/Settings

Shopify Operator Connector APIs

General Notes

Authentication with OAuth 2.0

You must authenticate with a bearer token that can be generated from your Mirakl Platform back office. Refer to Generating API integration access tokens documentation page for more information.

Rate limits

Mirakl APIs are protected by rate limits. Each API has a dedicated section displaying its rate limit.

If you make too many calls, you might receive an HTTP 429 "Too Many Requests" error. The response will contain a Retry-After header that specifies the number of seconds to wait before making a new request.

Languages
Servers
Shopify production endpoint.
https://operator-shpy.mirakl.net

Storefront

Operations

Connection

Operations

Checkout

Operations

Synchronization Errors

Operations

Public

Operations

Settings

Operations

ListSettings - List connector settings

Request

Call Frequency
Recommended usage:
- When you are required to read your environment settings
Read More
curl -i -X GET \
  https://operator-shpy.mirakl.net/api/settings

Responses

OK

Bodyapplication/json
additionalLocalesArray of objectsunique

Additional locales configuration, aside the primary language of the store

categoriesobject

Configuration for category filtering during taxonomy export

customAppClientSecretstring

Client secret used to verify the signature of JWT tokens send in CustomerUI API call

customCarrierDescriptionstring

Description for the custom carrier

customCarrierTitlestring

Title for the custom carrier

fraudCheckobject

Fraud check

imageAttributesArray of objects

List of image attributes exported when taxonomy is synchronized in Mirakl

jobsobject

The job settings

lastDeletedMiraklProductSyncstring(date-time)

Timestamp of the last synchronization of Mirakl deleted products to Shopify

lastMiraklToShopifyProductSyncstring(date-time)

Timestamp of the last Mirakl to Shopify product synchronization

lastMiraklToShopifyShipmentSyncstring(date-time)

Timestamp of the last Mirakl to Shopify shipment synchronization

lastOfferSyncstring(date-time)

Timestamp of the last offer synchronization

lastOrderSyncstring(date-time)

Timestamp of the last order synchronization

lastShopSyncstring(date-time)

Timestamp of the last shop synchronization

lastShopifyToMiraklProductSyncstring(date-time)

Timestamp of the last Shopify to Mirakl product synchronization

miraklMasterModeobject

Mirakl Master Mode settings

miraklPayoutobject

Mirakl payout settings

offerobject

Offer settings

orderobject

Order settings

paymentobject

Payment settings

publicationIdsArray of stringsunique

The Shopify publication ids in which the third-party products and collections will be published

rootAttributesobject

Settings of the root attributes and their Mirakl attribute codes. Only relevant when miraklMasterMode is enabled. If empty, defaults to preset values.

shippingZoneMappingobject

Mapping to compute Mirakl shipping zone code from customer address

shopobject

Shop settings

syncMiraklToShopifyProductWithTagsArray of strings

List of all tags used to mark Mirakl products imported into Shopify.

syncShopifyToMiraklProductWithTagsArray of strings

List of all tags used to synchronize Shopify products to Mirakl. No product are exported if null or empty

taxonomyMetafieldsArray of objects

List of all Shopify Metafields exported when taxonomy is synchronized in Mirakl

vendorAsValueListboolean

Export Shopify vendor attribute as a LIST attribute instead of TEXT

Response
application/json
{
  "additionalLocales": [
    { … },
    { … }
  ],
  "categories": {
    "excludes": [],
    "includes": []
  },
  "customAppClientSecret": "79●●●●●●●●●●●●●●●●●●●●●●●●●●●●36",
  "customCarrierDescription": "For convenience, your marketplace orders are grouped",
  "customCarrierTitle": "Marketplace orders",
  "fraudCheck": {
    "analysisFactDescription": null,
    "strategy": "NO_CHECK"
  },
  "imageAttributes": [
    { … }
  ],
  "jobs": {
    "SyncFirstPartyProducts": { … },
    "SyncOffers": { … },
    "SyncOrders": { … },
    "SyncShipments": { … },
    "SyncShops": { … },
    "SyncThirdPartyProducts": { … }
  },
  "lastDeletedMiraklProductSync": "2025-08-01T22:04:00Z",
  "lastMiraklToShopifyProductSync": "2024-09-20T10:00:00Z",
  "lastMiraklToShopifyShipmentSync": "2025-07-16T15:45:23Z",
  "lastOfferSync": "2024-09-01T10:20:30Z",
  "lastOrderSync": "2024-11-01T10:20:30Z",
  "lastShopSync": "2024-09-01T10:20:30Z",
  "lastShopifyToMiraklProductSync": "2024-09-20T10:00:00Z",
  "miraklMasterMode": {
    "enabled": false,
    "useShopifyCategories": false
  },
  "miraklPayout": {
    "payinPspId": null
  },
  "offer": {
    "synchronizeAdvancedPricing": false
  },
  "order": {
    "miraklExportCustomerOrganization": { … },
    "orderMetafields": [ … ]
  },
  "payment": {
    "confirmCaptureToMirakl": false,
    "confirmRefundToMirakl": false,
    "create3PCaptureInShopify": false,
    "create3PRefundInShopify": false,
    "miraklPaymentWorkflow": "PAY_ON_ACCEPTANCE",
    "useMiraklPayout": false,
    "useTransactionNumberForCaptureFromMetafield": false,
    "useTransactionNumberForRefundFromMetafield": false
  },
  "publicationIds": [
    "gid://shopify/Publication/220528771398"
  ],
  "rootAttributes": {
    "BARCODE": { … },
    "CATEGORY": { … },
    "DESCRIPTION": { … },
    "SHOP_SKU": { … },
    "TITLE": { … },
    "VARIANT_GROUP_CODE": { … },
    "VENDOR": { … },
    "WEIGHT": { … }
  },
  "shippingZoneMapping": {
    "countries": [ … ],
    "shippingZone": "INT"
  },
  "shop": {
    "shopMiraklCustomFields": [ … ]
  },
  "syncMiraklToShopifyProductWithTags": [
    "from_mirakl"
  ],
  "syncShopifyToMiraklProductWithTags": [
    "mirakl_sync"
  ],
  "taxonomyMetafields": [
    { … }
  ],
  "vendorAsValueList": false
}

UpdateSettings - Update connector settings

Request

Update your environment settings information field by field: unspecified fields will not be updated.

Call Frequency
Recommended usage:
- When you are required to update the settings

Bodyapplication/json
additionalLocalesArray of objectsunique

Additional locales configuration, aside the primary language of the store

categoriesobject

Configuration for category filtering during taxonomy export

customAppClientSecretstring

Client secret used to verify the signature of JWT tokens send in CustomerUI API call

customCarrierDescriptionstring

Description for the custom carrier

customCarrierTitlestring

Title for the custom carrier

fraudCheckobject

Fraud check

imageAttributesArray of objects

List of image attributes exported when taxonomy is synchronized in Mirakl

jobsobject

The job settings

lastDeletedMiraklProductSyncstring(date-time)

Timestamp of the last synchronization of Mirakl deleted products to Shopify

lastMiraklToShopifyProductSyncstring(date-time)

Timestamp of the last Mirakl to Shopify product synchronization

lastMiraklToShopifyShipmentSyncstring(date-time)

Timestamp of the last Mirakl to Shopify shipment synchronization

lastOfferSyncstring(date-time)

Timestamp of the last offer synchronization

lastOrderSyncstring(date-time)

Timestamp of the last order synchronization

lastShopSyncstring(date-time)

Timestamp of the last shop synchronization

lastShopifyToMiraklProductSyncstring(date-time)

Timestamp of the last Shopify to Mirakl product synchronization

miraklMasterModeobject

Mirakl Master Mode settings

miraklPayoutobject

Mirakl payout settings

offerobject

Offer settings

orderobject

Order settings

paymentobject

Payment settings

publicationIdsArray of stringsunique

The Shopify publication ids in which the third-party products and collections will be published

rootAttributesobject

Settings of the root attributes and their Mirakl attribute codes. Only relevant when miraklMasterMode is enabled. If not provided, defaults to preset values.

shippingZoneMappingobject

Mapping to compute Mirakl shipping zone code from customer address

shopobject

Shop settings

syncMiraklToShopifyProductWithTagsArray of strings

List of all tags used to mark Mirakl products imported into Shopify.

syncShopifyToMiraklProductWithTagsArray of strings

List of all tags used to synchronize Shopify products to Mirakl. No product are exported if null or empty

taxonomyMetafieldsArray of objects

List of all Shopify Metafields exported when taxonomy is synchronized in Mirakl

vendorAsValueListboolean

Export Shopify vendor attribute as a LIST attribute instead of TEXT

curl -i -X PATCH \
  https://operator-shpy.mirakl.net/api/settings \
  -H 'Content-Type: application/json' \
  -d '{
    "additionalLocales": [
      {
        "locale": "it"
      }
    ],
    "categories": {
      "excludes": [
        "gid://shopify/TaxonomyCategory/sg-4-17-3"
      ],
      "includes": [
        "gid://shopify/TaxonomyCategory/sg-4-17"
      ]
    },
    "customAppClientSecret": "0123456789abcdef0123456789abcdef0123",
    "customCarrierDescription": "My custom carrier description",
    "customCarrierTitle": "My custom carrier title",
    "fraudCheck": {
      "analysisFactDescription": "validated",
      "strategy": "CUSTOM_ASSESSMENT"
    },
    "imageAttributes": [
      {
        "code": "main_image_1",
        "isMainImage": true,
        "label": "Main Image"
      },
      {
        "code": "swatch",
        "isMainImage": false,
        "label": "Swatch"
      }
    ],
    "jobs": {
      "SyncFirstPartyProducts": {
        "scheduled": false
      },
      "SyncOffers": {
        "scheduled": true
      },
      "SyncOrders": {
        "scheduled": true
      },
      "SyncShipments": {
        "scheduled": true
      },
      "SyncShops": {
        "scheduled": true
      },
      "SyncThirdPartyProducts": {
        "scheduled": true
      }
    },
    "lastDeletedMiraklProductSync": "2025-08-01T22:04:00Z",
    "lastMiraklToShopifyProductSync": "2024-09-01T12:00:00Z",
    "lastMiraklToShopifyShipmentSync": "2025-07-16T15:45:23Z",
    "lastOfferSync": "2024-09-01T09:20:30Z",
    "lastOrderSync": "2024-11-01T10:20:30Z",
    "lastShopifyToMiraklProductSync": "2024-09-01T12:00:00Z",
    "miraklMasterMode": {
      "enabled": true,
      "useShopifyCategories": false
    },
    "miraklPayout": {
      "payinPspId": "PAYIN-EUR"
    },
    "offer": {
      "synchronizeAdvancedPricing": true
    },
    "order": {
      "miraklExportCustomerOrganization": {
        "mode": "FULL"
      },
      "orderMetafields": [
        {
          "miraklCustomFieldCode": "mirakl_customer_type",
          "shopifyKey": "customer_type",
          "shopifyNamespace": "custom"
        }
      ]
    },
    "payment": {
      "confirmCaptureToMirakl": true,
      "confirmRefundToMirakl": true,
      "create3PCaptureInShopify": true,
      "create3PRefundInShopify": true,
      "miraklPaymentWorkflow": "PAY_ON_SHIPMENT",
      "useMiraklPayout": true,
      "useTransactionNumberForCaptureFromMetafield": true,
      "useTransactionNumberForRefundFromMetafield": true
    },
    "publicationIds": [
      "gid://shopify/Publication/220528771398"
    ],
    "rootAttributes": {
      "BARCODE": {
        "code": "barcode"
      },
      "CATEGORY": {
        "code": "category"
      },
      "DESCRIPTION": {
        "code": "description"
      },
      "SHOP_SKU": {
        "code": "shop_sku"
      },
      "TITLE": {
        "code": "title"
      },
      "VARIANT_GROUP_CODE": {
        "code": "variant_group_code"
      },
      "VENDOR": {
        "code": "vendor"
      },
      "WEIGHT": {
        "code": "weight"
      }
    },
    "shippingZoneMapping": {
      "countries": [
        {
          "iso2Code": "US",
          "provinces": [
            {
              "code": "MA",
              "shippingZone": "MASSACHUSETTS"
            }
          ],
          "shippingZone": "USA",
          "zips": null
        },
        {
          "iso2Code": "FR",
          "provinces": null,
          "shippingZone": "FRANCE",
          "zips": [
            {
              "code": "75",
              "shippingZone": "PARIS"
            }
          ]
        }
      ],
      "shippingZone": "INT"
    },
    "shop": {
      "shopMiraklCustomFields": [
        {
          "code": "customer-care-phone"
        },
        {
          "code": "customer-care-email"
        },
        {
          "code": "shipping-policy"
        }
      ]
    },
    "taxonomyMetafields": [
      {
        "key": "materials",
        "namespace": "custom",
        "ownerType": "PRODUCT"
      },
      {
        "key": "boolean",
        "namespace": "test",
        "ownerType": "PRODUCTVARIANT"
      }
    ],
    "vendorAsValueList": true
  }'

Responses

OK

Bodyapplication/json
additionalLocalesArray of objectsunique

Additional locales configuration, aside the primary language of the store

categoriesobject

Configuration for category filtering during taxonomy export

customAppClientSecretstring

Client secret used to verify the signature of JWT tokens send in CustomerUI API call

customCarrierDescriptionstring

Description for the custom carrier

customCarrierTitlestring

Title for the custom carrier

fraudCheckobject

Fraud check

imageAttributesArray of objects

List of image attributes exported when taxonomy is synchronized in Mirakl

jobsobject

The job settings

lastDeletedMiraklProductSyncstring(date-time)

Timestamp of the last synchronization of Mirakl deleted products to Shopify

lastMiraklToShopifyProductSyncstring(date-time)

Timestamp of the last Mirakl to Shopify product synchronization

lastMiraklToShopifyShipmentSyncstring(date-time)

Timestamp of the last Mirakl to Shopify shipment synchronization

lastOfferSyncstring(date-time)

Timestamp of the last offer synchronization

lastOrderSyncstring(date-time)

Timestamp of the last order synchronization

lastShopSyncstring(date-time)

Timestamp of the last shop synchronization

lastShopifyToMiraklProductSyncstring(date-time)

Timestamp of the last Shopify to Mirakl product synchronization

miraklMasterModeobject

Mirakl Master Mode settings

miraklPayoutobject

Mirakl payout settings

offerobject

Offer settings

orderobject

Order settings

paymentobject

Payment settings

publicationIdsArray of stringsunique

The Shopify publication ids in which the third-party products and collections will be published

rootAttributesobject

Settings of the root attributes and their Mirakl attribute codes. Only relevant when miraklMasterMode is enabled. If empty, defaults to preset values.

shippingZoneMappingobject

Mapping to compute Mirakl shipping zone code from customer address

shopobject

Shop settings

syncMiraklToShopifyProductWithTagsArray of strings

List of all tags used to mark Mirakl products imported into Shopify.

syncShopifyToMiraklProductWithTagsArray of strings

List of all tags used to synchronize Shopify products to Mirakl. No product are exported if null or empty

taxonomyMetafieldsArray of objects

List of all Shopify Metafields exported when taxonomy is synchronized in Mirakl

vendorAsValueListboolean

Export Shopify vendor attribute as a LIST attribute instead of TEXT

Response
application/json
{
  "additionalLocales": [
    { … }
  ],
  "categories": {
    "excludes": [ … ],
    "includes": [ … ]
  },
  "customAppClientSecret": "01●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●23",
  "customCarrierDescription": "My custom carrier description",
  "customCarrierTitle": "My custom carrier title",
  "fraudCheck": {
    "analysisFactDescription": "validated",
    "strategy": "CUSTOM_ASSESSMENT"
  },
  "imageAttributes": [
    { … },
    { … }
  ],
  "jobs": {
    "SyncFirstPartyProducts": { … },
    "SyncOffers": { … },
    "SyncOrders": { … },
    "SyncShipments": { … },
    "SyncShops": { … },
    "SyncThirdPartyProducts": { … }
  },
  "lastDeletedMiraklProductSync": "2025-08-01T22:04:00Z",
  "lastMiraklToShopifyProductSync": "2024-09-01T12:00:00Z",
  "lastMiraklToShopifyShipmentSync": "2025-07-16T15:45:23Z",
  "lastOfferSync": "2024-09-01T09:20:30Z",
  "lastOrderSync": "2024-11-01T10:20:30Z",
  "lastShopSync": "2024-09-01T10:20:30Z",
  "lastShopifyToMiraklProductSync": "2024-09-01T12:00:00Z",
  "miraklMasterMode": {
    "enabled": true,
    "useShopifyCategories": false
  },
  "miraklPayout": {
    "payinPspId": "PAYIN-EUR"
  },
  "offer": {
    "synchronizeAdvancedPricing": true
  },
  "order": {
    "miraklExportCustomerOrganization": { … },
    "orderMetafields": [ … ]
  },
  "payment": {
    "confirmCaptureToMirakl": true,
    "confirmRefundToMirakl": true,
    "create3PCaptureInShopify": true,
    "create3PRefundInShopify": true,
    "miraklPaymentWorkflow": "PAY_ON_SHIPMENT",
    "useMiraklPayout": true,
    "useTransactionNumberForCaptureFromMetafield": true,
    "useTransactionNumberForRefundFromMetafield": true
  },
  "publicationIds": [
    "gid://shopify/Publication/220528771398"
  ],
  "rootAttributes": {
    "BARCODE": { … },
    "CATEGORY": { … },
    "DESCRIPTION": { … },
    "SHOP_SKU": { … },
    "TITLE": { … },
    "VARIANT_GROUP_CODE": { … },
    "VENDOR": { … },
    "WEIGHT": { … }
  },
  "shippingZoneMapping": {
    "countries": [ … ],
    "shippingZone": "INT"
  },
  "shop": {
    "shopMiraklCustomFields": [ … ]
  },
  "syncMiraklToShopifyProductWithTags": [
    "from_mirakl"
  ],
  "syncShopifyToMiraklProductWithTags": [
    "mirakl_sync"
  ],
  "taxonomyMetafields": [
    { … },
    { … }
  ],
  "vendorAsValueList": true
}

Setup

Operations

Synchronization

Operations