# Mirakl Connect APIs {% partial file="/partial-content/product/connect/rest/connect/openapi-description.md" /%} ## Servers Connect Production endpoint ``` https://miraklconnect.com/api ``` ## Security ### Bearer Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Mirakl Connect APIs](https://developer.mirakl.com/_bundle/content/product/connect/rest/connect/openapi3.yaml) ## Orders ### v2-acceptOrderLines - Accept or refuse order lines - [PUT /v2/orders/{order_id}/accept](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-acceptorderlines.md): Description Use this API to accept or refuse order lines that are in the AWAITING_ACCEPTANCE status, from Mirakl Connect. The API also synchronizes the order line status on the sales channel. Call Frequency Recommended usage: On each new order Maximum usage: On each new order ### v2-cancelOrderLines - Cancel order lines - [POST /v2/orders/{order_id}/cancel](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-cancelorderlines.md): Description Use this API to cancel order lines (all or part) of an order. Call Frequency Recommended usage: At each cancel request Maximum usage: At each cancel request ### v2-downloadOrderDocuments - Download documents from an order - [GET /v2/orders/{order_id}/documents](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-downloadorderdocuments.md): Description Use this API to download documents from an order. Call Frequency Recommended usage: On each order where we want to retrieve its documents Maximum usage: On each order where we want to retrieve its documents ### v2-uploadOrderDocument - Upload a document for an order - [POST /v2/orders/{order_id}/documents](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-uploadorderdocument.md): Description Use this API to upload a document for an order or its related entities (e.g. returns). Supported document types are : - RETURN_LABEL - CUSTOMER_INVOICE Call Frequency Recommended usage: On each document upload Maximum usage: On each document upload ### v2-getActionStatus - Track an asynchronous action request - [GET /v2/orders/actions/{action_id}](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-getactionstatus.md): Description Use this API to 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. Call Frequency Recommended usage: Asynchronous: every 5 minutes per action ID Maximum usage: Asynchronous: once per minute per action ID ### v2-listOrderDocuments - List documents - [GET /v2/orders/documents](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-listorderdocuments.md): Description Use this API to 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. Documents are returned as a flat list sorted by updated_at in descending order (most recent first). Call Frequency Recommended usage: When you need to retrieve documents for orders Maximum usage: When you need to retrieve documents for orders Pagination This resource supports seek pagination (see documentation) Sort fields sort field can have the following values:updated_at (Default) - Sort by document last update time (desc by default) ### v2-listOrders - List Mirakl Connect orders - [GET /v2/orders](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-listorders.md): Description Use this API to 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. To do so, schedule a task that calls this API using the updated_from parameter valued with the last execution time of the task. Call Frequency Recommended usage: Asynchronous: every 5 minutes Maximum usage: Asynchronous: once per minute Pagination This resource supports seek pagination (see documentation) Sort fields sort field can have the following values:updated_at (Default) - Sort by date time of last order modification in Mirakl Connect (desc by default)created_at - Sort by date time the order was created on the sales channel (desc by default) ### v2-refundOrderLines - Refund order lines - [POST /v2/orders/{order_id}/refund](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-refundorderlines.md): Description Use this API to refund order lines (all or part) of an order. Call Frequency Recommended usage: At each refund request Maximum usage: At each refund request ### v2-reportOrderActions - Log order action results and errors - [POST /v2/orders/actions](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-reportorderactions.md): Description Use this API to report to Connect the results of actions performed on orders in your system, such as synchronizing back orders. This enables enhanced error tracking while providing a centralized view of all order actions and errors within the Connect interface. We recommend integrating this API when developing a connector, such as for a CMS, to ensure comprehensive tracking of order actions and errors. This integration is optional if you process orders directly via the Connect API without using a connector. Call Frequency Recommended usage: Every 5 minutes Maximum usage: Once per minute ### acceptOrderLines - Accept or refuse order lines (deprecated) - [PUT /orders/{order_id}/accept](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/acceptorderlines.md): Description Use this API to accept or refuse order lines that are in the AWAITING_ACCEPTANCE status, from Mirakl Connect. The API also synchronizes the order line status on the sales channel. We recommend integrating this API in synchronous mode. Call Frequency Recommended usage: On each new order Maximum usage: On each new order ### listOrders - List Mirakl Connect orders (deprecated) - [GET /orders](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/listorders.md): Description Use this API to 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. To do so, schedule a task that calls this API using the updated_from parameter valued with the last execution time of the task. Call Frequency Recommended usage: Asynchronous: every 5 minutes Maximum usage: Asynchronous: once per minute Pagination This resource supports seek pagination (see documentation) Sort fields sort field can have the following values:updated_at (Default) - Sort by date time of last order modification in Mirakl Connect (desc by default)created_at - Sort by date time the order was created on the sales channel (desc by default) ### v2-getOrderTracking - Retrieve tracking information (deprecated) - [GET /v2/orders/tracking/{tracking_id}](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/orders/v2-getordertracking.md): Description This API is deprecated. Please use the new v2-getActionStatus API for retrieving the status of action request and potential errors. Call Frequency Recommended usage: Uses the new v2-getActionStatus API Maximum usage: Uses the new v2-getActionStatus API ## Conversations ### createConversation - Create a new conversation - [POST /conversations](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/createconversation.md): Description Use this API to initiate a new conversation with a customer on a marketplace. Returns an action identifier to track the asynchronous processing. ### listConversations - List all order conversations - [GET /conversations](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/listconversations.md): Description Use this API to synchronize Mirakl Connect conversations with your system. Pagination This resource supports seek pagination (see documentation) Sort fields sort field can have the following values:updated_at (Default) - Sort by date time of last conversation modification in Mirakl Connect (desc by default) ### createMessage - Create a message in a conversation - [POST /conversations/{conversationId}/messages](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/createmessage.md): Description Use this API to create a new message to the customer in a conversation. ### downloadConversationAttachments - Download attachments of a conversation - [GET /conversations/{conversationId}/attachments](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/downloadconversationattachments.md): Description Downloads a ZIP archive of the requested attachments from a conversation. ZIP archive contains all matching attachments with the following structure : ├── / │ ├── / │ │ └── │ └── / │ └── └── / └── / └── The zip file will be named with the following pattern : _attachments_.zip Unknown or deleted attachments are silently skipped. ### getConversationActionStatus - Get action status - [GET /conversations/actions/{actionId}](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/getconversationactionstatus.md): Description Use this API to check the status of your asynchronous conversation action. ### getConversationMessages - Get messages for a conversation - [GET /conversations/{conversationId}](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/conversations/getconversationmessages.md): Description Returns messages of a conversation, ordered by channel creation date descending. ## Shipments ### v2-createShipment - Ship items of a Connect order - [POST /v2/orders/{order_id}/shipments](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/shipments/v2-createshipment.md): Description Use this API to ship one or more items from the same order within the same package (using the same tracking information). Call Frequency Recommended usage: On each new shipment Maximum usage: On each new shipment ### createShipment - Ship items of a Connect order (deprecated) - [POST /orders/{order_id}/shipments](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/shipments/createshipment.md): Description Use this API to ship one or more items from the same order within the same package (using the same tracking information). We recommend integrating this API in synchronous mode, directly in your shipment creation process. Call Frequency Recommended usage: On each new shipment Maximum usage: On each new shipment ## Catalog ### deleteProducts - Delete products in bulk from your Mirakl Connect Catalog - [DELETE /products](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/catalog/deleteproducts.md): Description Use this API to delete one or more products using the product identifiers. Limitations: - Maximum 1000 products per request - For larger deletions, split into multiple requests Call Frequency Recommended usage: Asynchronous: every 5 minutes Maximum usage: Asynchronous: once per minute ### listProducts - List products from your Mirakl Connect catalog - [GET /products](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/catalog/listproducts.md): Description Use this API to retrieve products imported in your Mirakl Connect catalog. Items are sorted by product identifiers. Call Frequency Recommended usage: Synchronous: every 5 minutes Maximum usage: Synchronous: once per minute Pagination This resource supports seek pagination (see documentation) ### upsertProducts - Create or Update your Mirakl Connect Catalog - [POST /products](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/catalog/upsertproducts.md): Description 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. Any nullable field can be explicitly set to null in order to remove its value. Call Frequency Recommended usage: Asynchronous: every 5 minutes Maximum usage: Asynchronous: once per minute ## Returns ### v2-acceptReturn - Accept or refuse return - [PUT /v2/orders/returns/{return_id}/accept](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/returns/v2-acceptreturn.md): Description Use this API to accept or refuse a return that is in the REQUEST_INITIATED status, from Mirakl Connect. The API also synchronizes the return status on the sales channel. Call Frequency Recommended usage: On each new return Maximum usage: On each new return ### v2-acknowledgeReturnReception - Mark return as received - [PUT /v2/orders/returns/{return_id}/receive](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/returns/v2-acknowledgereturnreception.md): Description Use this API to marks the return as received to officially confirm physical reception of the item from the customer. The API also synchronizes the return status on the sales channel. Call Frequency Recommended usage: On each new return Maximum usage: On each new return ### v2-closeReturn - Mark return as closed - [PUT /v2/orders/returns/{return_id}/close](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/returns/v2-closereturn.md): Description Use this API to marks the return as closed after all necessary steps required by the marketplace or seller’s process are completed (e.g., refund, compliance check, restocking). The API also synchronizes the return status on the sales channel. Call Frequency Recommended usage: On each new return Maximum usage: On each new return ### v2-listReturns - List Mirakl Connect returns - [GET /v2/orders/returns](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/returns/v2-listreturns.md): Description Use this API to 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. To do so, schedule a task that calls this API using the updated_from parameter valued with the last execution time of the task. Call Frequency Recommended usage: Asynchronous: every 5 minutes Maximum usage: Asynchronous: once per minute Pagination This resource supports seek pagination (see documentation) Sort fields sort field can have the following values:updated_at (Default) - Sort by date time of last return modification in Mirakl Connect (desc by default) ### v2-updateReturnTrackingInformation - Update return tracking information - [PUT /v2/orders/returns/{return_id}/trackings](https://developer.mirakl.com/content/product/connect/rest/connect/openapi3/returns/v2-updatereturntrackinginformation.md): Description Use this API to update the tracking information of a return from Mirakl Connect. The API also updates the return tracking information on the sales channel. Call Frequency Recommended usage: On each new return Maximum usage: On each new return