.png)
Mirakl Integration Guide
Connect Mirakl marketplace operations with enterprise systems through REST APIs, selected event notifications, asynchronous processing, and orchestrated Martini workflows.
Mirakl integration options at a glance
Mirakl is primarily integrated through REST APIs whose available resources and permissions vary by product, marketplace deployment, and operator or seller role. Martini can consume these APIs to synchronize Shops, Products, Offers, Orders, Categories, and Users with enterprise applications. Selected Mirakl products and events support webhook-style notifications, while scheduled incremental polling remains useful for uncovered changes. For large catalog and offer operations, Martini can submit asynchronous or file-based jobs, persist job identifiers, poll for completion, and process validation reports. API keys are the common authentication method and can be stored in Martini secrets and environment configuration.
| Integration point | Supported by Mirakl? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Mirakl REST APIs are the primary integration mechanism for retrieving and updating Shops, Products, Offers, Orders, Categories, Users, fulfillment information, and marketplace configuration. Available resources vary by product and operator or seller role. | Martini can consume Mirakl REST APIs from workflows, map responses into canonical models, expose APIs for downstream applications, and apply business rules before writing results. |
| Webhooks and outbound callbacks | Limited | Selected Mirakl products and events can provide webhook-style or event notifications for changes such as orders, offer or inventory updates, shop status, and catalog processing results. Coverage is not universal. | Martini can receive supported Mirakl notifications, retrieve the current resource through REST, and use scheduled polling for objects or transitions without event coverage. |
| Bulk, asynchronous, and batch APIs | Yes | Large catalog, offer, seller, and marketplace operations can use asynchronous or file-based imports and exports where supported. Processing reports can contain row-level validation results. | Martini can submit an import or export, persist the returned job identifier, poll for completion, retrieve processing results, and route rejected rows for correction. |
| File and attachment APIs | Limited | Selected Mirakl resources may support catalog files, product media, documents, import files, or export files. Availability and behavior depend on the Mirakl product and endpoint. | Martini can orchestrate approved file transfers and transform file content, while keeping endpoint-specific file and attachment behavior configurable and validated. |
| Authentication | Yes | API keys supplied through request authorization headers are a common Mirakl authentication method. Permissions depend on the API user, role, marketplace configuration, and API family; OAuth may be product-specific. | Martini can store Mirakl API keys or other confirmed credentials in secrets and environment configuration, then apply them to API-consuming workflows without embedding them in definitions. |
| Incremental synchronization | Yes | Changes can generally be identified with modified-date or updated-at filters, status filters, pagination parameters, asynchronous exports, or event notifications where available. | Martini can maintain timestamps, cursors, page checkpoints, or processing ledgers and use them to implement recoverable scheduled synchronization. |
| SDKs | Not confirmed | Mirakl provides developer documentation and API specifications, but a dedicated SDK should not be assumed for every language or product. | Martini can call Mirakl APIs directly over HTTP and use custom JVM-compatible logic only where endpoint-specific processing requires it. |
| Database access | No | Direct access to Mirakl-managed production databases is not a standard integration mechanism. APIs, exports, event notifications, and approved file interfaces should be used instead. | Martini can connect to an enterprise database when required for staging or reconciliation, but it should not be represented as direct database access to Mirakl. |
How Mirakl exposes data and business events
Mirakl REST APIs
Mirakl REST APIs are the primary integration mechanism. API families and available resources vary by product, marketplace deployment, and whether the caller is an operator, seller, storefront, or another authorized user. REST operations can retrieve and update Shops, Products, Offers, Orders, Categories, Users, fulfillment data, and marketplace configuration.
Martini implementation pattern
Martini implementation pattern: A workflow authenticates with a Mirakl API key held in secrets, invokes the required endpoint, validates the response, maps the payload into a canonical model, and writes it to the target application. For outbound updates, Martini applies business rules and records request, response, and processing identifiers for reconciliation.
Implementation sequence
Mirakl webhooks and event notifications
Mirakl supports webhook-style or event notification capabilities for selected products and marketplace events. Possible notifications include new or updated Orders, order status changes, Offer or inventory changes, Shop status changes, and catalog processing results, but coverage must be confirmed for the tenant and event model.
Martini implementation pattern
Martini implementation pattern: Martini receives a supported notification through an API or workflow trigger, validates the incoming request according to the configured event security model, and retrieves the authoritative Mirakl resource through REST. When no notification exists for a change, a scheduled workflow uses incremental polling and a durable watermark instead.
Implementation sequence
Mirakl bulk and asynchronous processing
Mirakl provides asynchronous or file-based processing for some high-volume catalog, offer, seller, import, and export operations. A submission may return a job or import identifier before processing is complete, with later results containing validation or row-level errors.
Martini implementation pattern
Martini implementation pattern: Martini prepares and submits the catalog or offer payload, stores the returned job identifier, polls with a controlled interval, and retrieves the processing report. The workflow distinguishes request acceptance from successful completion and routes rejected rows to an operational review process.
Implementation sequence
Mirakl incremental synchronization
Mirakl data can generally be synchronized incrementally using updated-at or modified-date filters, status filters, pagination, asynchronous exports, or event notifications where available. Exact filter names, pagination behavior, and consistency guarantees vary by API family.
Martini implementation pattern
Martini implementation pattern: A scheduled workflow reads the last successful watermark or cursor, requests a bounded page of changed objects, processes and commits each page, and advances the checkpoint only after successful target writes. A look-back window and periodic reconciliation help handle late-arriving changes and missed notifications.
Implementation sequence
Common Mirakl integration patterns
Pattern 1: Synchronize products and offers from a PIM or ERP
When to use this pattern
Use this pattern when catalog, pricing, inventory, or lead-time changes originate in an ERP or PIM and must be published to Mirakl. Products and seller-specific Offers should remain separate models, with category-specific validation before submission.
Integration direction
Example Mapping
| Mirakl Field | Canonical Field | Target Field |
|---|---|---|
| product identifier | product.externalId | Mirakl Product identifier |
| attribute values | product.attributes | Mirakl Product attributes |
| unit price | offer.price | Mirakl Offer price |
| available quantity | offer.quantity | Mirakl Offer quantity |
Martini implementation pattern
A scheduled Martini workflow retrieves changed products and commercial data, validates required category attributes, maps product and offer payloads separately, and submits REST or asynchronous Mirakl operations. It persists job identifiers, processes validation reports, and routes rejected products or offers for correction rather than treating request acceptance as completion.
Martini capabilities used
- workflows
- scheduling
- API consumption
- data mapping
- business rules
- asynchronous orchestration
- error handling
Pattern 2: Orchestrate Mirakl Orders to fulfillment systems
When to use this pattern
Use this pattern when Mirakl Orders must be sent to an ERP, OMS, WMS, or fulfillment application and marketplace state must be updated as the order progresses. It is appropriate for both event-driven and scheduled order retrieval.
Integration direction
Example Mapping
| Mirakl Field | Canonical Field | Target Field |
|---|---|---|
| order identifier | order.externalId | fulfillment order number |
| suborder identifier | order.sellerOrderId | seller fulfillment reference |
| order lines | order.lines | fulfillment line items |
| shipment tracking number | shipment.trackingNumber | Mirakl shipment tracking number |
Martini implementation pattern
Martini receives a supported event or polls for new and updated Orders, checks the order and suborder ledger for duplicates, transforms seller-specific lines and fulfillment data, and submits the target order. After acceptance, shipment, cancellation, or other supported transitions, another workflow updates Mirakl and handles out-of-order notifications, transient failures, and reconciliation.
Martini capabilities used
- event-driven workflows
- scheduled synchronization
- API consumption
- data mapping
- idempotency rules
- conditional routing
- retry and reconciliation handling
Pattern 3: Govern seller onboarding and Shop activation
When to use this pattern
Use this pattern when seller onboarding is managed in a CRM, service platform, or internal process and approved sellers must be created or updated in Mirakl. It supports validation and manual review before a Shop becomes operational.
Integration direction
Example Mapping
| Mirakl Field | Canonical Field | Target Field |
|---|---|---|
| seller account ID | seller.externalId | Mirakl Shop identifier |
| seller legal name | seller.legalName | Mirakl Shop name |
| seller status | seller.lifecycleStatus | Mirakl Shop status |
| category permissions | seller.categoryPermissions | Mirakl Shop category configuration |
Martini implementation pattern
A Martini API or scheduled workflow receives seller data, validates required identity and commercial fields, applies approval rules, and submits authorized Shop operations to Mirakl. Incomplete or conflicting data is routed to manual review, while successful and rejected outcomes are returned to the source system with audit identifiers.
Martini capabilities used
- APIs
- workflows
- data validation
- mapping and transformation
- business rules
- conditional routing
- error handling
Pattern 4: Synchronize inventory and fulfillment status
When to use this pattern
Use this pattern when inventory changes originate in an ERP or WMS and fulfillment events originate in Mirakl or a downstream shipping process. It keeps seller Offers aligned with available quantity and returns shipment information to the marketplace.
Integration direction
Example Mapping
| Mirakl Field | Canonical Field | Target Field |
|---|---|---|
| stock quantity | inventory.availableQuantity | Mirakl Offer quantity |
| lead time | inventory.leadTime | Mirakl Offer lead time |
| shipment status | fulfillment.status | Mirakl shipment status |
| tracking number | fulfillment.trackingNumber | Mirakl tracking information |
Martini implementation pattern
Martini reads incremental inventory changes, maps them to seller-specific Offers, and submits bounded updates to Mirakl. A second workflow consumes or polls order and shipment changes, sends fulfillment instructions to the target system, and updates Mirakl only after validating the corresponding order, suborder, and shipment identifiers. Retry ledgers prevent duplicate updates.
Martini capabilities used
- scheduled workflows
- API consumption
- incremental synchronization
- data mapping
- business rules
- idempotency
- monitoring and reconciliation
Applications commonly integrated with Mirakl
Mirakl can be integrated at the API level with adjacent commerce, ERP, PIM, fulfillment, customer, and service applications. The exact resources and mappings depend on the Mirakl product, tenant configuration, and API permissions.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize seller onboarding, Shop status, account ownership, commercial relationships, and marketplace support activity. | Salesforce → Martini → Mirakl | Martini can receive seller or account changes from Salesforce, validate required onboarding data, map it to Mirakl Shop structures, and submit authorized REST API requests. Status changes and validation results can be returned to Salesforce through a separate workflow. |
| SAP S/4HANA | Exchange product, inventory, pricing, order, billing, and fulfillment information between the ERP and marketplace. | SAP S/4HANA → Martini → Mirakl | A scheduled or event-driven Martini workflow can retrieve changed ERP data, transform it into Mirakl Product and Offer structures, submit updates, and reconcile asynchronous processing results. Order and fulfillment updates can flow in the opposite direction with idempotency controls. |
| NetSuite | Synchronize catalog, inventory, orders, fulfillment, and financial settlement data between NetSuite and Mirakl. | NetSuite → Martini → Mirakl | Martini can orchestrate bidirectional REST API workflows, map NetSuite items and transactions to Mirakl Products, Offers, and Orders, apply marketplace business rules, and persist processing checkpoints and rejection details. |
| Adobe Commerce | Coordinate marketplace catalog, customer orders, inventory, and storefront commerce processes. | Adobe Commerce → Martini → Mirakl | Martini can expose controlled APIs for Adobe Commerce, consume Mirakl REST resources, and transform Products, Offers, Orders, and inventory updates between the two platforms. Retries and application-level deduplication protect against duplicate order or offer updates. |
| Shopify | Exchange product, offer, order, and inventory information where Shopify participates in the wider commerce architecture. | Shopify → Martini → Mirakl | Martini can schedule incremental reads or receive supported notifications, normalize Shopify and Mirakl identifiers, and route transformed catalog, inventory, and order payloads through API-consuming workflows. Endpoint-specific limits and state models should be confirmed before deployment. |
| Akeneo | Send product information, attributes, and category-related data from a PIM into the Mirakl marketplace catalog. | Akeneo → Martini → Mirakl | A Martini workflow can retrieve changed Akeneo products, validate category-specific attributes, map them to Mirakl Products and Categories, submit synchronous or asynchronous updates, and route row-level validation errors for correction. |
| ServiceNow | Manage seller onboarding tasks, operational incidents, and marketplace support workflows around Mirakl activity. | Mirakl → Martini → ServiceNow | Martini can consume Mirakl Shop status changes or scheduled extracts, create or update ServiceNow work items, and send approved status changes back to Mirakl where the relevant API permissions support that operation. |
| Manhattan Active | Exchange marketplace orders, inventory, shipment, and fulfillment status with an order or fulfillment platform. | Mirakl → Martini → Manhattan Active | Martini can receive or poll Mirakl Orders, distinguish marketplace orders from seller suborders, transform fulfillment instructions for Manhattan Active, and return shipment and tracking updates to Mirakl after reconciliation. |
How to build a Mirakl integration in Martini
Objective
Establish the Mirakl API connection with the correct operator, seller, or other authorized user context and keep credentials outside workflow definitions.
Instructions in Martini
- Confirm the Mirakl product, tenant, API family, role, and required permissions
- Store the Mirakl API key or other confirmed credential in Martini secrets and environment configuration
- Configure the API request authorization and separate development, test, and production credentials
- Avoid logging authorization headers or sensitive marketplace data
Objective
Select an event, schedule, or API entry point based on the Mirakl resource and the completeness of event coverage.
Instructions in Martini
- Use a supported Mirakl event notification for selected changes when available
- Use a scheduler for incremental polling when an event is unavailable or coverage is incomplete
- Use a Martini API when another application needs to initiate a Mirakl operation
- Define a watermark, cursor, status filter, or job ledger for recoverable processing
Objective
Read the authoritative Mirakl resource or processing result while handling pagination, asynchronous jobs, and endpoint-specific response behavior.
Instructions in Martini
- Retrieve the current Shop, Product, Offer, Order, Category, or User through the relevant REST API
- Implement endpoint-specific pagination and stable sorting where supported
- Persist asynchronous import, export, or catalog job identifiers
- Poll for completion with bounded intervals and retrieve processing reports
Objective
Coordinate calls to Mirakl and connected applications as a maintainable Martini workflow rather than a point-to-point request.
Instructions in Martini
- Separate notification receipt, resource retrieval, transformation, target writes, and status updates into clear workflow stages
- Use conditional routing for operator versus seller data and synchronous versus asynchronous operations
- Persist checkpoints and processing outcomes at durable boundaries
- Use reusable services or APIs for common marketplace operations when appropriate
Objective
Convert Mirakl marketplace models into target-system structures while preserving the distinction between Products, Offers, Shops, Orders, and suborders.
Instructions in Martini
- Map Mirakl identifiers to canonical and target identifiers
- Transform product attributes, prices, quantities, lead times, order lines, and fulfillment fields
- Keep Product master data separate from seller-specific Offer data
- Normalize dates, statuses, enumerations, and file or report content before target writes
Objective
Enforce marketplace, catalog, seller, fulfillment, and duplicate-prevention rules before changing either Mirakl or a connected system.
Instructions in Martini
- Validate required category attributes and seller onboarding fields
- Check order and suborder identifiers before creating target orders
- Prevent invalid fulfillment or order-state transitions
- Route incomplete, rejected, or conflicting data to review workflows
Common Mirakl data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Shops | Represent marketplace sellers or merchant accounts, including status, contacts, commercial configuration, and operational settings. | Salesforce, SAP S/4HANA, NetSuite, ServiceNow, identity platforms | Martini retrieves or receives Shop changes, validates onboarding and permission rules, maps seller data to target models, and records activation or rejection outcomes. |
| Offers | Represent seller-specific commercial offers for Products, including price, quantity, lead time, condition, fulfillment information, and offer status. | SAP S/4HANA, NetSuite, Adobe Commerce, Shopify, Manhattan Active | Martini separates Offers from Product master data, applies pricing and inventory rules, submits updates through REST or asynchronous APIs, and reconciles validation results. |
| Products | Represent marketplace catalog products with product identifiers and attributes. | Akeneo, SAP S/4HANA, NetSuite, Adobe Commerce, Shopify | Martini maps source catalog attributes and identifiers, validates required category fields, submits product updates, and routes rejected rows from asynchronous processing. |
| Orders | Represent customer orders, including marketplace suborders or seller-specific order lines and order state changes. | SAP S/4HANA, NetSuite, Adobe Commerce, Manhattan Active, ServiceNow | Martini consumes notifications or polls incrementally, uses order and suborder identifiers for idempotency, transforms order lines, and sends acceptance, shipment, cancellation, or reconciliation updates. |
| Categories | Provide marketplace taxonomy used to classify Products and validate category-specific attributes. | Akeneo, SAP S/4HANA, NetSuite, Adobe Commerce | Martini can retrieve Categories and use them to validate and route product mappings before submitting catalog data. |
| Users | Represent operator, seller, or marketplace users whose roles and permissions govern API access. | Salesforce, ServiceNow, identity platforms, internal administration systems | Martini can synchronize approved user or access data where the relevant API permits it, while keeping credentials and authorization context in protected configuration. |
Authentication and security considerations
API keys and authorization context
Mirakl commonly authenticates REST API requests with an API key supplied in the authorization header. The applicable permissions depend on the Mirakl user, role, marketplace configuration, and API family. Operator and seller APIs can expose different resources and boundaries.
Credential protection
Store Mirakl API keys and any product-specific credentials in Martini secrets and environment configuration. Use separate credentials for development, test, and production, and avoid logging authorization headers, seller credentials, customer data, or payment-related information.
Least privilege
- Confirm permissions for catalog, offer, order, Shop, User, and fulfillment operations before deployment.
- Validate inbound event requests according to the authentication and verification method supported by the relevant Mirakl event mechanism.
- Do not assume OAuth 2.0 is universal across Mirakl APIs; verify it for the specific product and API family.
Operational considerations for Mirakl integrations
Rate limits and pagination
Confirm limits for each Mirakl API family, use bounded concurrency and exponential backoff for throttling or transient server errors, and implement endpoint-specific pagination. Persist page, cursor, or watermark checkpoints so batch work can resume safely.
Asynchronous processing
Treat acceptance of an import or export request as different from successful completion. Persist job identifiers, poll at controlled intervals, retrieve processing reports, and expose row-level validation errors for operational correction.
Idempotency and state
Use Mirakl order IDs, suborder IDs, Offer and Product identifiers, and import job IDs as business keys. Prevent duplicate target writes, validate order and fulfillment state transitions, and account for out-of-order or repeated notifications.
Schema and reconciliation
Pin API versions where available, monitor tenant-specific documentation and release changes, and make mappings tolerant of additive fields while remaining strict about required identifiers and states. Periodic reconciliation helps detect missed notifications and partial updates.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate the full marketplace process
Scripts often handle one API call or one synchronization path. Martini can coordinate notifications, REST retrieval, asynchronous job polling, target writes, status updates, and reconciliation as a single maintainable workflow.
Centralize mapping and business rules
Martini provides a place to separate Products, Offers, Shops, Orders, and suborders, transform marketplace data into canonical models, validate category and seller requirements, and apply idempotency and fulfillment rules consistently.
Improve operational control
- Use secrets and environment configuration for credentials.
- Persist checkpoints, job identifiers, and processing outcomes.
- Route validation failures and business exceptions for review.
- Retry transient failures without duplicating successful target writes.
- Expose controlled APIs for downstream systems when a reusable integration boundary is needed.
Frequently asked questions
Mirakl is primarily integrated through REST APIs that expose marketplace resources such as Shops, Products, Offers, Orders, Categories, and Users. Selected products and events may support webhook-style notifications, while bulk and asynchronous operations support larger catalog and offer workloads. Scheduled incremental synchronization can cover changes that are not notified.
Yes. Martini can integrate with Mirakl by consuming its REST APIs, receiving supported event notifications, submitting asynchronous or file-based operations where available, and orchestrating data with ERP, PIM, commerce, fulfillment, CRM, and service applications.
No. A dedicated Mirakl connector is not required. Martini can use Mirakl's confirmed native integration mechanisms, including REST APIs, selected webhook-style notifications, asynchronous jobs, approved file interfaces, and API-key authentication.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Mirakl. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Mirakl, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
REST APIs are the primary recommended method for current Mirakl integrations. Use selected event notifications when the required product and event are supported, asynchronous or bulk processing for large catalog and offer operations, and scheduled incremental polling for uncovered changes. GraphQL and SOAP should not be assumed because they were not confirmed in the supplied Mirakl research.
Mirakl supports webhook-style or event notification capabilities for selected products and events, but not necessarily for every object or state transition. Coverage should be verified for the tenant and event model. Martini can receive supported notifications and use REST retrieval or scheduled polling where notifications are unavailable.
Martini can use updated-at or modified-date filters, status filters, pagination, event notifications, or asynchronous exports to implement incremental synchronization. For large catalog or offer updates, it can submit a Mirakl job, persist the job identifier, poll for completion, retrieve processing results, and route row-level failures for correction.
Martini maps Mirakl's distinct Products, Offers, Shops, Orders, and suborders into canonical and target models, then applies validation and business rules before writing data. Workflows can use order, offer, product, and job identifiers for application-level idempotency, retry transient failures with bounded backoff, separate transport and validation errors, and reconcile missed or partial updates.
Related Martini documentation
Connect Mirakl with your enterprise systems
Use Martini to build reliable Mirakl integrations with REST APIs, selected event notifications, asynchronous marketplace operations, secure credentials, and maintainable workflows.