---
title: Mirakl Connect API Integration on Truto
slug: miraklconnect
category: E-Commerce
canonical: "https://truto.one/integrations/detail/miraklconnect/"
---

# Mirakl Connect API Integration on Truto



**Category:** E-Commerce  
**Status:** Beta

## MCP-ready AI tools

Truto exposes 24 tools for Mirakl Connect that AI agents can call directly.

- **get_single_mirakl_connect_conversation_action_by_id** — Check the status of your asynchronous conversation action. Required: id.
- **list_all_mirakl_connect_conversation_attachment_contents** — Download attachments of a conversation as a ZIP file. Required: conversation_id. Returns a ZIP file, not JSON.
- **create_a_mirakl_connect_conversation_message** — Create a new message to the customer in a conversation. Required: conversation_id, message_input. Mirakl processes it asynchronously: the response has an action_id; check it with conversation_actions get.
- **list_all_mirakl_connect_conversation_messages** — List the messages of a conversation, newest first. Required: conversation_id.
- **create_a_mirakl_connect_conversation** — Initiate a new conversation with a customer on a marketplace. Returns an action identifier to track the asynchronous processing. Required: conversation. Mirakl processes it asynchronously: the response has an action_id; check it with conversation_actions get.
- **list_all_mirakl_connect_conversations** — Synchronize Mirakl Connect conversations with your system. The connector follows next_page_token through every page.
- **create_a_mirakl_connect_order_action_result** — Report to Connect the results of actions performed on orders in your system, such as synchronizing back orders. Required: actions.
- **get_single_mirakl_connect_order_action_by_id** — Check the status of an asynchronous action request (e.g., v2-acceptOrderLines) and retrieve any potential errors that occurred during the action processing. We recommend integrating this API asynchronously. Required: id.
- **list_all_mirakl_connect_order_document_contents** — Download documents of an order as a ZIP file. Required: order_id. Returns a ZIP file, not JSON.
- **create_a_mirakl_connect_order_document** — Upload a document for an order or its related entities (e.g. returns). Supported document types are : - RETURN_LABEL - CUSTOMER_INVOICE. Required: order_id, file, metadata. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **list_all_mirakl_connect_order_documents** — Retrieve documents across orders with pagination support. Each document in the response includes its associated order_id along with metadata such as name, type, size, and last update date. The connector follows next_page_token through every page.
- **mirakl_connect_orders_approve** — Accept or refuse order lines in AWAITING_ACCEPTANCE. Required: order_id, order_lines. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **mirakl_connect_orders_cancel** — Cancel order lines (all or part) of an order. Required: order_id, cancelations. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **list_all_mirakl_connect_orders** — Synchronize Mirakl Connect orders with your system. We recommend integrating this API in asynchronous mode. You can retrieve all orders updated since the last call, and update your referential accordingly. The connector follows next_page_token through every page.
- **mirakl_connect_orders_refund** — Refund order lines (all or part) of an order. Required: order_id, refunds. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **mirakl_connect_products_bulk_delete** — Delete one or more products using the product identifiers. Limitations: - Maximum 1000 products per request - For larger deletions, split into multiple requests. Required: products.
- **list_all_mirakl_connect_products** — Retrieve products imported in your Mirakl Connect catalog. Items are sorted by product identifiers. The connector follows next_page_token through every page.
- **mirakl_connect_products_bulk_upsert** — Products are created if they do not already exist. The missing fields in the request remain unchanged on the Mirakl Connect catalog (behaves like a PATCH). Omitted top-elements in the API will remain unchanged.
- **create_a_mirakl_connect_return_tracking** — Set the tracking information of a return (replaces what is there). Required: return_id. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **mirakl_connect_returns_approve** — Accept a return request. Required: return_id, accepted. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **mirakl_connect_returns_confirm** — Confirm that the returned items were received. Required: return_id. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **mirakl_connect_returns_close** — Close a return. Required: return_id. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.
- **list_all_mirakl_connect_returns** — Synchronize Mirakl Connect returns with your system. We recommend integrating this API in asynchronous mode. You can retrieve all returns updated since the last call, and update your referential accordingly. Required: updated_from. The connector follows next_page_token through every page.
- **create_a_mirakl_connect_shipment** — Ship one or more items from the same order within the same package (using the same tracking information). Required: order_id, items. Mirakl processes it asynchronously: the response has an action_id; check it with order_actions get.

## How it works

1. **Link your customer's Mirakl Connect account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app.
2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request.
3. **Call Truto's API to reach Mirakl Connect.** The Proxy API is a 1-to-1 mapping of the Mirakl Connect API.
4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field.

## Use cases

- **Centralize Marketplace Customer Support** — Helpdesk and customer service SaaS platforms can offer a Mirakl Connect integration so sellers managing conversations across hundreds of Mirakl-powered marketplaces can respond from a single unified inbox without logging into each portal.
- **Automate Multi-Marketplace Order Fulfillment** — Order and warehouse management SaaS platforms can ingest Mirakl Connect orders, push shipment tracking back to the marketplace, and handle cancellations or refunds programmatically — eliminating manual seller portal work.
- **Streamline Returns and RMA Processing** — Returns management SaaS platforms can sync marketplace returns, confirm warehouse receipt, and trigger approvals or closures to release buyer refunds without seller operations teams touching the Mirakl UI.
- **Power Catalog, Price, and Inventory Sync** — PIM, repricer, and inventory SaaS tools can push high-frequency stock and price updates into Mirakl Connect using bulk upserts, keeping listings accurate across every connected marketplace.
- **Build Marketplace Analytics and Operations Dashboards** — Analytics platforms can pull orders, returns, conversations, and documents from Mirakl Connect to give sellers unified reporting on GMV, SLA performance, and fulfillment health across their entire marketplace footprint.

## What you can build

- **Unified Marketplace Inbox** — Pull all buyer conversations and messages from Mirakl Connect into your UI and post agent replies back with async delivery confirmation via action polling.
- **Automated Shipment Notification** — Create shipments on Mirakl Connect the moment your warehouse scans a label, with tracking numbers and carrier info pushed directly to the marketplace.
- **Order Lifecycle Automation** — Programmatically approve, cancel, or refund marketplace orders based on your platform's business rules, with action ID tracking to confirm each state change.
- **End-to-End Returns Workflow** — Sync incoming returns, auto-approve low-value RMAs, confirm warehouse receipt, and close returns to trigger buyer refunds — all without touching the Mirakl portal.
- **Bulk Catalog and Inventory Sync** — Push high-frequency price and stock updates via bulk upsert operations, leveraging PATCH-style behavior to avoid overwriting untouched product fields.
- **Document and Attachment Retrieval** — Download order documents, return labels, and buyer-uploaded conversation attachments (delivered as ZIP archives) and surface them inside your product.

## FAQs

### How does Truto handle Mirakl Connect's asynchronous API pattern?

Mirakl Connect returns an action_id for most mutations (shipments, messages, order and return actions) rather than confirming success inline. Truto exposes the polling endpoints — such as get_single_mirakl_connect_order_action_by_id and get_single_mirakl_connect_conversation_action_by_id — so you can verify completion or capture errors after dispatching the original call.

### How are ZIP file downloads for documents and attachments handled?

Endpoints like list_all_mirakl_connect_order_document_contents and list_all_mirakl_connect_conversation_attachment_contents return binary ZIP payloads. Truto passes these through so your platform can extract invoices, return labels, or buyer-uploaded images without parsing them as JSON.

### How does pagination work for high-volume endpoints like orders?

Mirakl Connect uses token-based pagination. Truto's list endpoints (such as list_all_mirakl_connect_orders, list_all_mirakl_connect_returns, and list_all_mirakl_connect_conversations) expose next_page_token so you can run reliable scheduled syncs over large datasets.

### Can I run lightweight stock and price updates without resending full product data?

Yes. mirakl_connect_products_bulk_upsert behaves like a PATCH at the top-element level — omitted fields remain unchanged — so you can push high-frequency inventory and price syncs without resending full catalog descriptions.

### What order lifecycle operations are supported?

Truto supports listing orders, approving (mirakl_connect_orders_approve), cancelling (mirakl_connect_orders_cancel), refunding (mirakl_connect_orders_refund), creating shipments, and uploading or retrieving order documents — covering the full fulfillment and exception-handling flow.

### What's the right way to keep buyer conversations in sync with my helpdesk?

Poll list_all_mirakl_connect_conversations and list_all_mirakl_connect_conversation_messages on an interval appropriate to your SLA, fetch attachments via list_all_mirakl_connect_conversation_attachment_contents, and post agent replies with create_a_mirakl_connect_conversation_message — then confirm delivery through the conversation action endpoint.
